Moving to Hugo and GitLab pages
I’m guilty of having an online blog and not writing on it. I must confess that working on its looks and internals is much more fun for me than actually putting some words in plain English for everyone to read. But that is not the point, the content is the point of a blog.
This website has gone few visual updates over the years. Each time I decide to embrace new technologies(at least to me) and to work on top of somebody else’s work instead of trying again to do the design by myself. Today is a mayor step forward as I complete use a freely available theme instead of just using a web-framework for design my website. I can still read about the inner workings of the template, but I don’t need to know everything.
What inspired this change?
The idea of a static website is great and GitHub pages was offering a good environment for hosting my website. Except that:
- GitHub pages is only compatible with Jekyll
- Your custom domain cannot use HTTPS
Jekyll is not bad at all. I did find it quite an useful tool. However, I always found people complaining about it, and I wasn’t always very happy with it. When I started looking for alternatives, my first tendency was to use tools written in Python. Python is a great language, I work with it all the time. I found Pelican, Nikola, they both seem to do the job. But they have one problem, the themes. I’m not a web-designer, and I decided to just stop trying to make my website completely from scratch. Pelican, Nikola, and even Jekyll didn’t offer a large set of themes. Maybe they do, I just felt the offer was very limited and not what I was looking for.
This is where Hugo, came into the game. I had found references about it quite some times in web blogs. Its mayor advantage being speed, and it does seem to be true (although I don’t have a large website). I also found out that they offer native support for org files. Since I migrated to Emacs, I just love to work on org files. Hugo also offers a nice gallery of themes, I was fond of quite a few theme propositions. Finally, Hugo is written in Go, I don’t know it, but learning about something new is always good motivation and I decided to give Hugo a try.
I could host my new Hugo generated blog in GitHub, it is just pushing the static website to the repo. But I have been quite angry at GitHub and their services. For sure they host the largest amount of open source projects, and offer many tools to manage them, but they don’t seem to be moving forward in their services. On the other hand GitLab, being community driven seems to favor much more the needs of developers and to integrate their ideas into their services. Their web interphase does feel slower, and I have not yet collaborated in a project inside GitLab. But their integrated CI service is just fantastic. I can just make my docker images for my test environment and let the CI run on those, even better I can host the CI server myself and profit of a fantastic speedup in build times of my personal little projects in comparison to having them on TravisCI or the even better CircleCI. Also debugging my own docker image and GitLabCI environments has been by far the easiest compared to TravisCI(close to a nightmare) or CircleCI(quite fine because can SSH into CI server).
How about GitLab Pages? It’s great, you can use anything to build your webpage. You just use you custom CI environment and deploy the output. They offer plenty of examples on how to use their service for large variety of website generators. You can do anything, you are not constrained to using a specific tool at a specific version with just a set of extensions. If you don’t like their prepared build environments, you can just do your own and work with it. Finally, you can use your custom domain and TLS certificate, you can use Let’s encrypt for this. GitHub falls short on the last one and having an HTTPS website is very important to me.
How was it?
Installing Hugo was extremely easy on my computer, it is available in the Archlinux repository. Just by following the quick start guide for Hugo I could experience how it works and tryout many of their available themes. Having examples is probably the most powerful documentation. I settled for the hugo-tranquilpeak-theme, and started looking for an image for the background, It is now a photo I took from the train stop. I like the view of trees, rail roads and a green light.
Although there is an Hugo importer from Jekyll, and I did use it, I preferred to redo the import by hand. I don’t have many pages anyway. I was easier that way as I ended up editing all the files anyway. Yes, I did the work twice. I first performed and import into a test directory where I would try Hugo. When I was happy about using this technology I did the import again inside my git repository containing my website. I just feel it is a better way to go, it is the repository holding my online presence and it makes sense for me now to keep the same repository, in spite of the fact that I’m changing my hosting provider and the technology that generates the site.
How about the killer feature of supporting org-mode files. Well I didn’t like it and chose not to use it. I did not settle for markdown either, org-mode in Emacs is just fantastic and I cannot let go. I preferred the workflow offered by the org exporter ox-hugo. I feel it provides a more intuitive way to write into my blog. Have can have a big org file with all the posts organized inside substrees and use org tags to define Hugo categories and tags. Then export the substree corresponding to a post into a markdown file that Hugo will process. Version control becomes replicated as I version control the source org file and the exported markdown, but I guess it’s just fine.
Getting Let’s Encrypt to work
This step included some guessing as the GitLab tutorial is focus on Jekyll website. But using Hugo did not increased the difficulty. I followed the instructions in their blog post with some variations. I first install certbot directly from Archlinux package manager.
sudo pacman -S certbot certbot-apache
Because I do not want to run this as root, I don’t need it anyway since I’m
doing the process manually, I create a folder where I can save the Let’s
letsencrypt_certs, and then call certbot for my domain.
mkdir letsencrypt_certs certbot certonly -a manual -d blog.example.com --work-dir letsencrypt_certs --config-dir letsencrypt_certs --logs-dir letsencrypt_certs
When I need to make the website available, I just save in the required HTML
file in the
static folder with the sub-folder structure as given by Let’s
Encrypt, which Hugo copies identically into the website.
certbot completes the certificate generation after the sites are
online. Finally paste into gitlab Certificate (PEM) the
and into Key (PEM) the