Install and Configure Gollum Wiki on Raspberry Pi
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.
If you haven’t already, install Git on your Raspberry Pi:
sudo apt-get install git
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.
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 email@example.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
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
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.
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
<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.
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