Gollum: Your Self-Hosting Setup and Management Guide

Gollum is a lightweight, self-hosted wiki system that uses Git repositories as its backend, making it an ideal choice for developers and system administrators who value version control and data privacy. Designed for simplicity, Gollum allows users to create, update, and manage markdown-based wikis with full customization and control. In this guide, we’ll walk through the installation, configuration, management, and advanced usage of Gollum to help you deploy a robust, self-hosted wiki.

Installing Gollum

📦 Docker/Docker Compose Setup

Docker simplifies the deployment of Gollum by encapsulating its dependencies into a container. Here’s how to set it up with Docker Compose:

1. Create a docker-compose.yml file with the following content:

version: '3.8'

services:

gollum:

image: gollum/ruby:latest

container_name: gollum

ports:

- "4567:4567"

volumes:

- ./wiki:/wiki

working_dir: /wiki

command: gollum --port 4567

This configuration maps your local directory ./wiki to the container's /wiki directory and exposes Gollum on port 4567.

2. Deploy the container using:

docker-compose up -d

This will start Gollum in detached mode, accessible at http://<server-ip>:4567.

3. Verify the container status:

docker ps

Ensure the gollum container is running.

🚀 Manual Installation

If you prefer a manual setup on a Linux server, follow these steps:

1. Install Ruby and build dependencies:

sudo apt update

sudo apt install -y ruby-full build-essential git

2. Install the Gollum gem:

gem install gollum

3. Initialize a Git repository for your wiki:

mkdir ~/wiki

cd ~/wiki

git init

4. Start the Gollum server:

gollum --port 4567

Gollum will now be accessible at http://<server-ip>:4567.

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

To serve Gollum through a domain name, configure Nginx as a reverse proxy:

1. Create an Nginx server block file:

sudo nano /etc/nginx/sites-available/gollum

2. Add the following content:

server {

listen 80;

server_name wiki.example.com;

location / {

proxy_pass http://localhost:4567;

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Proto $scheme;

}

}

3. Enable the configuration and reload Nginx:

sudo ln -s /etc/nginx/sites-available/gollum /etc/nginx/sites-enabled/

sudo nginx -t

sudo systemctl reload nginx

🔒 SSL/TLS Setup

Secure your Gollum instance with Let's Encrypt:

1. Install Certbot:

sudo apt install -y certbot python3-certbot-nginx

2. Obtain an SSL certificate:

sudo certbot --nginx -d wiki.example.com

3. Verify automatic renewal:

sudo certbot renew --dry-run

Logging and Debugging Gollum

🗃️ Enabling Debug Logs

Enable debug-level logging to troubleshoot issues:

1. Start Gollum with detailed logging:

gollum --verbose --port 4567

2. For Docker, check logs using:

docker logs gollum

📄 Viewing Logs

Access logs on the filesystem or via Docker:

• For manual installation: Logs will appear directly in the terminal where Gollum is running.

• For Docker: Use the docker logs command above.

🛠️ Troubleshooting Common Issues

1. Check if the Gollum server is running:

curl -I http://localhost:4567

2. Validate Nginx configuration:

sudo nginx -t

3. Investigate permissions on your wiki directory:

ls -ld ~/wiki

📤 Exporting Logs

Send logs to an external system like ELK Stack by forwarding Docker logs using tools like Filebeat or Fluentd.

Backup and Restore

🗂️ File-Based Backups

Since Gollum stores data in a Git repository, backup is straightforward:

1. Create a tarball of the wiki directory:

tar -czvf wiki-backup.tar.gz ~/wiki

2. Restore by extracting the archive:

tar -xzvf wiki-backup.tar.gz -C ~/

📅 Automated Backup Scripts

Set up a cron job for regular backups:

1. Create a script backup_gollum.sh:

#!/bin/bash

tar -czvf ~/wiki-backup-$(date +%Y%m%d).tar.gz ~/wiki

2. Make it executable:

chmod +x backup_gollum.sh

3. Add a cron job:

crontab -e

Add the following line to run daily at midnight:

0 0 * * * /path/to/backup_gollum.sh

Updating and Upgrading Gollum

⬆️ Updating Docker Images

Update your Docker container to the latest version:

1. Pull the latest image:

docker pull gollum/ruby:latest

2. Restart the container:

docker-compose down

docker-compose up -d

🛠️ Manual Updates

For manual installations, update the Gollum gem:

gem update gollum

🔍 Checking for Updates

Verify the installed version:

gollum --version

Compare it with the latest release on the Gollum GitHub page.

Leveraging Gollum’s Unique Features

🔧 Enabling APIs

Activate Gollum’s API for programmatic access:

1. Start Gollum with API support enabled:

gollum --port 4567 --allow-uploads

2. Interact with the API using curl:

curl -X POST -F "[email protected]" http://localhost:4567/upload

🌟 Advanced Configurations

1. Enable a custom CSS file for styling:

gollum --css custom.css

2. Add plugins for extended functionality:

gem install gollum-lib

Then restart Gollum to load the plugins.

Wrapping Up

Self-hosting Gollum empowers you with full control over your content while leveraging Git for versioning and collaboration. This guide provided actionable steps to install, configure, secure, and manage Gollum on your server. With its flexibility and advanced features, Gollum is an excellent choice for developers looking to build a private, customizable wiki. Start implementing the examples today to create your own powerful, self-hosted knowledge base!