Following on from last week’s post about how ikiwiki functions, and how it’s different from other wiki engines; here’s how to get started with it and what do do next.

I used git as the revision control system (RCS) for my installation, if you use a different RCS, then some of the detail below may not be accurate to your setup. i.e. where I mention git.

Installation

If you have administrative access to an ubuntu/debian server, then getting ikiwiki is as straight forward as:

sudo apt-get install ikiwiki

to create a wiki, run:

ikiwiki --setup /etc/ikiwiki/auto.setup

and this will prompt for the wiki name, RCS and the admin user’s name and password. A wiki specific setup file and repositories are automatically created in your home directory, and the wiki source folder is placed in your public_html folder. The automatic setup will also guess the wiki url from your computer’s hostname, and will return the url of your wiki. If this is correct, you can visit your new, blank, wiki straight away.

For Ubuntu 10.04 LTS, the repositories have ikiwiki version 3.2.0100122ubuntu. If you are running an older distributions that have very out-of-date packages for ikiwiki, some of the automatic wiki creation may not be available. In this case, you can still create a wiki by hand.

Post-Install

When the wiki is built (or rebuilt) from source, the setup file (ie. ~/<wikiname>.setup) contains all of the wiki meta data, the locations of the repositories and RCS and details of the plugins and the templates.

When changes are made to the wiki’s settings file, manually trigger a rebuild of the wiki by running:

ikiwiki --setup ~/<wikiname>.setup

To correct my install, I updated the admin_email, and changed the url value to match my setup; using a subdomain instead of a subfolder.

CGI-scripts

Many web servers are configured to not allow cgi scripts to be run outside of certain directories. If you are unable to get the web side editing to function, check that cgi-scripts are either allowed to run, or that ikiwiki.cgi is placed in the correct web directory. If you have to change the location of the ikiwiki.cgi script, updated both cgiurl and cgi_wrapper in the settings file, and rebuild the wiki.

Moving Repository location

Almost immediately after installing, I wanted to tidy up my home directory, and move all the git repositories elsewhere (you can also create your own installation rules using auto.setup as guide). It’s no more difficult than moving the repository (and/or source) folders where you’d rather they were and updating the setup file to match, but there are a couple of bits to watch out for.

Source Directory

It is possible to either move the source directory folder to a new location,

mv ~/<wikiname> /path/to/new/location/

or clone one in a new location from the repository,

cd /path/to/new/location/ git clone ~/<wikiname>.git

and update srcdir in the setup file.

However, if you clone a new repository, make sure that you manually copy the .ikiwiki folder to the new one. This contains configuration files, such as the user database, that are not propagated to other git repositories. Otherwise, you’ll need to register your admin username.

Repository

The repository can be either cloned from the source directory,

cd /path/to/new/location/ git clone --bare /path/to/<wikiname>

or moved to a new location,

mv ~/<wikiname>.git /path/to/new/location/

And update git_wrapper with the new location.

With either move or clone, the git origin remote in the source directory will no longer be pointing at the right path. Be sure to either edit the path in /path/to/<wikiname>.git/config (and on any working repositories) or run,

cd /path/to/<wikiname> git remote delete origin git remote add origin /path/to/new/location/<wikiname>.git

Destination Directory

There is no need to copy the contents of the destination directory, as the wiki will need to be rebuilt for the new location. Just remove the old files and update destdir, url, cgiurl and cgi_wrapper in the setup file and run,

ikiwiki --setup ~/<wikiname>.setup

Setup file

You can keep this wherever you like; the developer recommends putting it in ~/.ikiwiki/. Just use the new path when you run ikiwiki --setup /path/to/<wikiname>.setup.

Plugins

Plugins took me a little while to get my head around, and I still don’t quite understand the command line syntax, but by far the easiest way to administrate and activate plugins is through the web interface.

Go to your wiki and -> Preferences -> (log in if necessary) -> Wiki Setup. And the plugin selection is all set by tick boxes on the page.

It’s also possible to activate plugins by adding their name to the add_plugins variable in your setup file. Just rebuild the wiki to see the changes (web-side changes will automatically trigger a rebuild). All the plugin settings are also lower in the file.

Templates and Themes

Ikiwiki uses three different types of template,

  • Template variables, used to hold values that can be inserted into a page of template.

  • Template pages, which can insert common layout structures into any other page

  • and Template files, that are used to build and theme the wiki

(more detail here)

To alter that layout of your wiki, you will need to make changes to the template files. The basic set of template files are in the usr/share/ikiwiki/templates directory. To override the standard templates update the templatedir path in your setup file to the folder where you will put your replacement template files. This can be inside the wiki source (e.g. in the templates/ directory) or outside in another folder.

You need only copy across the template file that you change, if a file is not present in the specified template directory, a standard template will be used. However, no matter if you place your templates inside of outside the wiki source, you will have to manually rebuild the wiki for template changes. These do not trigger a rebuild automatically.

Put your CSS theming for the wiki in the local.css file in the root folder of you wiki source.