Introduction

Gollum is a Wiki-like engine that allows different kinds of formatting, mainly Markdown but also MediaWiki.

I am considering three use-cases:

  • local install on a workstation just to be able to display Markdown documents
  • server install
  • dockerized server install

Either install from source

Either install the needed packages to build the thing,

#apt -y install build-essential git ruby ruby-dev libicu-dev zlib1g-dev

problem is I did not figure out how to install some addons,

#apt -y install git ruby ruby-dev zlib1g-dbg zlib1g-dev libicu-dev make build-essential
#gem install bundle
#git clone https://github.com/gollum/gollum.git
#git clone https://github.com/sekhmeth13/gollum-tweaked.git
#cd gollum/
#git pull
#bin/gollum -v
#bundle install

Or install with gem

Or use gem to install system-wide Gollum & addons,

apt install ruby
gem install gollum

sate-of-the-art markdown formatting with better tables,

gem install github-markdown

and with the rugged adapter,

apt -y install cmake pkg-config
gem install gollum-rugged_adapter

optionally,

#gem install wikicloth # mediawiki formatting

create a user to run gollum (unless you are already inside a container),

useradd -m gollum

now switch back to user and check,

#^D
su - gollum

which gollum
gollum -v

GIT setup to handle the documentation

Setup the GIT profile that corresponds to the non-authenticated Gollum WUI: try to use some mailing-list address and shared name. You will be able to setup binding to some Directory Server afterwards anyway.

git config --global user.email "project@example.com"
git config --global user.name "ACME Project"

Create either a locally editable,

repo=operations
git init $repo/

or Setup a GIT bare repository.

Configuration

You can also use the config file to setup Wiki options and environment,

repo=operations
cd ~/
vi gollum.$repo.rb

wiki_options = {
  :live_preview => false,
  :allow_uploads => true,
  :allow_editing => true,
  :h1_title => true,
  :universal_toc => true
}

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

Precious::App.set(:environment, :production)

Notes.

  • Change allow_editing to false if you want your WUI to be read-only (and documents only maintained by GIT).
  • The allow_uploads option only works if you also enabled allow_editing so you might have to upload your images and other stuff to gitrepo/uploads/ manually instead.

Operations

as user on a workstation

as gollum on a server or container (possibly with matching UID with the docker host)

Eventually make some handy symlinks,

cd ~/
ln -s /var/lib/gems/2.3.0/gems/gollum-4.1.2/config.rb gollum.rb.dist
ln -s /var/lib/gems/2.3.0/gems/gollum-4.1.2

And enable it as user,

sudo vi /etc/rc.local

#!/bin/bash

repo=operations
su - gollum -c "nohup gollum $repo/ --config gollum.$repo.rb --adapter rugged --host 127.0.0.1 &"

sudo chmod +x /etc/rc.local
sudo /etc/rc.local
cat ~gollum/nohup.out
lynx -dump localhost:4567

Notes.

  • add --bare if you've choosen to create a bare GIT repo, and point to gitrepo.git/
  • --allow-uploads to enable the Upload button! (creates uploads/ into the git repo)
  • default port is 4567, you can change it with --port X
  • if you have tweaked the conf, eventually add --config config.rb
  • eventually specify the leading portion of the URL with e.g. --base-path /gollum

Check that you can now access the Markdown GUI,

http://SERVER_ADDRESS:4567/

Everything's fine? You can now proceed with the reverse-proxy setup.

Also provide some custom script to start it at boot time,

mkdir -p ~/bin/
vi ~/bin/run_gollum

#!/bin/bash

cd $HOME/
nohup /usr/local/bin/gollum $HOME/gitrepo/ --config gollum.gitrepo.rb --adapter rugged \
    > $HOME/gollum.gitrepo.log 2> $HOME/gollum.operations.error.log &

chmod +x ~/bin/run_gollum

sudo vi /etc/rc.local

echo -n starting Gollum as USER_HERE user...
su - USER_HERE -c '$HOME/bin/run_gollum' && echo ok

Editing the documents

You can now edit the documents with your editor of choice + git commit, either locally (workstation) or remotely (normal or bare through ssh).

Make sure you've got git available on your workstation and setup your GIT profile (if not already done),

git config --global user.email "your email"
git config --global user.name "your name"

Remote editing

Send your public SSH key (ssh-keygen && cat ~/.ssh/id_rsa.pub) to user_id_1000@dockerhost access list (~/.ssh/authorized_keys) and try to log into it without a password,

ssh user_id_1000@dockerhost

if that works, you're ready to maintain the Documentation tru GIT e.g.,

git clone ssh://user_id_1000@dockerhost/data/gollumprod/operations.git/
cd operations/

(edit/add files)

when finished, commit your changes and push to the hosted repository,

#git add or git commit -a
git commit
git push

References