Install and Configure Gollum Wiki on Raspberry Pi
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