.TH codeberg-pages-2 7 .SH NAME codeberg-pages-2 \- Codeberg Pages 2: Setting Up Subdomain for git-pages Back-end .SH AUTHOR Artyom Bologov .SH SYNOPSIS Codeberg Pages moved to a new back-end (git-pages.) This caused me some pain. But I’m now on the other side of it, and I want to share some gotchas. .SH TEXT .P So Codeberg Pages have finally moved to .UR https://codeberg.org/git-pages/git-pages git-pages back-end .UE . Which is nice, don’t get me wrong! It’s fast, it’s lean, it’s featureful. But… Codeberg Pages docs related to deployment are pretty obscure. .UR https://codeberg.org/Codeberg/Documentation/pulls/868#issuecomment-20688911 And the maintainers don’t feel like fixing this .UE . Thus this post: to explain my journey in setting up .UR https://scheme-index.aartaka.me scheme-index.aartaka.me .UE as a custom domain subdomain. .P I have to link to .UR https://docs.codeberg.org/codeberg-pages/using-custom-domain Codeberg Pages docs .UE for fairness. In case you can understand them all and set up your subdomain based on them, then nice! But I wasn’t able to get through them and had to experiment and make many mistakes in the process. Here’s what I did. .EX .P Important detail: I use Namecheap as my domain registrar and DNS provider. So some things in this post are specific to Namecheap. The notation is \fB@\fP for apex domain and \fBscheme-index\fP for the subdomain (just for the sake of example.) .EE .SH Create a Repository .P I’m not going to explain Git here. Just make a new repo on Codeberg. Don’t add a \fBpages\fP branch yet—it’d better be done later! .SH Subdomain: CNAME Record .P First, I needed to add some records. I already had \fBALIAS\fP record for the root of the website. I only had to add a \fBCNAME\fP pointing the domain to the right \fBcodeberg.page\fP subdomain: .P .in +4n .EX ALIAS @ codeberg.page. CNAME scheme-index scheme-index.aartaka.codeberg.page. .EE .in .P — DNS records to set up the subdomain .P I don’t use the \fBCNAME\fP for root domain (aartaka.me,) \fBcodeberg-pages (7)\fP because I also use it for email (section dns-email). \fBCNAME\fP conflicts with that. Thus \fBALIAS\fP. But \fBCNAME\fP is safe for subdomains! .SH More DNS Records .P You have to prove that you own the subdomain and that it’s deployed from the right repository. So \fB_git-pages-repository\fP record: .P .in +4n .EX TXT _git-pages-repository.scheme-index https://codeberg.org/aartaka/scheme-index.git .EE .in .P — Record authenticating you as a domain owner .P Another thing that docs recommend is setting up a \fBCAA\fP record. With scary values of \fBletsencrypt.org;accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/292520050;validationmethods=tls-alpn-01,http-01\fP and \fBletsencrypt.org;accounturi=https://acme-staging-v02.api.letsencrypt.org/acme/acct/272029763;validationmethods=tls-alpn-01,http-01\fP. However, Namecheap does not allow anything but domain in the \fBCAA\fP record. So mine looked like: .P .in +4n .EX CAA @ 0 issue "letsencrypt.org" .EE .in .P — The only CAA record Namecheap allows me to make .P It’s enough it seems. .SH (Optional) .domains File—Just to Be Safe .P I honestly have no idea what I’m doing here. .UR https://docs.codeberg.org/codeberg-pages/using-custom-domain/#step-2%3A-configure-git-pages-authorization:~:text=no%20longer%20necessary%20to%20have%20a%20%2Edomains%20file Codeberg Docs mention that .domains file is no longer necessary .UE . But I added it just in case: .P .in +4n .EX scheme-index.aartaka.me scheme-index.aartaka.codeberg.page pages.scheme-index.aartaka.codeberg.page .EE .in .P — My .domains file .P I guess just add it if something goes wrong? .SH Add a Forgejo Hook .P Finally, we can try deploying to the subdomain. This is done through the Forgejo webhook. .UR https://docs.codeberg.org/codeberg-pages/#getting-started-with-a-codeberg.page-url Codeberg docs explain it well enough .UE . One important gotcha: you should set the webhook target URL to the subdomain URL and not apex domain URL! So \fBhttp://scheme-index.aartaka.me\fP and not \fBhttp://aartaka.me\fP. I’m emphasizing this because I set it to the apex domain URL and it overwrote my main website. Whaaaaat. .P So the final webhook will look like: .TP .B Target URL http://scheme-index.aartaka.me (Notice the \fBhttp\fP—the first push should happen to an HTTP URL for git-pages reasons. You can change it to HTTPS after the first push.) .TP .B Branch filter pages .TP .B All the other fields Leave as-is, they are fine .SH Push and Enjoy! .P Now you can create a \fBpages\fP branch in the repository and make the first push. If everything is set up correctly, you website should be live in a couple of minutes. Don’t hurry too much though—things take time. Have patience. I didn’t have patience and look where it got me. .B Chat log showing my frustration .EX .P .in +4n .EX Hi y'all. I'm trying to deploy one of my projects to a subdomain from Codeberg repository consulting Codeberg Pages docs, and I seem to be getting something wrong. In a minute, I'll list what I did: [11:52] - Created a repository: https://codeberg.org/aartaka/scheme-index [11:53] - Created a .domains file with scheme-index.aartaka.me in it (should be unnecessary as per the docs) - Created an ALIAS record scheme-index codeberg.page. - Made a Forgejo hook to ping https://aartaka.codeberg.page/scheme-index/ [11:54] - Made another one to ping http://scheme-index.aartaka.me - Then fixed it to ping http://aartaka.me - Added _git-pages-repository.scheme-index TXT record with https://codeberg.org/aartaka/scheme-index.git in it [11:55] And it still fails to resolve at DNS stage, and when I ignore that, it fails with SSL errors I tried to set the CAA records, but Namecheap does not allow me to set anything but "letsencrypt.org" [11:56] So yeah, that's basically it. Anyone has ideas on what's wrong? Oh no, and now it fucked up https://aartaka.me [12:10] > Then fixed it to ping http://aartaka.me [12:17] This probably was the mistake that re-deployed scheme-index at https://aartaka.me But I triggeret the webhook in the main repository and now https://aartaka.me is back Can't say the same about scheme-index.aartaka.me: still unable to set it up [12:18] It works now. I'm going to send a patch to the docs. [12:23] .EE .in .P — Yeah, I annoyed people on #git-pages .EE .P I hope that your experience will be better than mine! Codeberg Pages deserve love and use. Smooth sailing with no icebergs in sight ⛵ .SH COPYRIGHT .UR https://creativecommons.org/licenses/by/4.0 CC-BY 4.0 .UE 2022-2026 by Artyom Bologov (aartaka,) .UR https://codeberg.org/aartaka/pages/commit/a91befa with one commit remixing Claude-generated code .UE . Any and all opinions listed here are my own and not representative of my employers; future, past and present.