Blog Setup

This is the steps I went through to set up this blog.

Research

What I wanted

After some browsing Hugo + Academic + Gitlab Pages has all the things I wanted

• No vendor lock in, I should be able to carry my stuff somewhere else
  • rules out all proprietary offerings
• Allows custom domain
  • rules out wordpress.com
• Works with my existing DNS setup
  • rules out Netlify
• Minimal maintenance even if I self-host
  • practically limit options to static site generators
• Large community usage so I get more documented features and bugfixes than alternatives
• Free as in beer
• Extra features and performance is nice
  • compared to plain gitlab/github pages

Note on subdomains

I found a very good explanation on the merits of having a www subdomain versus not. It seems for custom domains with a third-party providers, the subdomain has many benefits.

Problem with netlify

Hugo/Academic getting started guide recommends using Netlify for builds and deployment. Netlify wants to use their own DNS servers for good reason - they can easily do load balancing, cert renewals etc when they have DNS under control.

The problem is, I want to have:

1. HTTPS access through my custom domain
2. HTTPS auto cert renewal
3. Existing DNS server left alone (only add entries as needed)

Netlify will do either 1 and 2 or 1 and 3, but does not seem to support all 3.

Github and Gitlab pages does support all 3, so I ended up going with them.

A lesser annoyance with Netlify is the git-gateway requires read/write access to all repositories. This is a limitation of the Github Oauth2 permissions and Netlify not yet implementing access through the netlify github app (which actually has per-repository granularity), as explained here. This is not a major problem since I am the only one writing here so I don’t actually need this feature.

gitlab pages vs github pages

github pages serves the content of a git repository as the website assets.

gitlab pages does pretty much the same thing, but it has one major advantage: It can leverage gitlab CI for the build process, and serves the build artifact results as the website. This has two major benefits:

• Tight integration with Gitlab CI, with only ~20 lines of yaml needed to get automated builds and deploy, as documented here and here .
• There is no need to have separate repositories for the raw markdown files and the generated website. This is in contrast with github pages, where the academic deployment guide asks you to use submodules to also checkout the repository for the generted website.

Gitlab pages also can serve public pages from private repositories, so I can hide my embarassing editing history mistakes from the Internet :P

On the other hand, Gitlab Pages has problems generating TLS certs if the domain has more than one CNAME records. Github Pages does not seem to have this issue.

Implementation

Clone the academic-kickstart repository

Simply follow the new repository wizard in Gitlab by cloning from https://github.com/sourcethemes/academic-kickstart .

Configure academic and .gitlab-ci.yml

Two things are needed to start serving web pages:

• Add a .gitlab-ci.yml file. Note Academic template requires the full hugo-extended, so I end up using image: registry.gitlab.com/pages/hugo/hugo_extended:latest.
• in config/_default/config.toml, put the correct name of the domain in the baseurl parameter

Configure gitlab repository

Go to Settings > General > Visibility > Pages and enable Gitlab Pages for everyone.

Go to Settings > Pages and follow the instructions to add your domain.

To access the website directly from the top level domain, you need to add an A record instead of CNAME record. As of this writing the A record should be 35.185.44.232 .

Configure DNS and TLS

Configure the DNS server to add these:

• TXT record for verification
• CNAME record to redirect visitors to Gitlab’s servers.
• A record if you want top level domain to redirect to Gitlab’s servers.

Wait until the configs propagates then follow the instructions to generate TLS certs.