From 9e4e00d7d0dfda3056d5775a8a9190c366581efb Mon Sep 17 00:00:00 2001 From: crystal Date: Thu, 30 Oct 2025 17:05:41 +0100 Subject: [PATCH] improve custom domain examples (#557) - remove codeberg.page from .domains, it's redundant, the pages-server does not validate the .domains file for codeberg.page domains - add information for www-apex redirects to apex examples Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/557 Reviewed-by: Gusted Co-authored-by: crystal Co-committed-by: crystal --- .cspell.json | 3 +- content/codeberg-pages/using-custom-domain.md | 49 ++++++++++--------- 2 files changed, 27 insertions(+), 25 deletions(-) diff --git a/.cspell.json b/.cspell.json index 51e91d7..f4f5269 100644 --- a/.cspell.json +++ b/.cspell.json @@ -117,7 +117,8 @@ "accounturi", "Ente", "getent", - "sealioning" + "sealioning", + "DNSSEC" ], "ignorePaths": [ "**/node_modules/**/*", diff --git a/content/codeberg-pages/using-custom-domain.md b/content/codeberg-pages/using-custom-domain.md index a28d18d..cf36e75 100644 --- a/content/codeberg-pages/using-custom-domain.md +++ b/content/codeberg-pages/using-custom-domain.md @@ -19,12 +19,9 @@ The value of the CAA record would look like `letsencrypt.org;accounturi=https:// For custom domains, two things are required: -- a `.domains` file in the repository and branch where your files reside which you want to publish via Codeberg Pages. - The file should contain a list of _all_ domains that shall be usable to access that repository, - according to the following rules: +- a `.domains` file in the repository and branch where your files reside which you want to publish via Codeberg Pages. The file should contain a list of all external domains that shall be usable to access that repository, according to the following rules: - One domain per line, you can leave lines empty and comment out lines with `#`. - The first domain is the main domain, all other domains in the file will be redirected to the first one. - - The rest of the list includes all relevant `*.codeberg.page` domains for the specific repository. - a [DNS record](https://en.wikipedia.org/wiki/Domain_Name_System#Address_resolution_mechanism) pointing to one of the following targets, depending on where your static files reside: @@ -229,7 +226,7 @@ The following sub-sections include a few examples of the different alternatives, All considerations regarding a _Personal_ site also apply to an _Organization_ site, so these two cases will be addressed together. -### Personal (or Organization) site, third level domain +### Personal (or Organization) site, subdomain In this case, we want our _Personal_ pages available at the URL `https://myself.example.com`. @@ -237,14 +234,11 @@ The `.domains` file contains the following: ```text myself.example.com -frida.codeberg.page -pages.frida.codeberg.page -pages.pages.frida.codeberg.page ``` For the DNS configuration: -- if CNAME can be used, one single DNS record will suffice: +- if the domain is not the apex of the zone and does not have other services such as email, you should always use a CNAME record: - name `myself.example.com`, type `CNAME`, data `frida.codeberg.page` - otherwise, if ALIAS can be used, two DNS records will be needed: @@ -258,29 +252,33 @@ For the DNS configuration: ### Personal/Organization site, apex domain -In this case, we want our _Personal_/_Organization_ pages available at the URL `https://example.com`. +In this case, we want our _Personal_/_Organization_ pages available at the URL `https://example.com`. We also want the URL `https://www.example.com` to redirect to the apex domain. The `.domains` file contains the following: ```text example.com -frida.codeberg.page -pages.frida.codeberg.page -pages.pages.frida.codeberg.page +www.example.com ``` -For the DNS configuration, the CNAME SHOULD NOT be used, so: +_You may also put the `www` subdomain on the first line if you wish to use it as the canonical URL and redirect the apex domain instead._ -- if ALIAS can be used, two DNS records will be needed: +For the DNS configuration, CNAME records CANNOT be used for the apex domain, so: + +- if ALIAS can be used, three DNS records will be needed: - name `example.com`, type `ALIAS`, data `codeberg.page` - name `example.com`, type `TXT`, data `frida.codeberg.page` + - name `www.example.com`, type `CNAME`, data `frida.codeberg.page` -- otherwise, A/AAAA records must be used, together with one TXT record: +_Note that ALIAS records are not real DNS records and are typically incompatible with DNSSEC signed zones._ + +- otherwise, A/AAAA records must be used, together with a TXT record: - name `example.com`, type `A`, data `217.197.84.141` - name `example.com`, type `AAAA`, data `2a0a:4580:103f:c0de::2` - name `example.com`, type `TXT`, data `frida.codeberg.page` + - name `www.example.com`, type `CNAME`, data `frida.codeberg.page` -### Project site, third-level domain +### Project site, subdomain In this case, we want our _Project_ pages available at the URL `https://colormix-app.example.com`. @@ -288,13 +286,11 @@ The `.domains` file contains the following: ```text colormix-app.example.com -colormix.frida.codeberg.page -pages.colormix.frida.codeberg.page ``` For the DNS configuration: -- if CNAME can be used, one single DNS record will suffice: +- if the domain is not the apex of the zone and does not have other services such as email, you should always use a CNAME record: - name `colormix-app.example.com`, type `CNAME`, data `colormix.frida.codeberg.page` - otherwise, if ALIAS can be used, two DNS records will be needed: @@ -321,17 +317,22 @@ The `.domains` file contains the following: ```text example.com -colormix.frida.codeberg.page -pages.colormix.frida.codeberg.page +www.example.com ``` -For the DNS configuration, CNAME SHOULD NOT be used: +_You may also put the `www` subdomain on the first line if you wish to use it as the canonical URL and redirect the apex domain instead._ -- if ALIAS can be used, two DNS records will be needed: +For the DNS configuration, CNAME records CANNOT be used for the apex domain, so: + +- if ALIAS can be used, three DNS records will be needed: - name `example.com`, type `ALIAS`, data `codeberg.page` - name `example.com`, type `TXT`, data `colormix.frida.codeberg.page` + - name `www.example.com`, type `CNAME`, data `colormix.frida.codeberg.page` + +_Note that ALIAS records are not real DNS records and are typically incompatible with DNSSEC signed zones._ - otherwise, A/AAAA records must be used, together with one TXT record: - name `example.com`, type `A`, data `217.197.84.141` - name `example.com`, type `AAAA`, data `2a0a:4580:103f:c0de::2` - name `example.com`, type `TXT`, data `colormix.frida.codeberg.page` + - name `www.example.com`, type `CNAME`, data `colormix.frida.codeberg.page`