This document is an older, unmaintained guide. There may be a new guide available for this software.
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.
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:
## 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.
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://bucknell.com/~squire/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, bucknell is the machine's hostname, squire 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 the config file ~/wiki.setup as needed. If the automatic wiki setup is not ideal for your use case, we recommend manual 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://library.linode.com/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:
[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://email@example.com/srv/git/wiki.git
In this example, squire is the username, colab.bucknell.net 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.
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.
[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://firstname.lastname@example.org/srv/git/wiki-admin.git
In this example, squire is the username, colab.bucknell.net 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.
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.
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/bucknell.net/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.
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.
This guide is licensed under a Creative Commons Attribution-NoDerivs 3.0 United States License.
Last edited by System on Friday, April 29th, 2011 (r1487).