Gollum is a simple wiki system built on top of Git. A Gollum Wiki is simply a git repository (either bare or regular) of a specific nature:
- A Gollum repository's contents are human-editable, unless the repository is bare.
- Pages are unique text files which may be organized into directories any way you choose.
- Other content can also be included, for example images, PDFs and headers/footers for your pages.
- May be written in a variety of markups.
- Can be edited with your favourite system editor or IDE (changes will be visible after committing) or with the built-in web interface.
- Can be displayed in all versions (commits).
As you'll note in the (real world) screenshot above, my requirements for a personal wiki are:
- Portable across my devices
- Supports images
- Full-text search
- Supports inter-note links
- Revision control
Gollum meets all these requirements, and as an added bonus, is extremely fast and lightweight.
Since Gollum itself offers no user authentication, this design secures gollum behind an oauth2 proxy, so that in order to gain access to the Gollum UI at all, oauth2 authentication (to GitHub, GitLab, Google, etc) must have already occurred.
Setup data locations¶
We'll need an empty git repository in /var/data/gollum for our data:
1 2 3
mkdir /var/data/gollum cd /var/data/gollum git init
- Choose an oauth provider, and obtain a client ID and secret
- Create gollum.env, and populate with the following variables (you can make the cookie secret whatever you like)
1 2 3
OAUTH2_PROXY_CLIENT_ID= OAUTH2_PROXY_CLIENT_SECRET= OAUTH2_PROXY_COOKIE_SECRET=
Setup Docker Swarm¶
Create a docker swarm config file in docker-compose syntax (v3), something like this:
I share (with my patreon patrons) a private "premix" git repository, which includes necessary docker-compose and env files for all published recipes. This means that patrons can launch any recipe with just a
git pull and a
docker stack deploy 👍
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
version: '3' services: app: image: dakue/gollum volumes: - /var/data/gollum:/gollum networks: - internal command: | --allow-uploads --emoji --user-icons gravatar proxy: image: a5huynh/oauth2_proxy env_file : /var/data/config/gollum/gollum.env networks: - internal - traefik_public deploy: labels: - traefik.frontend.rule=Host:gollum.example.com - traefik.docker.network=traefik_public - traefik.port=4180 volumes: - /var/data/config/gollum/authenticated-emails.txt:/authenticated-emails.txt command: | -cookie-secure=false -upstream=http://app:4567 -redirect-url=https://gollum.example.com -http-address=http://0.0.0.0:4180 -email-domain=example.com -provider=github -authenticated-emails-file=/authenticated-emails.txt networks: traefik_public: external: true internal: driver: overlay ipam: config: - subnet: 172.16.9.0/24
Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you're creating/removing stacks a lot. See my list here.
Launch Gollum stack¶
Launch the Gollum stack by running
docker stack deploy gollum -c <path-to-docker-compose.yml>
Authenticate against your OAuth provider, and then start editing your wiki!
Chef's Notes 📓¶
- In the current implementation, Gollum is a "single user" tool only. The contents of the wiki are saved as markdown files under /var/data/gollum, and all the git commits are currently "Anonymous"
Tip your waiter (support me) 👏¶
Did you receive excellent service? Want to make your waiter happy? (..and support development of current and future recipes!) See the support page for (free or paid) ways to say thank you! 👏
Flirt with waiter (subscribe) 💌¶
Want to know now when this recipe gets updated, or when future recipes are added? Subscribe to the RSS feed, or leave your email address below, and we'll keep you updated. (double-opt-in, no monkey business, no spam either - check the archive for proof!)