Blogging with Hugo and GitLab (3): Custom Domains

Give your blog website a custom domain to make it more professional and/or more fun.

Top-level domain

A top-level domain (TLD) is the last label of a domain name, for example, "com" of "www.example.com". For that same example, "example" is a second-level domain. With your blog website created and hosted in GitLab, it's associated with the second-level domain "gitlab.io" and can be visited at https://username.gitlab.io.

There is a wide variety of top-level domains today. Besides the most known ones like ".com" and ".net", you have the choice of other new interesting domains for your style such as ".lol", ".cat" and ".nyc". Some domains look strange to me, for example, ".fail" and ".wtf", and I wonder how they can be used (that said, there is one good example I really like, Algorithms.wtf, by a professor in UIUC).

Could top-level domains be free? Yes, but you only have five options and you won't be able to own it (though you can use it). Domains can be affordable as long as it's not a premium/popular name. Often time you can get one with around ten bucks for a year. It may even have discount for the first year ended up with less than one buck. To begin with, you will need to choose a domain name registrar. Here NameSilo is recommended.

Why NameSilo?

By looking around, I found NameSilo to be a domain name registrar with very good reputation (though its website looks old-fashioned). Its main advantage is the price--not only cheap, but also transparent. The price listed is what you pay (which may not be always true for other domain name registrars). For a new registration, there is the coupon NamesiloOneDollar to get $1 discount. Note that NameSilo does not offer SSL/TLS certificates (which means your website can only be visited at http:// but not https://). Fortunately, there are options that offer secure SSL/TLS for free.

Register a domain at NameSilo

To register a domain:

1. Go to NameSilo and search the name you would like to get.
2. Select the top-level domain (e.g., .com) you prefer and click "REGISTER CHECKED DOMAINS".
3. Set the configuration options as below:
   • "Service Link": None (default)
   • "NameServers": (leave it)
   • "Auto-Renew": No/Yes
   • "Privacy Setting": WHOIS Privacy
   • "Set all years to": 1/2/3/.../10 Note that for a domain with the first-year pricing promotion, the limit for registrations is 1 year. Upon registration, you will then be able to extend it for up to 10 years with the regular price.
4. Enter the coupon NamesiloOneDollar and click "Submit" to apply.
5. Click "CONTINUE -->" and choose the payment.

Link the domain with your website

The rationale behind the linkage of a domain and your website is to rely on the Domain Name System (DNS) which maps the domain to the IP address where the website is served. Configuration is needed on both sides:

1. Add the custom domain to GitLab.
2. Add the DNS records to the domain name registrar (e.g., NameSilo) and direct them to GitLab.

Add a custom domain to GitLab

1. Disable the forcing of HTTPS, since NameSilo does not provide SSL/TLS certificates.
   "Settings" > "Pages".
   Unselect "Force HTTPS (requires valid certificates)".
   Click "Save".

2. Add the root domain (e.g., loadbalancing.xyz).
   "Settings" > "Pages" > click "New Domain".
   "Domain": loadbalancing.xyz
   "Certificate (PEM)": (leave it blank)
   "Key (PEM)": (leave it blank)
   Click "Create New Domain".
   GitLab will then generate a DNS TXT record content (will be used later) like:
   _gitlab-pages-verification-code.loadbalancing.xyz TXT gitlab-pages-verification-code=...

3. Add the sub-domain (e.g., www.loadbalancing.xyz).
   "Settings" > "Pages" > click "New Domain".
   "Domain": www.loadbalancing.xyz
   "Certificate (PEM)": (leave it blank)
   "Key (PEM)": (leave it blank)
   Click "Create New Domain".
   GitLab will then generate a DNS TXT record content (will be used later) like:
   _gitlab-pages-verification-code.www.loadbalancing.xyz TXT gitlab-pages-verification-code=...

Add DNS records to NameSilo

1. Open the control panel of NameSilo.
   Click "domain manager".
   Click the domain you want to configure.
   Click "DNS Records: Update".

2. Remove all existing DNS A and CNAME records.

3. For the root domain (e.g., loadbalancing.xyz):
   Create a new A-type record.
   "HOSTNAME": (leave it blank)
   "TYPE": A
   "ADDRESS / VALUE": 35.185.44.232 (GitLab's IP address)
   "DISTANCE/PRIO" : NA
   "TTL": 3603
   click "SUBMIT".
   Create a new TXT/SPF-type record.
   "HOSTNAME": _gitlab-pages-verification-code
   "TYPE": CNAME
   "ADDRESS / VALUE": gitlab-pages-verification-code=...
   "DISTANCE/PRIO" : NA
   "TTL": 3603
   click "SUBMIT".

4. For the sub-domain (e.g., www.loadbalancing.xyz):
   Create a new CNAME-type record:
   "HOSTNAME": www
   "TYPE": CNAME
   "ADDRESS / VALUE": username.gitlab.io
   "DISTANCE/PRIO" : NA
   "TTL": 3603
   click "SUBMIT".
   Create a new TXT/SPF-type record:
   "HOSTNAME": _gitlab-pages-verification-code.www
   "TYPE": CNAME
   "ADDRESS / VALUE": gitlab-pages-verification-code=...
   "DISTANCE/PRIO" : NA
   "TTL": 3603
   click "SUBMIT".

Here we use different DNS records for the root domain and sub-domain (DNS A record and DNS CNAME record respectively). The DNS TXT records are required by GitLab to verify the domain's ownership.

After a couple of minutes, you will be able to visit your website from the new domain.