the road to activate Caspershire Meta

Published on 19 Mar 2017

I came a long way to get CasperMeta up and running. Eventually, CasperMeta works the way I initially intended it to be.

First I tested my theory of using Gogs as the web UI for editing my posts. After committing change(s), a git-hook post-update triggers Jekyll build command to generate a static HTML site, then served by Caddy webserver. When I tested on my Debian virtual machine, it worked beautifully. But when I tried on my Debian VPS, I ran out of hair to pull.

running Gogs

I chose Gogs because it is very light on resource (less than 30 MB for 1 repository). Running it is very simple since I only need to run the binary in tmux because I do not have a proper init script for it just yet, which I will. Since this Gogs instance aims to be light, I chose to run sqlite as the database backend with self-registration disabled (this is a private instance). I could not get to set up a proper SSL for git so for now all git pushes are through HTTP (shame, I know). However, the front-end is served through caddy with SSL enabled. Overall, the setup was indeed a breeze.

the pain: Jekyll

I did not expect this. At first when I tested my theory on my Debian VM, nothing weird happened after I pushed changes to the git repo. However here on the Debian VPS, I encountered an error with the Jekyll installation on the VPS.

remote: jekyll 3.4.2 | Error: the minima theme could not be found

The frustration of not being able to solve this error prompted me to find another static content generator (SCG) as an alternative, and I did. I tried Hugo.

Hugo: sort of works, but not quite

Here is my post-update hook that I used for Hugo instance.


rm -rf $PUBLIC_WWW/*

Hugo was installed via brew (Linuxbrew). After pushing changes, it worked fine. However, when use the caddy as the HTTP/2 webserver (with SSL enabled), the generated HTML was not properly rendered. I found out that this was due to the fact that all assets were hardcoded with HTTP url, thus making the website unusable to be served through HTTPS. There were workarounds but I decided to rethink my strategy.

finally, Jekyll works


At first I used the system’s ruby and gem on the VPS. I guess that’s what causing the problem. I ran brew command to install ruby, and then used the gem to install bundler. Here is an extra twist. On the VPS, I initialized a Jekyll instance just to make sure I have all the gems.

jekyll new dummysite

This command should pull everything. And then after it initialized a functioning Jekyll instance, I deleted it. And then I ran the same installation again.

  1. Create a repo through Gogs web UI
  2. Initialized a Jekyll instance in local computer
  3. Manually create post-update file in hooks folder
  4. Push changes

Here is the post-receive hook from my local Debian VM:


jekyll build -s $TMP_GIT_CLONE -d $PUBLIC_WWW

It should return this:

repos/metacs - [master] ยป git push origin master
Counting objects: 6, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 1.15 KiB | 0 bytes/s, done.
Total 6 (delta 1), reused 0 (delta 0)
remote: Cloning into '/home/user/tmp/metacs'...
remote: done.
remote: Configuration file: /home/user/tmp/metacs/_config.yml
remote:             Source: /home/user/tmp/metacs
remote:        Destination: /home/user/cms/metacs
remote:  Incremental build: disabled. Enable with --incremental
remote:       Generating...
remote:                     done in 0.137 seconds.
remote:  Auto-regeneration: disabled. Use --watch to enable.
   23bafa8..1f77c20  master -> master

No more errors! Lesson learned: do not use system’s ruby. Always install the one that does not require sudo. Some people use rbenv, some use rvm. And now that I can use Gogs web UI as the editor, my blogging life gets even more interesting!

the “but” with Jekyll

Since themes are now in the gem format, that’s a problem for me. I am not a wizard nor a ninja. The theming system in Hugo is much more consistent and pluggable, at least to me.

Remember that at first I was having hard time dealing with the Hugo to generate the static HTML properly. I found the actual problem. Let’s go to the site’s config.toml.

languageCode = "en-us"
title = "Caspershire Meta"
baseURL = ""
theme = "hugo-cactus-theme"

  post = "/:filename/"

Take a closer look at the baseURL. The protocol and the url must be the exact same and must end with a trailing slash. I did not put a trailing slash and that was what causing the HTML not to be properly generated because from that URL, Hugo generates absolute path to all assets.

update (March 20th): I changed my mind about gem

I did some readings on the recent changes about Jekyll using gem-based themes. It is logical and it makes sense. Previously the theming system kind of messing up the Jekyll root folder with bunch of files, distracting users from actually creating contents. With gem-based themes it is easier for users to manage theme files and contents separately.

The reason for using gem: it is easier for designers to push changes through the gem system and for the users to download the most recent update. In this regard, Jekyll wins because of the federated repository that simplifies the update process through gem/bundler command. However, I still prefer if Jekyll actually makes a subfolder in the Jekyll root directory that holds all of the theme files.

update (March 20th): sort post by date

I realized this hugo-cactus-theme does not sort posts by date. I opened the post-list.html file and I commit a simple change from this:

{{ range where .Paginator.Pages "Params.hidden" "ne" "true" }}

To this:

{{ range .Data.Pages.ByDate.Reverse }}

With a total disregard on what I might’ve broken.