Run Gollum Locally Using Pow

A quick guide that details how to setup and configure Gollum, a ruby app which turns a Git repository into a full-featured wiki with a robust API.

Setup Gollum

Initialize a repository

First, initialize a repository to serve the gollum app from. In this example, we will be naming the app wiki and serving it from the directory ~/Projects.

cd ~/Projects
mkdir wiki
cd wiki
git init

Setup application configuration options

Inside the folder gollum will be served from, create a file called config.ru which will be used to set ruby application configuration options.

touch config.ru

Open config.ru in a text editor and modify its contents to use bundler to serve gollum and to set some sound default options for gollum:

# config.ru
#!/usr/bin/env ruby
require 'pathname'

ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../Gemfile", Pathname.new(__FILE__).realpath)

require 'rubygems'
require 'bundler/setup'
require 'gollum/app'

# Setup gollum options
help_path = File.expand_path(File.dirname(__FILE__))
Precious::App.set(:gollum_path, help_path)
Precious::App.set(:default_markup, :markdown)
Precious::App.set(:wiki_options, {:universal_toc => false})

run Precious::App

Create a Gemfile and add the following lines:

source 'http://rubygems.org'

gem 'gollum'

Install gollum using bundler

Use bundler to setup the gem environment for the app:

bundle install

Note that for certain recent versions of OS X, Bundler may encounter an error installing the Nokogiri library that looks something like this:

An error occurred while installing nokogiri (1.6.8.1), and Bundler cannot
continue.
Make sure that `gem install nokogiri -v '1.6.8.1'` succeeds before bundling.

This is a common error that can be fixed by manually installing Nokogiri and telling bundler how to build it:

gem install nokogiri -v '1.6.8.1'
bundle config build.nokogiri --use-system-libraries

The bundle install command should now work.

Linking to pow

Now, link the newly created app to pow:

cd ~/.pow
ln -s ~/Projects/wiki

The gollum site will then be available locally at http://wiki.dev. If created using a different name, the pattern for the URL will be

http://[project-name].dev

Gollum Configuration Details

Some tips and tricks for configuring gollum.

Custom styling and views

Custom styles can be added to gollum by placing them in a file under the root directory called custom.css. Use gollum’s —css flag to load the file—if gollum is running as a rack app, use the option wiki_options[:css] = true to let gollum know that it should look for a custom css file.

Note: the custom.css file must be committed to the repository before changes will take effect.