I got a custom domain for my website: pawroman.dev

The .dev domains went live recently and are quite affordable. I like that Google decided to enforce HTTPS on every .dev website.

I managed to point my domain at GitLab pages hosted at gitlab.com. Read on for a quick guide.

Update (2020-03-29)

GitLab now handles Let's Encrypt certificates automatically, out of the box, including automated renewals. See their docs for more details.

Therefore, parts of this guide related to certificate setup are no longer relevant.

Setup procedure

To get my custom domain working with gitlab pages, I had to do a few things:

  1. Add an A record to DNS pointing to GitLab pages host.
  2. Setup a HTTPS certificate using Let's Encrypt.
  3. Verify the domain in GitLab.

This is also pretty well described in GitLab documentation.

Setting up DNS

When you buy a domain, the vendor usually gives you DNS functionality. You can modify the DNS settings right in the domain management panel.

To make our domain point at GitLab pages, we need to create a DNS A record. This type of record basically says this: this domain points at this IP.

For pages hosted on gitlab.com, the IP is 35.185.44.232, as described in their documentation.

Setting up HTTPS certificate

.dev domains must support HTTPS, and getting a free HTTPS certificate from Let's Encrypt is very easy using certbot.

Once certbot is installed (I used my PC running Linux), getting the certificate is quite easy.

To issue the certificate, the Let's Encrypt CA (Certificate Authority) needs to verify the domain really belongs to you. You can do this in a few ways, but in my case I went with adding a TXT DNS record to verify my domain, as described here.

After running:

sudo certbot certonly --manual --preferred-challenges=dns

And entering my domain, I was presented with the TXT entry to add to my domain DNS settings.

Adding this entry did the trick and the certificate files were stored on my disk under /etc/letsencrypt/live/pawroman.dev

Note that all these files are owned by root, because of their sensitive content (private keys etc).

Adding the domain to GitLab

GitLab can easily integrate custom domains, but to support HTTPS, it needs the certificate and the private key.

Usually, you want to keep such things private, but because all the content on my website is public, I had no issues with that.

I followed the procedure described here.

I simply copy-pasted the contents of /etc/letsencrypt/live/pawroman.dev/fullchain.pem into the Certificate (PEM) field in GitLab pages settings, and the contents of /etc/letsencrypt/live/pawroman.dev/privkey.pem into the Key (PEM) field.

The only thing left was to verify the domain, using a similar procedure to Let's Encrypt verification.

GitLab asked me to create a DNS TXT record with verification code, which I did and the domain verified successfully.

Wrapping up

All that was left was to update links to my page and change the page itself to advertise the new domain.

The only thing to follow up on is automating the certificate renewal. Let's Encrypt certificates expire relatively quickly (after 3 months). I will investigate options for automating the procedure, but for now I'm happy with the setup!

Feel free to bookmark pawroman.dev :)