sub1: notes for Ken

grebedoc.dev

“I own a domain. How do I serve static pages from Codeberg on a subdomain of my domain?”

  • On quarto, make a static website in the root of the repo, on branch pages. To do this, make sure _quarto.yml starts with this:
project:
  type: website
  output-dir: .

My procedure:

  • create a new Quarto website project in R Studio

  • create a new codeberg repo with the same name as the project

  • in R Studio, git checkout -b pages (branch must be called pages)

  • add and commit, but don’t push yet

  • follow the instructions on codeberg to add a remote and push to it, but use origin pages instead of origin main.

  • build the website, committing and pushing as necessary

  • open the DNS configuration page of your domain (mine is at namecheap and is called “advanced DNS”)

  • follow the instructions in “I own a domain. How do I serve static pages from Codeberg?” using method A (recommended by me). Include the webhook piece. At this point, your DNS configuration should have:

    • an A record with host @ and value the IPv4 address of grebedoc.dev;
    • an AAAA record with host @ and value the IPv6 address of grebedoc.dev (or the equivalent with ALIAS);
    • a TXT record at host _git-pages-repository and value that is the HTTPS clone URL of your repo that should appear at the root of your domain, such as https://codeberg.org/myusername/myrepo1.git.

  • Allow time for the DNS changes to propagate. To check that this has happened, you can run dig mydomain.com A and there should be an ANSWER section like this one, where the IP address at the end is grebedoc.dev’s: mydomain.com. 1790 IN A 185.187.152.7

  • At this point, visiting mydomain.com should display the static website in myrepo1.

  • Now create another static website, and push it to codeberg as repo myrepo2 (say). Suppose visiting sub1.mydomain.com is to display the static website in myrepo2. The steps below will make this happen.

  • set up a webhook in myrepo2 on codeberg as before, only this time the webhook should include the subdomain, such as http://sub1.mydomain.com.

  • in your DNS configuration, add a second TXT record. The host for this is _git-pages-repository.sub1 now with the name of the subdomain on the end, and the value is the HTTPS clone URL of the codeberg repo, such as https://codeberg.org/myusername/myrepo2.git. (Check whether you need to add .mydomain.com onto the end of your Host; on namecheap you do not.)

  • still in your DNS configuration, also add a CNAME record with host the name of your subdomain (sub1), and with value grebedoc.dev. with a dot on the end.

  • When these changes have propagated, you should be able to run dig sub1.mydomain.com CNAME and get an ANSWER section like this: sub1.mydomain.com. 1799 IN CNAME grebedoc.dev.

  • The TXT records are what authorize that you own the domain. You can also dig these to check that authorization is working:

    • dig _git-pages-repository.mydomain.com TXT should yield an ANSWER like _git-pages-repository.mydomain.com. 1799 IN TXT "https://codeberg.org/myusername/myrepo1.git"
    • dig _git-pages-repository.sub1.mydomain.com TXT should yield an ANSWER like _git-pages-repository.sub1.mydomain.com. 1799 IN TXT "https://codeberg.org/myusername/myrepo2.git".

  • As a final check, you can go to the webhook page for your codeberg repo myrepo2 and click “test delivery”. When it completes, you should see the test run “now” with a green checkmark on the left. If you click the blue ID (a hexadecimal number) you should see a 200 Response.

  • At this point, visiting sub1.mydomain.com should display the static website that is in myrepo2.

  • As a final note, this took me about three days, and several pieces of help, to get right, so I am writing it down to make sure I do not have to go through this again!