
\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}
<aartaka> 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]
<aartaka> - Created a repository: https://codeberg.org/aartaka/scheme-index
                                                                        [11:53]
<aartaka> - Created a .domains file with scheme-index.aartaka.me in it (should
          be unnecessary as per the docs)
<aartaka> - Created an ALIAS record scheme-index codeberg.page.
<aartaka> - Made a Forgejo hook to ping
          https://aartaka.codeberg.page/scheme-index/  [11:54]
<aartaka> - Made another one to ping http://scheme-index.aartaka.me
<aartaka> - Then fixed it to ping http://aartaka.me
<aartaka> - Added _git-pages-repository.scheme-index TXT record with
          https://codeberg.org/aartaka/scheme-index.git in it [11:55]
<aartaka> And it still fails to resolve at DNS stage, and when I ignore that,
          it fails with SSL errors
<aartaka> I tried to set the CAA records, but Namecheap does not allow me to
          set anything but "letsencrypt.org" [11:56]
<aartaka> So yeah, that's basically it.
<aartaka> Anyone has ideas on what's wrong?
<aartaka> Oh no, and now it fucked up https://aartaka.me [12:10]
<aartaka> > Then fixed it to ping http://aartaka.me [12:17]
<aartaka> This probably was the mistake that re-deployed scheme-index at
          https://aartaka.me
<aartaka> But I triggeret the webhook in the main repository and now
          https://aartaka.me is back
<aartaka> Can't say the same about scheme-index.aartaka.me: still unable to
          set it up [12:18]
<aartaka> 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}
