I recently decided to move this blog from octopress, hosted on a commercial site, to hugo, hosted on gitlab pages.

Why?

  • I don’t care that Octopress hasn’t been updated for a while but I do care that I didn’t understand what it was doing- I’m not a Ruby/Jekyll/Whatever person. I never took the time to understand how it worked under the hood, my bad.
  • I wasn’t using 99% of the facilities offered with the commercial host. Database? Nope. Wordpress? Nope. PHP? Perl? Email? Yes, need that. Also I loathe cpanel.
  • GitLab is lovely. Like GitHub but with more features.
  • I figured out how to configure and adapt hugo within a few hours of installing it.
  • I can deploy blog posts from my tablet if I want, using the mighty termux
  • Deployment is orders of magnitude quicker with hugo compared to octopress.

How?

Ah, this was the slightly tricky bit…

Conversion

I used octohug to do the conversion. Running hugo locally told me about various errors (mainly date formatting), so I fixed those. Not with anything clever, just with “find in files” in SublimeText.

Relative links (to other posts etc) had to be dealt with manually but that was quite easy to do.

Themes

Hugo has loads of themes, pick one from https://themes.gohugo.io/. If you choose to include your theme as a git submodule, then you’ll need to take that into account later when you deploy your site on GitLab.

To customise your chosen theme, you override the stylesheets with your own, so in my case I copied the standard css from my chosen theme and changed the basic colours to a more Edward Tufte Colour Scheme.

Deployment

GitLab deployment is slightly different to GitHub. There’s no concept of a gh-pages branch, as you’d need on GitHub. Instead, from the user documentation, you use GitLab’s Continuous Integration Pipeline to build a temporary server from docker and build your site from your raw code.

Huh?

It’s easy, don’t worry! There’s a basic file available on the hugo site. To include your theme as a git submodule though, you’ll need to get your server to install git and download the theme for you. Furthermore to do anything clever like adding search, you’ll need to get your server image to install the required software for that too. In summary, anything you do to run your site locally must be replicated in your GitLab pipeline. Here’s my config file.

Once it is all set up, you will be able to add to your site locally, commit it and push to your remote GitLab repository, where GitLab’s CI Pipeline will build and deploy it, in a matter of seconds.

Custom Domains

Cue a rabbit hole of dns management!

The documentation will get you most of the way there, but you’ll hit an issue with email, which I’ll cover later. If you want https (and you should), then generating a certificate with letsencrypt, using the Certbot client is very straightforward. Certbot asks you to publish a certain text file containing certain contents, in a specific location on your website, and once that is done (proving you own the site) it will issue you a certificate that you load onto GitLab.

But…

Email

How do you get email without a hosting plan? You have a couple of choices here- Amazon SES or something like Mailgun. I tried with Amazon, but ended up with Mailgun.

Setting up email requires more messing around with dns management. To verify you own the domain you’ll be required to add additional TXT records. You’ll then need to add CNAME and MX records as well. The important thing to note here is that CNAME records override MX records, and if you’ve followed the GitLab instructions to the dot, you will have a CNAME record pointing at yoursite.gitlab.io, which will break your MX records. You can remove that gitlab CNAME record with no ill-effect as far as I can tell (YMMV).

If you use Mailgun, you can then set up email forwarding to the account of your choice. If that choice happens to be google, then there are plenty of instructions like this one.

But…

Gmail will want to verify your new email account when you set it up, and you won’t be able to receive the email! To get around this, initially set your Mailgun forwarding route to a different email address. Allow Gmail to send the verification email, which will get routed via Mailgun to your secondary address. Clicking the confirmation link might not work, but you should be able to copy the verification code and add it in the verification interface. Once the account is verified with Gmail, you should be able to set the forwarding route in Mailgun to your preferred email address, and be able to send and receive emails from your custom domain.

Now you can sit back and have a nice cup of tea!

Still to do

I’d like to have comments on the blog, but probably not Disqus, because I’d prefer something self-hosted that doesn’t track people. I’m probably going to try isso.

I need a wildcard certificate for my ssl, because… domain stuff