Ikiwiki on Ubuntu 9.10 (Karmic)

Updated Friday, June 1, 2018 by Linode Written by Linode

Deprecated

This guide has been deprecated and is no longer being maintained.

Unlike some other popular wiki engines, Ikiwiki compiles static HTML pages which can be efficiently served with a basic web server. These are generated from a source directory that can be stored in the version control system of your choice, though this guide assumes that you use git.

This guide is written for Ubuntu 9.10 (Karmic), and assumes that you’ve followed our getting started guide and have a running and updated system. Additionally, it is assume that you have a functioning Apache web server and a working installation of git.

Installing Ikiwiki

Before installing Ikiwiki, we must enable the universe repository. To enable universe, modify your /etc/apt/sources.list file to mirror the example file below. You’ll need to uncomment the universe lines:

/etc/apt/sources.list

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

## main & restricted repositories deb http://us.archive.ubuntu.com/ubuntu/ karmic main restricted deb-src http://us.archive.ubuntu.com/ubuntu/ karmic main restricted deb http://security.ubuntu.com/ubuntu karmic-security main restricted deb-src http://security.ubuntu.com/ubuntu karmic-security main restricted ## universe repositories deb http://us.archive.ubuntu.com/ubuntu/ karmic universe deb-src http://us.archive.ubuntu.com/ubuntu/ karmic universe deb http://us.archive.ubuntu.com/ubuntu/ karmic-updates universe deb-src http://us.archive.ubuntu.com/ubuntu/ karmic-updates universe deb http://security.ubuntu.com/ubuntu karmic-security universe deb-src http://security.ubuntu.com/ubuntu karmic-security universe

After updating this file, run the following commands:

apt-get update
apt-get upgrade --show-upgraded

We’re ready to install Ikiwiki and its dependencies using the following command:

apt-get install ikiwiki git-core build-essential libcgi-formbuilder-perl libcgi-session-perl

Now that you have Ikiwiki installed, we can move on to configuring it for use.

Automatic Ikiwiki Configuration

From the command line, you can issue the following command to generate a basic config file using Ikiwiki’s auto-setup script.

ikiwiki -setup /etc/ikiwiki/auto.setup

This will ask you a series of questions about file locations and the revision control system you want to use. We recommend using git. When it’s completed, it will generate the following output:

Successfully set up foo:
    url:         http://example.com/~username/wiki
    srcdir:      ~/wiki
    destdir:     ~/public_html/wiki
    repository:  ~/wiki.git
To modify settings, edit ~/wiki.setup and then run:
    ikiwiki -setup ~/wiki.setup

In this example, example is the machine’s hostname, username is the admin user specified in the setup process, and wiki is the name of the wiki you specified during setup. You will need to configure your web server to serve files in ~/public_html/wiki before this wiki will be accessible.

While the auto-setup script is great for getting up and running in a matter of moments, you are encouraged to examine and edit the config file ~/wiki.setup as needed. If the automatic wiki setup is not ideal for your use case, we recommend manual configuration.

Manual Ikiwiki Configuration

To help you begin a manual configuration, we’ve included a full-featured Ikiwiki configuration file for you to review and edit. This provides configuration options for common plugins and some additional comments. Issue the following commands to fetch this file:

cd ~/
wget -O ikiwiki.setup http://www.linode.com/docs/assets/655-ikiwiki.setup

If you do not use the auto creation script, you’ll need to create the “source directory” repository. For the sake of example, the source directory will be ~/wiki/. Issue the following commands to create the directory and repository:

mkdir ~/wiki/
cd ~/wiki/
git init

You’ll want to create an index or “home page” for your wiki in the index.mdwn file. When you’ve saved this file you’ll need to add it to the staging area and create the commit with the following commands:

git add index.mdwn
git commit -m "creating the initial index file for the wiki"

It’s important to set up a git repository that will be the “origin” repository for the source directory repository so that you will be able to clone and push from remote machines. We’ll create the “origin” repository in /srv/git/wiki.git/ using the following sequence of commands:

mkdir -p /srv/git/wiki.git/
cd /srv/git/wiki.git/
git init --bare

Edit the ~/wiki/.git/config file to create the remote repository so that it looks something like the following example:

~/wiki/.git/config

1 2 3 4 5 6 7 8

[core] : repositoryformatversion = 0 filemode = true bare = false logallrefupdates = true [remote "origin"] : fetch = +refs/heads/*:refs/remotes/origin/* url = /srv/git/wiki.git [branch "master"] : remote = origin merge = refs/heads/master

Now perform the first push using the following sequence of commands. This will update the “origin” repository with the first commit created above:

cd ~/wiki/
git push origin master

Read through the ikiwiki.setup file that you fetched above. It is located at ~/ikiwiki.setup. This file has been thoroughly commented to make it easy to configure Ikiwiki for your particular needs. Alter it to conform to your setup and to point to the correct locations of the various repositories created above. After the file is edited correctly, issue the following command:

ikiwiki --setup ~/ikiwiki.setup

This assumes the ikiwiki.setup file is located in the home directory of the current user. You may have to adjust the path in the command if your Ikiwiki configuration file is located elsewhere.

If you have git installed, you can now clone the repository that stores the content for your wiki to your local machine. Use the following command:

git clone ssh://username@colab.example.com/srv/git/wiki.git

In this example, username is the username, colab.example.com is the name of the host where the repository resides, and /srv/git/wiki.git is the location of the “bare” repository.

If Ikiwiki is configured correctly, when you do a git push to the remote repository a “post-update hook” will trigger Ikiwiki to refresh the wiki with the content contained in your commit.

Advanced Ikiwiki Setup

While all of the content of an Ikiwiki is stored under version control, the templates and configuration files are stored outside of the source directory. If you want to use git to store these files and track the versions of your configuration we recommend making an “admin” repository located in the ~/wiki-admin directory. This should reside next to the ~/wiki/ repository/directory where the wiki’s source directory is located. To create the directory and initialize the repository, issue the following commands:

mkdir ~/wiki-admin/
cd ~/wiki-admin/
git init

Move your ikiwiki.setup file into ~/wiki-admin/. You may also want to move the template files into the wiki-admin repository with the following command:

cp -R /usr/share/ikiwiki/templates/ ~/wiki-admin/

Add these files to the commit and create an initial commit object with the following commands:

git add .
git commit -m "templates and ikiwiki.setup"

The process for creating a bare repository to push/pull the wiki-admin git repository is very much like the process you use for creating the bare “remote” repository for the wiki/ content. To begin, create a bare remote repository:

mkdir -p /srv/git/wiki-admin.git/
cd /srv/git/wiki-admin.git/
git init --bare

Next, edit the ~/wiki-admin/.git/config file to set up the remote repository. Use the following example as a guideline.

~/wiki/.git/config

1 2 3 4 5 6 7 8

[core] : repositoryformatversion = 0 filemode = true bare = false logallrefupdates = true [remote "origin"] : fetch = +refs/heads/*:refs/remotes/origin/* url = /srv/git/wiki-admin.git [branch "master"] : remote = origin merge = refs/heads/master

Now you can perform the first push for the wiki-admin repository by issuing the following commands:

cd ~/wiki-admin/
git push origin master

You can clone the wiki-admin repository to your local machine with the following command (issued locally):

git clone ssh://username@colab.example.com/srv/git/wiki-admin.git

In this example, username is the username, colab.example.com is the name of the host where the repository resides, and /srv/git/wiki-admin.git is the location of the “bare” repository. When you push to this repository, you’ll need to issue a git pull from within ~/wiki-admin/ on your server so that Ikiwiki will be able to see the changes you’ve made. You may set up a post-update hook at /srv/git/wiki-admin.git/hooks/post-update to make sure that ~/wiki-admin stays up to date.

The wiki-admin repository is totally optional, however it will simplify backup and mirroring down the road and allow you to version the templates. If you think any of these features will be helpful in your use case, we encourage you to consider storing your files in this manner.

Using Ikiwiki

Once installed, using Ikiwiki itself is fairly straightforward. You can push content to the bare repository, and Ikiwiki will incrementally update the pages changed in that commit. You can also choose to update pages via the web-based interface. As a result, you may find that you don’t actually need to interact with the ikiwiki program very much.

Nevertheless, if you change a configuration option or a template and need to rebuild all pages in the wiki, issue the following command:

ikiwiki --setup ~/wiki-admin/ikiwiki.setup

In this command, ~/wiki-admin/ikiwiki.setup represents the path to your setup file.

You may find yourself wondering why there are so many git repositories for a single wiki. The setup with a remote “bare” repository allows Ikiwiki to avoid a situation where you might “push” content to a non-bare repository, which would cause the “working copy” of the “source directory” repository to get out of sync with the sequence of commits in the git database. In short, never push to a non-bare git repository.

Notes for Using Gitosis with Ikiwiki

If you’re using gitosis to manage the git repositories as described in the introduction to Git guide, there are a couple of configuration options for Ikiwiki that you’ll need to keep in mind as you’re setting things up. As gitosis needs to “own” the git repositories it manages, the gitosis user ends up executing post-update hook and wrappers, and as a result many Ikiwiki files need to be owned by the gitosis user. This should not present a concern as Ikiwiki’s scripts are designed to be run securely by untrusted users. This means running ikiwiki.cgi as mode “6755”. See the example Ikiwiki configuration file for details on how to configure this.

The files that needed to be owned by the gitosis user are the “destination” directory where Ikiwiki puts its output, the “source directory”, and the bare repository. Run the following commands to set this ownership.

chown -R gitosis:gitosis /srv/git/wiki.git
chown -R gitosis:gitosis ~/wiki/
chown -R gitosis:gitosis /srv/www/example.com/public_html/wiki

Change the paths as necessary and run those commands again to correct permissions errors if you’re having a permissions problem.

If you’re using gitosis, you will want to run Ikiwiki scripts and interact with the git repositories on the server as the git user in order to ensure that permissions stay set as needed. You can use the su (switch user) command to get a prompt as the gitosis user by issuing a command in the following format:

su --login gitosis

However, using the sudo command may prove more useful and flexible for some use cases. To issue a single command as the gitosis user, prefix that command with sudo -u gitosis. For example, to trigger Ikiwiki to refresh your wiki, use the following format:

sudo -u gitosis ikiwiki --setup ~/wiki-admin/ikiwiki.setup

If you need to drop into a prompt as the gitosis user for more complicated operations, issue the following command:

sudo -u gitosis -s

Beyond these basic considerations, using Ikiwiki with gitosis is no different than using Ikiwiki with more conventionally managed repositories.

More Information

You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.

• Ikiwiki Home Page
• Example Ikiwiki Deployments

Join our Community

Find answers, ask questions, and help others.

This guide is published under a CC BY-ND 4.0 license.