Operating System CentOS

How to Set Up a GitHub-Style Wiki With Gollum on AlmaLinux 9 or Rocky Linux 9

Install the Git-backed Gollum wiki on AlmaLinux 9 or Rocky Linux 9, run it as a systemd service and put it behind Nginx with password protection.

Gollum is a wiki that stores its pages as plain files in a Git repository. It began as the engine behind GitHub's wikis and gives you the same model on your own server: edit in the browser or with a text editor, and every change is a Git commit. This guide installs the current Gollum release (6.1) on AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9, runs it as a systemd service and puts it behind Nginx with a password.

CentOS 7 reached end of life in June 2024, and its Ruby 2.0 is far too old for Gollum, which now requires Ruby 2.6 or newer. The RHEL 9 family provides suitable Ruby versions in its own repositories.

Requirements

  • A server running AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9.
  • A user with sudo rights; the examples use deploy.
  • A DNS name for the wiki. The examples use wiki.example.com.
sudo dnf update -y

Step 1: Install Ruby and the build tools

RHEL 9 and its rebuilds ship Ruby 3.0 by default and offer newer versions as module streams. List what your system provides:

sudo dnf module list ruby

Enable the newest stream shown (3.3 was added in release 9.4) and install Ruby with its development headers:

sudo dnf module enable -y ruby:3.3
sudo dnf install -y ruby ruby-devel

Several of Gollum's dependencies contain C code that is compiled during installation, in particular rugged, the Git library binding, which needs CMake and the OpenSSL headers. Install the compiler toolchain and libraries:

sudo dnf group install -y "Development Tools"
sudo dnf install -y git cmake openssl-devel libicu libicu-devel zlib zlib-devel

Step 2: Install Gollum

Gollum is distributed as a Ruby gem:

sudo gem install gollum

The compilation step takes a few minutes. When it finishes, confirm the version and note where the executable was installed; the service file in Step 4 needs that path:

gollum --version
command -v gollum

On this family of systems the path is normally /usr/local/bin/gollum.

Step 3: Create a user and the wiki repository

Run the wiki under its own unprivileged account:

sudo useradd --system --create-home --home-dir /var/lib/gollum --shell /sbin/nologin gollum

A Gollum wiki is simply a Git repository. Create one with main as its branch, which is the branch Gollum serves by default (it falls back to master if main does not exist):

sudo -u gollum git init -b main /var/lib/gollum/wiki

Step 4: Run Gollum as a service

Create a systemd unit:

sudo vi /etc/systemd/system/gollum.service
[Unit]
Description=Gollum wiki
After=network.target

[Service]
User=gollum
Group=gollum
ExecStart=/usr/local/bin/gollum --host 127.0.0.1 --port 4567 /var/lib/gollum/wiki
Restart=on-failure

[Install]
WantedBy=multi-user.target

--host 127.0.0.1 matters. Gollum listens on all interfaces (0.0.0.0) by default and has no login of its own, so anyone who can reach port 4567 could edit the wiki. Bound to the loopback address, it is only reachable through the reverse proxy configured in the next step.

Start the service and enable it at boot:

sudo systemctl daemon-reload
sudo systemctl enable --now gollum
systemctl status gollum

Test it locally:

curl -I http://127.0.0.1:4567/

Step 5: Put Nginx with a password in front

Install Nginx and the htpasswd tool, then create a password file with a first user:

sudo dnf install -y nginx httpd-tools
sudo htpasswd -c /etc/nginx/wiki.htpasswd deploy
sudo chown root:nginx /etc/nginx/wiki.htpasswd
sudo chmod 640 /etc/nginx/wiki.htpasswd

Add more users with the same htpasswd command without -c. Create the site configuration:

sudo vi /etc/nginx/conf.d/wiki.conf
server {
    listen 80;
    server_name wiki.example.com;

    location / {
        auth_basic "Wiki";
        auth_basic_user_file /etc/nginx/wiki.htpasswd;

        proxy_pass http://127.0.0.1:4567;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

SELinux does not let Nginx open network connections to other services until you allow it:

sudo setsebool -P httpd_can_network_connect 1

Test the configuration, start Nginx and open the firewall:

sudo nginx -t
sudo systemctl enable --now nginx
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Open http://wiki.example.com/, log in, and Gollum offers to create the Home page. Because the password travels with every request, add a TLS certificate to the Nginx server block before using the wiki over the internet.

Step 6: Edit pages from the command line

Pages are ordinary files, so you can also write them in an editor and commit them. Gollum shows committed changes immediately; uncommitted files are not visible.

cd /var/lib/gollum/wiki
sudo -u gollum sh -c 'echo "# Server notes" > Server-notes.md'
sudo -u gollum git add Server-notes.md
sudo -u gollum git -c user.name="Deploy User" -c user.email="deploy@example.com" commit -m "Add server notes"

You can also clone the repository to another machine, work there and push back, exactly as with any Git repository.

Useful options and maintenance

Append options to the ExecStart line, then run sudo systemctl daemon-reload and sudo systemctl restart gollum:

  • --allow-uploads dir enables file uploads by drag and drop; files are stored under uploads/ in the repository.
  • --no-edit makes the web interface read-only.
  • --base-path wiki serves the wiki under /wiki instead of the site root.
  • --ref branch serves a different branch.
  • --config file loads a Ruby configuration file for settings that have no command-line option.

Markdown and RDoc work out of the box. Other markup formats need an extra gem, for example sudo gem install asciidoctor for AsciiDoc or sudo gem install org-ruby for Org files.

Update Gollum with sudo gem update gollum followed by a service restart. Back up the wiki by copying or cloning /var/lib/gollum/wiki; the repository contains every page and its full history.

If the service does not start, read its output with sudo journalctl -u gollum. If gem install fails while building rugged, cmake or openssl-devel is missing.

Frequently asked questions

Does Gollum have user accounts or permissions?

No. Gollum has no built-in authentication, which is why this setup binds it to the loopback address and lets Nginx ask for a password. Everyone who can log in can edit every page. The project documents integration with external single sign-on for more control.

Can I run Gollum in a container instead?

Yes. The project publishes an official image, gollumwiki/gollum, which avoids installing Ruby and compiling gems on the host. You mount the wiki repository into the container and still want a reverse proxy with authentication in front.

Can I serve an existing GitHub wiki with it?

Generally yes. A GitHub wiki is a Git repository of Markdown (or other markup) files; clone it into /var/lib/gollum/wiki as the gollum user and point Gollum at it. If its branch is not main or master, add --ref with the branch name.

Why are my new files not showing up?

Gollum reads pages from the Git history, not from the working directory. A file appears only after it has been committed on the branch Gollum serves.

Share story:

Continue reading other guides on How VPS.