\documentclass[12pt]{article} \usepackage[T2A,OT1]{fontenc} \usepackage[a4paper, top=20mm, bottom=20mm, left=20mm, right=20mm]{geometry} \usepackage[utf8]{inputenc} \usepackage[russian, english]{babel} \usepackage{tabu} \usepackage{hyperref} \usepackage{parskip} \usepackage{graphicx} \usepackage{tabularx} \usepackage[normalem]{ulem} \usepackage{float} \floatstyle{boxed} \restylefloat{figure} \usepackage{setspace} \onehalfspacing \author{Artyom Bologov \href{mailto:codeberg-pages-2@aartaka.me}{(email)}} \date{\today} \title{Codeberg Pages 2: Setting Up Subdomain for git-pages Back-end} \makeatletter \def\endenv{\expandafter\end\expandafter{\@currenvir}} \makeatother \begin{document} \maketitle \includegraphics[width=\textwidth,height=\textheight,keepaspectratio]{./assets/codeberg-pages-2.png} So Codeberg Pages have finally moved to \href{https://codeberg.org/git-pages/git-pages}{git-pages back-end}. 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. \href{https://codeberg.org/Codeberg/Documentation/pulls/868#issuecomment-20688911}{And the maintainers don't feel like fixing this}. Thus this post: to explain my journey in setting up \href{https://scheme-index.aartaka.me}{scheme-index.aartaka.me} as a custom domain subdomain. I have to link to \href{https://docs.codeberg.org/codeberg-pages/using-custom-domain}{Codeberg Pages docs} 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. \begin{quote} 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 \verb|@| for apex domain and \verb|scheme-index| for the subdomain (just for the sake of example.) \end{quote} \section*{Create a Repository} \label{repository} I'm not going to explain Git here. Just make a new repo on Codeberg. Don't add a \verb|pages| branch yet---it'd better be done later! \section*{Subdomain: CNAME Record} \label{subdomain} First, I needed to add some records. I already had \verb|ALIAS| record for the root of the website. I only had to add a \verb|CNAME| pointing the domain to the right \verb|codeberg.page| subdomain: \begin{figure}[h!]\begin{verbatim} ALIAS @ codeberg.page. CNAME scheme-index scheme-index.aartaka.codeberg.page. \end{verbatim}\caption{DNS records to set up the subdomain}\end{figure} I don't use the \verb|CNAME| for root domain (aartaka.me,) \href{run:codeberg-pages}{because I also use it for email (section dns-email)}. \verb|CNAME| conflicts with that. Thus \verb|ALIAS|. But \verb|CNAME| is safe for subdomains! \section*{More DNS Records} \label{more-dns} You have to prove that you own the subdomain and that it's deployed from the right repository. So \verb|_git-pages-repository| record: \begin{figure}[h!]\begin{verbatim} TXT _git-pages-repository.scheme-index https://codeberg.org/aartaka/scheme-index.git \end{verbatim}\caption{Record authenticating you as a domain owner}\end{figure} Another thing that docs recommend is setting up a \verb|CAA| record. With scary values of \verb|letsencrypt.org;accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/292520050;validationmethods=tls-alpn-01,http-01| and \verb|letsencrypt.org;accounturi=https://acme-staging-v02.api.letsencrypt.org/acme/acct/272029763;validationmethods=tls-alpn-01,http-01|. However, Namecheap does not allow anything but domain in the \verb|CAA| record. So mine looked like: \begin{figure}[h!]\begin{verbatim} CAA @ 0 issue "letsencrypt.org" \end{verbatim}\caption{The only CAA record Namecheap allows me to make}\end{figure} It's enough it seems. \section*{(Optional) .domains File---Just to Be Safe} \label{domains} I honestly have no idea what I'm doing here. \href{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}. But I added it just in case: \begin{figure}[h!]\begin{verbatim} scheme-index.aartaka.me scheme-index.aartaka.codeberg.page pages.scheme-index.aartaka.codeberg.page \end{verbatim}\caption{My .domains file}\end{figure} I guess just add it if something goes wrong? \section*{Add a Forgejo Hook} \label{hook} Finally, we can try deploying to the subdomain. This is done through the Forgejo webhook. \href{https://docs.codeberg.org/codeberg-pages/#getting-started-with-a-codeberg.page-url}{Codeberg docs explain it well enough}. One important gotcha: you should set the webhook target URL to the subdomain URL and not apex domain URL! So \verb|http://scheme-index.aartaka.me| and not \verb|http://aartaka.me|. I'm emphasizing this because I set it to the apex domain URL and it overwrote my main website. Whaaaaat. So the final webhook will look like: \begin{description}\item[Target URL] http://scheme-index.aartaka.me (Notice the \verb|http|---the first push should happen to an HTTP URL for git-pages reasons. You can change it to HTTPS after the first push.) \item[Branch filter] pages \item[All the other fields] Leave as-is, they are fine \end{description} \section*{Push and Enjoy!} \label{push} Now you can create a \verb|pages| 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. \paragraph{Chat log showing my frustration} \begin{quote} \begin{figure}[h!]\begin{verbatim} 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] \end{verbatim}\caption{Yeah, I annoyed people on #git-pages}\end{figure} \end{quote} I hope that your experience will be better than mine! Codeberg Pages deserve love and use. Smooth sailing with no icebergs in sight ⛵ \par\noindent\rule{\textwidth}{0.4pt} \href{https://creativecommons.org/licenses/by/4.0}{CC-BY 4.0} 2022-2026 by Artyom Bologov (aartaka,) \href{https://codeberg.org/aartaka/pages/commit/a91befa}{with one commit remixing Claude-generated code}. Any and all opinions listed here are my own and not representative of my employers; future, past and present. \end{document}