Setting up a dockerised Gollum wiki for your documentation needs

The problem: fragmented documentation

Documentation is critical for any technical project, yet managing it effectively poses several challenges:

Documentation scattered across multiple systems
Difficulty tracking version history of documentation
No single source of truth for project information
Complex setup requirements for documentation platforms
Limited customisation options
Inability to edit documentation with preferred tools

These challenges can lead to outdated information, knowledge gaps during team transitions, and wasted time searching for essential documentation.

Why it happens: common documentation pitfalls

Documentation fragmentation typically occurs due to:

Tool proliferation: Different teams adopt different documentation tools
Lack of integration: Documentation systems don't integrate well with development workflows
Accessibility barriers: Complex systems discourage regular updates
Missing version control: Many systems lack proper versioning capabilities
Customisation limitations: Documentation platforms often restrict styling and extensions

Solution approach: Gollum with Docker

Gollum, a Git-powered wiki originally built for GitHub's wiki system, offers an elegant solution when combined with Docker. This approach provides:

Git-based version control for all documentation
Simple, lightweight interface
Flexibility to edit content through both web UI and text editors
Customisation capabilities through Ruby configuration
Containerisation for easy deployment and management

Implementation: basic setup

Step 1: Create directory structure

Start by creating a directory for your wiki and the necessary files:

mkdir test-wiki && cd test-wiki
touch config.rb docker-compose.yaml
mkdir wikidata && git init wikidata

Step 2: Configure Docker Compose

Create a docker-compose.yaml file with the following configuration:

version: '3.7'

services:
  gollum:
    image: gollumwiki/gollum:master
    restart: always
    ports:
      - '4567:4567/tcp'
    volumes:
      - ${PWD}/config.rb:/etc/gollum/config.rb
      - ${PWD}/wikidata:/wiki
    command:
      - '--config=/etc/gollum/config.rb'

This configuration:

Uses the official Gollum Docker image
Maps container port 4567 to the same host port
Mounts your local configuration and wiki data
Uses your custom configuration file

Step 3: Create basic configuration

Set up your config.rb with basic customisation options:

module Gollum
  # to require 'my_adapter':
  Gollum::GIT_ADAPTER = "my"
end

wiki_options = {
  css: true,
  js: true,
}

Precious::App.set(:wiki_options, wiki_options)

This configuration enables custom CSS and JavaScript to be loaded by your wiki.

Step 4: Launch the container

Start your Gollum wiki with:

docker compose up -d

Your wiki should now be accessible at http://localhost:4567.

Solution enhancement: customisation

Problem: default wiki styling and functionality limitations

The default Gollum appearance and functionality may not meet your specific needs or match your organisation's branding.

Solution: custom CSS, JavaScript, and macros

Custom modules in configuration

Enhance the config.rb file with custom modules and macros:

module Gollum
  class Macro
    class AllPagesCopy < Gollum::Macro
      def render
        if @wiki.pages.size > 0
          '<ul id="pages">' + @wiki.pages.map { |p| "<li>#{CGI::escapeHTML(p.name)}</li>" }.join + '</ul>'
        end
      end
    end
  end
end

Note

After any changes to `config.rb`, restart the Gollum container:

docker compose restart

</div>

Custom styling

Create and commit custom CSS and JavaScript files to modify the wiki's appearance and functionality:

cd wikidata
touch custom.css custom.js
git add custom.css custom.js
git commit -m "Add custom styling and scripts"

Warning

Gollum only recognises files that are committed to Git. Uncommitted files will not be visible in the wiki interface.

Solution enhancement: multiple wikis

Problem: different teams need separate wikis

You may need to maintain separate documentation spaces for different teams, projects, or purposes.

Solution: multiple Gollum instances with port mapping

For each additional wiki, create a new directory with its own configuration, changing the port mapping in the docker-compose.yaml file:

version: '3.7'

services:
  gollum:
    image: gollumwiki/gollum:master
    restart: always
    ports:
      - '4571:4567/tcp'
    volumes:
      - ./config.rb:/etc/gollum/config.rb
      - ./wikidata:/wiki
    command:
      - '--config=/etc/gollum/config.rb'

The key change is mapping container port 4567 to a different host port (4571).

Streamlined management

Create a simple shell function to start all your wikis at once:

ds(){
    docker compose -f ~/wikis/personal/docker-compose.yaml up -d
    docker compose -f ~/wikis/professional/docker-compose.yaml up -d
    docker compose -f ~/wikis/travel/docker-compose.yaml up -d
    echo 'Docker containers successfully started.'
}

Add this to your shell profile to run all wikis with the ds command.

Solution enhancement: external editing workflow

Problem: changes made outside Gollum aren't immediately visible

When editing wiki files with external text editors, changes aren't shown in Gollum until they're committed to Git.

Solution: automated Git commits with cron

Set up a cron job to automatically commit changes:

*/1 * * * * bash /home/me/code/cron-scripts/gollum-wiki-commit-cron.sh > /home/me/.local/share/log/cron/wikicron 2>&1

Create a commit script that checks and commits changes in all wiki repositories:

#!/bin/bash
# gollum-wiki-commit-cron.sh

# List of wiki repositories to check
WIKIS=("/home/me/wikis/personal/wikidata" "/home/me/wikis/professional/wikidata" "/home/me/wikis/travel/wikidata")

for WIKI in "${WIKIS[@]}"; do
  cd $WIKI

  # Check if there are any changes
  if [[ $(git status --porcelain) ]]; then
    # Changes exist, commit them
    git add -A
    git commit -m "Automatic commit of external changes $(date)"
    echo "Changes committed in $WIKI at $(date)"
  else
    echo "No changes in $WIKI at $(date)"
  fi
done

This script runs every minute, checking each wiki repository for changes and automatically committing them.

Results: an integrated documentation system

This Dockerised Gollum setup addresses the key documentation challenges by providing:

Single source of truth: All documentation lives in Git repositories
Version control: Complete history of documentation changes
Flexibility: Edit through web UI or text editors
Customisation: Tailor the appearance and functionality to your needs
Simplicity: Lightweight system with minimal overhead
Multiple wikis: Separate spaces for different needs
Automation: Changes automatically visible regardless of editing method

Practical applications and benefits

This approach is particularly valuable for:

Development teams: Integrate documentation directly with your code workflows
Technical writers: Edit in your preferred markdown editor while providing a web interface for readers
DevOps teams: Document infrastructure in a version-controlled environment
Cross-functional teams: Maintain separate wikis with consistent structure and styling
Personal knowledge management: Track personal notes with version history

Potential improvements and next steps

While this solution addresses the core documentation challenges, further enhancements could include:

Implementing authentication and authorisation
Setting up a reverse proxy with SSL for secure access
Creating a central index for navigating between wikis
Developing additional custom macros for specific documentation patterns
Integrating with CI/CD pipelines for automated documentation updates

These enhancements will be covered in future articles in this documentation systems series.

Conclusion

Gollum with Docker provides a flexible, lightweight solution to common documentation challenges. By leveraging Git for version control, Docker for deployment, and simple automation for workflow enhancement, this approach creates a documentation system that works with your team's preferred tools while maintaining consistency and accessibility.

Whether you're managing documentation for personal projects, small teams, or larger departments, this approach offers a solid foundation that integrates seamlessly with development workflows while remaining accessible to all team members.