Github-Synchronized, Markdown-based, and Auth-Enabled Wiki System

Summary

In this post, I will introduce how to set up a personal Wiki system with the following features,

Github-Synchronized: All pages are synchronized on Github;
Markdown-based: All pages can be written in Markdown;
Auth-Enabled: Visitors can view and admins can view/edit.

Conclusion

I provide a ready-to-use Docker image.

sudo docker run \
-v ${PWD}:/home/wiki_repo \
-p 4567:4567 \
-e GITHUB_CLIENT_ID=xxx \
-e GITHUB_CLIENT_SECRET=xxx \
-e AUTH_EMAIL=fighternan@gmail.com \
--name wiki \
fighternan/auth_wiki:latest

There are three environment varibles you should set. GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are available once you set your Github OAuth App. See here for official tutorial. AUTH_EMAIL specifies the user who can edit the pages. Other users can only view the pages.

If you want to build your customized image. See my repo here and develop your images.

Details

Gollum

Gollum is a wiki using git as the back end storage mechanism and written mostly in Ruby. It is the wiki system used by the GitHub web hosting system. Gollum pages may be written in a variety of formats such as Markdown. See here for installation tutorial.

Github Wiki

For every Github repository, you can create a Wiki, which is separate from your main project. You can clone it, look at it, edit pages and structure, and push your changes back up. For example, I have a wiki repo here.

git clone https://github.com/FighterNan/FighterNan.github.io.wiki.git

Set up Your Wiki Service

Once you clone the Wiki repo and install Gollum, people can view and edit your pages through a Web GUI.

cd FighterNan.github.io.wiki && gollum

The system can be run without networks. Once you have Internet available, you can back them up though git push.

Authentication

You may want to share your Wiki but do not want others to edit the pages. omnigollum provides the authentication packages. Use the configuration below.

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 => true,
  :mathjax => true,
  :h1_title => true
}
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/var/www/htmllications/
    provider :github, 'Client ID', 'Client Secret'
  end,
  :dummy_auth => false,
  # If you want to make pages private:
  #:protected_routes => ['/private*'],

  # Specify committer name as just the user name
  :author_format => Proc.new { |user| user.name },
  # Specify committer e-mail as just the user e-mail
  :author_email => Proc.new { |user| user.email },

  # Authorized users
  :authorized_users => ["your_email@example.com"],
}
## :omnigollum options *must* be set before the Omnigollum extension is registered
Precious::App.set(:omnigollum, options)
Precious::App.register Omnigollum::Sinatra

Run your application again by gollumn --config auth.rb. The original script and post are available here.

Github OAuth App

You can achieve authentication through Github OAuth App without passing the password to the Wiki System. Follow the tutorial here and create your OAuth Apps.

Ready-to-Use Docker Image

Environment Issues are annoying and you do not want to configure them again from your MAC laptop to another Centos or Ubuntu server. You may also want to be lazy and configure things by one command.

Here comes the Docker. Use my images here. The arguments are set by passing the environment variables .