Play video

Prerequisite: Ruby

I recommend installing Ruby using a Ruby version manager. Rbenv is my preferred Ruby version manager for Raspberry Pi’s and full installation instructions are on their official GitHub page.

Prerequisite: Git

If you haven’t already, install Git on your Raspberry Pi:

sudo apt-get install git

Install Gollum

Gollum is just a Ruby gem, so if you’ve got Ruby installed it’s as easy as…

gem install gollum

Full installation instructions on the official Gollum GitHub repo.

Debugging: gem install gollum fails on ‘rugged’

Make sure you’ve got libgit2-dev, CMake and pkg-config installed:

sudo apt install libgit2-dev cmake pkg-config

Setup Gollum file storage

Gollum uses a git repo as its “backend”. This is convienient because I setup my personal wiki on GitHub therefor I can just clone the repo.

git clone git@github.com:JackLot/docs.git

If you don’t already have an initialized git repo, you can make one:

mkdir my-wiki
cd my-wiki
git init

Testing Gollum

This command will run Gollum in a synchronous process to test that we can access Gollum at 0.0.0.0:4567. The path to my git repository on my local system is /home/pi/docs, which is what I’ll use in the command below.

gollum /home/pi/docs/ --css

Additional CLI configuration options here

Additional Configuration

Automatically run Gollum on boot

After testing to ensure Gollum works and that you can edit/save files, we’ll create a process that automatically launches the Gollum webserver on boot. Instructions are adapted from the main Gollum wiki. This Digital Ocean article is also a great intro to systemd.

Create a gollum.service file in /etc/systemd/system folder with the following contents:

[Unit]
Description=Gollum wiki server
After=network.target

[Service]
Type=simple
ExecStart=/home/pi/.rbenv/shims/gollum <path-to-your-git-repo> --css
Restart=on-abort

[Install]
WantedBy=multi-user.target

Note: Replace <path-to-your-git-repo> with your git repository path.

The above file will be used by systemd to start the server. You’ll need to target the Gollum gem with it’s absolute path and also target the Gollum wiki repo by it’s absolute path on the system. As a reminder, system services run as root.

Start and check the status of the process. After executing this, also try to access the server at 0.0.0.0:4567 to ensure the permissions are good.

sudo systemctl start gollum.service
sudo systemctl status gollum.service

After verifying everything works, tell systemd to run gollum on boot

sudo systemctl enable gollum.service

More info about system vs user services

Auto-sync Gollum wiki files

Since gollum uses a git repo as a ‘backend’, everytime a change/addition/delete is made to the wiki gollum automatically commits it to the local repo. We’ll create a cron job to automatically push these commits to our remote git repo. This is useful not only if the same wiki is running on multiple machines, but also so that work isn’t lost if the local server fails.

Warning: Don’t rely on this script to automatically sync content when you have Gollum running on multiple machines backed by the same repo. Even though you might not touch the same file at the same time on those different machines, git will still not be able to do a fast-forward merge since Gollum automatically creates commits on the same branch your pulling. More info.

Create a file called sync.sh in the root directory of your Gollum repo with the following contents:

#!/bin/sh
 
cd /path/to/gollum/repo && git pull && git push

Note: The double apersand && is not a typo. See here

Make the file executable with chmod a+x sync.sh then test it by running ./sync.sh. If everything works commit the file.

Create a cron job that executes this sync.sh script every 15 minutes (good tool for verifying crontab time strings). Do this by running crontab -e to edit your crontab file and append the following line:

*/15 * * * * /home/pi/sync.sh

On save, crontab should update with your new job.

Cron troubleshooting

To check that the cron job ran you can check the system logs:

sudo grep -a 'sync.sh' /var/log/syslog

To get a nice log of the output you can edit the cron line as follows:

*/15 * * * * /home/pi/docs/sync.sh 1> /dev/null 2> /home/pi/docs/crontab_git_sync.err

Then you can cat crontab_git_sync.err to see the output of the sync.sh execution

Inspiration from this section comes from: Gollum Auto-sync Git Repository