Gollumとは

gollumとはgitで作られたwikiエンジンです。個人の環境に無料で立てられるwikiサーバーとしては、簡単に立てられ、またデザインや操作方法も非常にシンプルなので手軽に始められるのが特徴だと思います。

gitで動くので、gollumのインストール以外にDBなどの他のミドルウェアは必要ありません。gollumには認証機能がありませんが、--configオプションでBasic認証やOmniAuthを実装したrbファイルを指定できるので、簡易的な認証機能としては十分です。

以下のような人に向いているwikiエンジンだと思います。

手軽に個人環境にwikiサーバーを立ち上げたい
使い方はシンプルな方が良い
日本語の全文検索をしたい
グループで使用できて、作成・編集にだけ認証をつければ良い　→　URLさえ知ってれば誰でも見せたい
ある程度デザインは拡張できた方が良い
バックアップを自動的に取るようにしたい

環境情報

サーバー -> AWS EC2
os -> Amazon Linux AMI 2016.03.3 (HVM), SSD Volume Type
git version -> 2.9.0
ruby version -> 2.0.0p648
gollum version -> 4.0.1

事前準備

EC2にインスタンスを起動します。インスタンスの起動方法はこちらのサイトが参考になると思います。今回はお試しということで最小構成で起動します。なおOSにはAMIを使っています。

環境構築

Gollumに必要なパッケージをインストールしていくため、ローカル環境からsshでインスタンスにログインします。

gitのインストール

Gollumはgitで動いています。wikiを書いたmdファイルをgitリポジトリと管理するため、gitをインストールする必要があります。
EC2を立ち上げた時点でgitはインストールされていますが、バージョンが古いため最新バージョンのgitをインストールしなおします。

1.gitのインストールに必要なパッケージのインストール

yum -y install curl-devel expat-devel gettext-devel openssl-devel zlib-devel perl-ExtUtils-MakeMaker

2.gitのソースを取得してくる
インストール時点での最新バージョンが2.9.0だったため、ここでは2.9.0をインストールします。

wget https://www.kernel.org/pub/software/scm/git/git-2.9.0.tar.gz
tar zxvf git-2.9.0.tar.gz

3.ソースをコンパイルしてインストールする

cd git-2.9.0
sudo make prefix=/usr/local all
sudo make prefix=/usr/local install
git --version

gollumのインストール

次にgollum本体をインストールします。gollumはRubyGemsとして公開されているため、gemコマンドを使ってインストールしてきます。

1.gemでインストールするために、必要なパッケージをインストールする

yum -y install gcc gcc-c++ libicu-devel ruby-devel

2.Gollumのインストール

sudo gem install gollum —-no-ri —-no-rdoc
sudo gem install github-markdown

--no-r --no-rdocはインストール時にドキュメントファイルを無視するためのオプションです。私の環境では、インストールにかなりの時間がかかってしまい、我慢できなかったためこのオプションをつけましたが、外しても大丈夫です。

Gollumの起動

Gollumを立ち上げるために、gitリポジトリを作成する必要があります。
後々wikiを作成した際のユーザー名を表示するために、gitのconfigの設定もしておきましょう。
※configの設定はしなくても大丈夫です。

mkdir private-wiki
cd private-wiki
git init
git config --global user.name "Your name"
git config --global user.email your_address@example.com

コマンドラインから

ここまでで、gollumを立ち上げる準備は完了です。
起動は以下のコマンドです。

gollum

デフォルトのポートは4567なので、http://{ec2のパブリックDNS}:4567にアクセスすると以下の画面が表示されます。

適当に内容を入力してSaveを押すと以下のようにに入力内容が表示されます。

デーモン化する

毎回コマンドで起動するのは面倒なので、デーモンとして登録します。ここではUpstartを使って登録していきます。
Upstartの詳しい説明はこちらを参照してください。

1.設定ファイルを書く
vim /etc/init/private-wiki.conf

description "private-wiki"
author  "Hoge hoge"

start on runlevel [2345]
stop on runlevel [016]

chdir /home/ec2-user/private-wiki
exec gollum >> /var/log/gollum.log

respawn

2.initctlに登録する

sudo initctl reload-configuration

3.起動する

sudo initctl start private-wiki

4.終了する

sudo initctl stop private-wiki

Gollumのカスタマイズ

Gollumはシンプルなデザインが特徴ですが、やっぱり物足りないのでデザインを変更していきたいと思います。また、このままでは誰でも新規登録、編集ができてしまうので、ユーザーの認証を設定していきます。

なお、ここでカスタマイズした内容はGitHubにあげているので、よろしければ参考にしてください。

gollum-custom

デーモンからの起動時に以下の設定を適応するためには、デーモンの設定ファイル内のexec gollum >> /var/log/gollum.log部分を変更する必要があります。

デザインの変更

独自でデザインはcustom.cssというcssファイルを作成し、gollumリポジトリのトップディレクトリに配置することで、--cssのオプションを指定時に読み込んでくれます。
custom.cssはおくだけでなく、gitでcommitする必要があるので注意してください。

custom.cssを適用したイメージ

テンプレートの変更

gollumはテンプレートエンジンとしてmustacheを使用しています。そのため、mustacheファイルを編集すれば独自にヘッダーやフッターをつけることができます。

独自に変更したテンプレートファイルは、--template-dir {path-to-template}のオプションを指定することで、読み込ませることができます。

そこでまずはgollumで使用されているテンプレートファイルをすべてコピーします。
私のEC2の環境では以下のディレクトリにありました。

/usr/local/share/ruby/gems/2.0/gems/gollum-4.0.1/lib/gollum/templates/

templatesフォルダ配下のファイルはすべてコピーしてください。--template-dirは変更した一部のファイルだけを読み込むのではなく、templateファイル一式を読み込むパスを指定するオプションのようです。

閲覧ページはlayout.mastacheなので、このファイルを編集すれば独自のデザインに変更できます。

例）

layout.mastache

<body>
<div id="cust-header-wrapper">
    <div id="cust-header">
         <h1>Tech Knowledge</h1>
     </div>
</div>
{{{yield}}}
</body>

独自のテンプレートを適用したイメージ

OmniAuthを使った認証

gollumは独自に認証機能を持っていませんが、--config {path-to-configfile}のオプションを指定することで、認証を実現することできます。

認証はBasic認証で手軽にできますが、ここではOmniAuthを使ってGitHubと連携した認証にしてみたいと思います。

Basic認証の方法は以下のサイトが参考になると思います。

GitHubにOAuth設定をする

GitHubにログインし、Settings -> OAuth Applicationsを選択し、連携キーを発行します。
例）
・Application name -> Gollum private wiki server
・Homepage URL -> http://{EC2のパブリックDNS}:4567/
・Application description -> Gollum をOmniAuthするためのアプリケーション
・Authorization callback URL -> http://{EC2のパブリックDNS}:4567

これでClient IDとClient Secretが発行されます。

発行されたものを環境変数に登録します。

export GITHUB_OAUTH_CLIENT_ID="{Client ID}"
export GITHUB_OAUTH_SECRET="{Client Secret}"

upstartの設定ファイルなら以下のように指定できます。

env GITHUB_OAUTH_CLIENT_ID="{Client ID}"
env GITHUB_OAUTH_SECRET="{Client Secret}"

OmniAuthを行うために必要なパッケージのインストール

2.必要なパッケージを入れる

sudo gem install omnigollum
sudo gem install omniauth-github

3.config.rbを作成する

認証の処理はconfig.rbに記載します。
私はrubyは書けないので、config.rbの内容はこちらを参考にしました。

config.rb

Gollum::Page.send :remove_const, :FORMAT_NAMES if defined? Gollum::Page::FORMAT_NAMES

## Omni Auth
require 'omnigollum'
require 'omniauth/strategies/github'

wiki_options = {
  :live_preview => false,
  :allow_uploads => true,
  :per_page_uploads => true,
  :allow_editing => true,
  :css => true,
  :js => false,
  :mathjax => false,
  :h1_title => false,
  # Custom template files directory
  :template_dir => 'custom-template'
}

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

options = {
  # OmniAuth::Builder block is passed as a proc
  :providers => Proc.new do
    # Found https://github.com/settings/applications/
    provider :github, ENV['GITHUB_OAUTH_CLIENT_ID'], ENV['GITHUB_OAUTH_SECRET']
  end,
  :dummy_auth => false,

  # List the URL of the page if you wants to demand the certification from the specific page
  # :protected_routes => ['/private*'],

  # Add authorized users who you want to publish gollum site
  :authorized_users => ["sample@example.com"],
}

## :omnigollum options *must* be set before the Omnigollum extension is registered
Precious::App.set(:omnigollum, options)
Precious::App.register Omnigollum::Sinatra

解説

wiki_optionsには、起動時に使用したいオプションを指定できます。オプションの種類は公式のwikiを参考にしてください。

:protected_routesには、認証が必要なディレクトリを指定することができます。例えば["/private*"]と指定した場合には、privateディレクトリ以下にページを作成するときや編集する際に認証が必要になります。それ以外のページは認証を行わずに作成・編集することができます。
また、["/"]と指定した場合には、http://{ec2のパブリックDNS}:4567へのアクセス自体に認証が求められます。そのため、閲覧自体も制御したい場合には、["/"]と指定すると良いです。

:authorized_usersには、認証を許可するユーザーを指定してください。ここに指定されていないユーザーが認証を求めてきても、許可されません。

4.実行する

gollum --config config.rbで実行すれば、認証が必要な状態で実行されます。
認証はページの作成、編集時に求められます。ページを参照する分には認証が必要なく見ることができます。

作成、編集時には以下のようにGitHubの認証が求められ、認証が成功した時のみ編集画面へ遷移します。

よくある失敗

GitHubの認証画面からログイン後に以下の画面に遷移することがあります。

Authentication failed
Insufficient data from authentication provider, email not provided or empty

この場合はログインユーザーのメールアドレスがPublic emailとして公開されていないことが原因です。GitHubにログインし、個人設定の変更からPublic emailを:authorized_usersに指定してあるemailアドレスで公開してください。

バックアップの取得

Gollumはgitで動いているので、リモートリポジトリをgollumサーバーとは別なところに立てて、gollumのリポジトリに設定し、定期間隔でcommit&pushすることでバックアップを取ることが可能です。

EC2にlinux環境を立ち上げたなら、cronで定期実行する方法が考えられます。こちらが参考になると思います。

まとめ

簡単に立ち上げられるwikiサーバーとしては非常に使いやすく思いました。ただ、深い階層にwikiを作っていった場合に、一つ前の画面に戻るしかけがないのが気になりました。例えば/user/hoge/fuga/aみたいな状態でaのwikiを見た時にその一つ前のfugaに直接戻れると便利そうです。他のwikiによくあるパンくずリストがあると便利だと思いました。

あと、live-preview機能もあって、書きながらプレビューを見れるようでしたが、試してみたところ反映がうまくいっていないことも多く、また止まってしまいにっちもさっちもいかない状態になってしまった時もあったので、今は使っていません。

その点を除けば、シンプルに自由に使えるところが非常に気に入りました。