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
sudorights; the examples usedeploy. - A DNS name for the wiki. The examples use
wiki.example.com.
sudo dnf update -yStep 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 rubyEnable 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-develSeveral 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-develStep 2: Install Gollum
Gollum is distributed as a Ruby gem:
sudo gem install gollumThe 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 gollumOn 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 gollumA 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/wikiStep 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 gollumTest 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.htpasswdAdd more users with the same htpasswd command without -c. Create the site configuration:
sudo vi /etc/nginx/conf.d/wiki.confserver {
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 1Test 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 --reloadOpen 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 direnables file uploads by drag and drop; files are stored underuploads/in the repository.--no-editmakes the web interface read-only.--base-path wikiserves the wiki under/wikiinstead of the site root.--ref branchserves a different branch.--config fileloads 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.