Jocodoma

Joco's Tech Blog

0%

Setup Custom Domains for GitLab Pages with SSL/TLS Certificates

Posted on In , Disqus:
Symbols count in article: 4.5k Reading time ≈ 4 mins.

Goal

My goal is to set up a custom domain for my static site hosted on GitLab Pages with HTTPS protocol enabled.

  • Register a custom domain on Google Domains (jocodoma.com).
  • Obtaining SSL/TLS certificates from Let’s Encrypt (for subdomain, which is blog.jocodoma.com)
  • Setup DNS and the static site (on GitLab Pages) as a subdomain under the custom domain

References:

Google Domains

Register a Domain Name with Google Domains

There are couple of places where you can obtain domain names from. One of the famous domain name registrar is GoDaddy. In my case, I decided to go for Google Domains. Here is the comparison between two. Depending on your preference, you can get your domain name from any of domain name registrar.

Let’s Encrypt

Let's Encrypt is a non-profit certificate authority run by Internet Security Research Group (ISRG) that provides X.509 certificates for Transport Layer Security (TLS) encryption at no charge. The certificate is valid for 90 days, during which renewal can take place at any time. The offer is accompanied by an automated process designed to overcome manual creation, validation, signing, installation, and renewal of certificates for secure websites.

Obtain Let’s Encrypt SSL/TLS Certificate

In order to have my static site available under HTTPS with the custom domain I registered earlier, I will have to have a SSL/TLS certificate for the (sub)domain. GitLab Pages accepts certificates provided in the PEM format, issued by Certificate Authorities (CAs) or as self-signed certificates.

There are some certificate authorities that offer free certificates, aiming to make the internet more secure to everyone. The most popular is Let’s Encrypt, which issues certificates trusted by most of browsers. It’s open source, and free to use. GitLab has a tutorial on how to secure your GitLab Pages website with Let’s Encrypt.

The following steps is based on macOS High Sierra. For more information on different operating systems, please see CertBot instructions.

  • Step 1 - Install certbot by brew

    1
    2
    brew update && brew upgrade
    brew install certbot

  • Step 2 - Request a certificate for the (sub)domain (blog.jocodoma.com)

    1
    sudo certbot certonly -a manual -d blog.jocodoma.com --email admin@jocodoma.com

  • Step 3 - You’ll be prompted with a message to agree with their terms. Press A to agree.

  • Step 4 - CertBot will then prompt you with something similar to the following message.


    Do not press Enter yet. Let’s Encrypt will need to verify your domain ownership before issuing the certificate. To do so, follow the instructions to create three consecutive directories under your website’s root: /.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP/ and add to the last folder an index.html file containing the content referred on the previous prompt message:

    1
    Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb

    Note that this file needs to be accessed under http://YOUR.DOMAIN/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP to allow Let’s Encrypt to verify the ownership of your domain, therefore, it needs to be part of the website content under the repo’s public folder.

  • Step 5 - Add, commit, and push the file into your repo in GitLab. Once the pipeline passes, press Enter on your terminal to continue issuing your certificate. CertBot will then prompt you with the successful message.

Reference:

Renew Certificate

Let’s Encrypt certificates expire every 90 days and you’ll have to renew them periodically. To renew all your certificates at once, run:

1
sudo certbot renew

Delete Certificate

The following command will offer an index from which you can select the domain name to delete:

1
sudo certbot delete

You can also delete Certbot Certificate by Domain Name:

1
sudo certbot delete --cert-name example.com

Reference:

Setup Custom Domain for GitLab Pages

Back at GitLab, navigate to your project’s Settings > Pages, click New Domain.

Add your certificate to GitLab Pages

From your terminal, copy and paste the certificate into the first field Certificate (PEM):

1
sudo cat /etc/letsencrypt/live/blog.jocodoma.com/fullchain.pem | pbcopy

Copy and paste the private key into the second field Key (PEM):

1
sudo cat /etc/letsencrypt/live/blog.jocodoma.com/privkey.pem | pbcopy

Verify New Domain

After new domain is assigned to your GitLab Page, you should see a warning message saying This domain is not verified. You will need to verify ownership before access is enabled.

DNS CNAME Record

Back at Google Domains, navigate to DNS -> Custom resource records:

DNS TXT record

Verify Custom (Sub)Domain

Back to GitLab Page, click on Retry verification. Then, you should see the successful message as below: