Two weeks ago my blog was hosted on a 10$/mo vps instance in DigitalOcean, powered by a couple docker containers, running an ever dynamic Wordpress platform. Now it’s completely static, served from GitHub Pages servers free. What follows is a small experience reco/guide on how to make this happen.
Running on a small vps with wordpress was nice, but not inspiring: I moved there from (google)blogger platform, which at that time was one of the fastest ways to bootstrap a blog, seeking something, that is more editor/code/content friendly. After all, Wordpress, with the heritage of catering to bloggers around the world, was a promising platform to look at. The things that I was looking for included:
clean readable design/theme
easy to use editor, preferably wysiwyg
easy basics: tags, archive, search, comments, bio etc.
After getting a closer look it turned out that Wordpress is a very bare-bones platform: plugins+themes are the things that make it beautiful and functional. I spent a lot of time looking for a functional simple free themes/plugins that would make my blog look readable on both mobile and desktop. I found one, but ultimately I wasn’t happy with it. On top of that my vps docker system kept asking for more RAM to keep MySQL, Varnish and a couple NGinxs satisfied. It was the time I realized I need something way simpler and more developer - oriented.
Enter HUGO
HUGO is static pages generator, written in Go. It comes with a fast server, that takes about 30 MB mem to run on site of this size(which is not large, but not exactly empty either). You write your posts in markdown, which is currently what I breathe, and you can literally program you pages(with go-like syntax), should you really want to. You need to keep in mind everything is static in the end, thus, should you want your site to be responsive, you’ll have to use javascript.
Hugo has support for most things you’d want to have: tags(taxonomies), categories, metadata, templates for different types of content, ready to use themes and internationalization support. That being said support !== ready to use out of the box. In other words one can build pages that have all the features mentioned, using the framework, but you need to do the legwork… or not ).
TranquilPeak is an open-source theme that has most of the basics implemented for you, using hugo’s framework. You can easily extend it if you wish. Thus blog runs it, so feel free to look around, but there is a showcase available as well. I won’t talk much about it here, as the docs are quite exhaustive, suffices to say that the theme comes loaded with goodness like
The goal was to get my wordpress running on GitHub Pages, with a custom domain. I also prefer my content to be versioned separately from the framework, therefore I went with git worktrees workflow as described below.
As described here, use the exporter plugin to get your content out of wordpress.
I’ve hit problems right there, on step one: Fatal error: Class ‘ZipArchive’ not found in /var/www/html/wp-content/plugins/hugo-export.php on line 403 Solution: make sure you have zip installed and enabled(in php.ini) on your machine. php info would be you guiding light. I was running an old wordpress:4.6.1-fpm bare container hence apt-get was useless. If you are in the same or similar boat that I was - upgrade to latest wordpress:4.8.3-php7.0-fpm then use
docker-php-ext-install zip
inside the container. Restart the container - now it(export) should work.
Install tranquipeak theme
There were no problems for me doing this. Configuring the theme takes a while, especially if you decide to change fonts, highlights etc.
Test everything works by running hugo server or hugo to generate files.
Now host the thing on GitHub Pages, using this guide
I had several problems here where I could not select the branch to publish from on github, or my CNAME was not working. The remedy was to follow the steps and instructions exactly as prescribed by github, namely:
Create a new project.
Create the index.html page
Set your project to be GitHub pages in Settings.
Pull your project from GitHub.
Make sure you have latest git installed and follow the guide
I had a problem here where wit git worktree:
fatal: Refusing to point HEAD outside of refs/
solved, by updating to the latest git.
6 Add CNAME file, containing your domain name to your gh-pages branch root
Profit!
Hope this helps people, should they have trouble. Also, if you have problems following these instructions - let me know in comments.
PS: In my NGinx:Varnish:NGinx:Php-fpm:MySQL Wordpress setup I went overzealous on the HSTS header
# Set HSTS to 365 days
add_header Strict-Transport-Security "max-age=31536000; includeSubdomains; preload";
So now people, that visited my blog a year ago, and haven’t cleared their cache since, will be forced to https, which would yield nothing, since custom domains are not served through https yet from GitHub Pages. Oh well…
