Ikiwiki installation

Start by installing ikiwiki.

On archlinux, a package is available in AUR (not up to date unfortunately at the moment, but the PKGBUILD can be tweaked to get the latest version).

Add a system user named ikiwiki. It helps making a clear separation between the http user that serves the web pages (through lighttpd) and the git user that manages gitolite repositories.

$ sudo groupadd --system ikiwiki
$ sudo useradd --system -c 'ikiwiki user' -g ikiwiki -m -d /srv/ikiwiki ikiwiki

The first command creates a system group called ikiwiki. The second command creates a user named ikiwiki with the following properties:

Create a first ikiwiki instance

Before integrating git in the process, start by creating a ikiwiki instance which can already be put on the web. For that, two directories are required:

Note: from now on, commands prefixed by $ must be executed by the ikiwiki user. Basically, run those commands with sudo -u ikiwiki.

Create these directories:

$ mkdir /srv/ikiwiki/wiki.src
$ mkdir /srv/ikiwiki/wiki.http

And add some content to the wiki:

$ echo "Hello world!" > /srv/ikiwiki/wiki.src/index.mdwn

Run the ikiwiki command to dump an almost empty setup file (in /srv/ikiwiki/wiki.setup):

$ ikiwiki /srv/ikiwiki/wiki.src /srv/ikiwiki/wiki.http --dumpsetup /srv/ikiwiki/wiki.setup

Edit and tune the setup file to define (at least) the following options:

Rerun ikiwiki on the setup file to generate the website:

$ ikiwiki --setup /srv/ikiwiki/wiki.setup

Configure the webserver to serve /srv/ikiwiki/wiki.http as the url defined in the setup file.

Note: if the webserver can't read the html files generated by ikiwiki, it might be because the permissions are too restrictive. Edit the wiki setup file and set option umask to public.

Configure gitolite

Since gitolite manages repository access based on ssh keys, the ikiwiki user must have its own key. Create ssh keys for the ikiwiki user:

$ ssh-keygen -t dsa

The command above will create two files, /srv/ikiwiki/.ssh/id_dsa and /srv/ikiwiki/.ssh/, which are respectively the private and the public key.

Configure gitolite to create a new git repository and give access to this repository to the ikiwiki user. In the file conf/gitolite.conf of the gitolite admin repository, define the new repository for the wiki:

repo    wiki
    RW+ = ikiwiki

Copy ikiwiki's public key in keydir/ It is likely that the permissions of the key need to be corrected.

Connect ikiwiki and the bare git repository

First the source directory needs to be checked in git:

$ cd /srv/ikiwiki/wiki.src
$ git init
$ echo /.ikiwiki > .gitignore
$ git add .
$ git commit -m "initial commit"

Then the source directory can be connected to the bare repository that is under gitolite management:

$ git remote add origin git@localhost:wiki
$ git config branch.master.merge refs/heads/master
$ git config branch.master.remote origin

Finally, the source directory can be pushed into the bare git repository:

$ git push --all

Automatic ikiwiki regeneration

For ikiwiki to generate a git post-update hook, it must know the source directory is now checked into git. Modify the option called rcs in the wiki setup file:

The setup file has to be reloaded for the options related to git to appear:

$ ikiwiki --changesetup /srv/ikiwiki/wiki.setup

Edit again the wiki setup file and define the path of the git post-update hook that ikiwiki will generate:

Relaunch ikiwiki to generate the hook:

$ ikiwiki --setup /srv/ikiwiki/wiki.setup

For the hook to be automatically called, and to regenerate the html output accordingly, it must be linked to the bare git repository that is under gitolite management:

$ sudo -u git ln -s /srv/ikiwiki/hooks/ /srv/git/repositories/wiki.git/hooks/post-update


Any push to the git bare repository (respecting the typical workflow of gitolite) should now automatically regenerate the html output.