Ikiwiki is a very flexible wiki compiler. From a set of input pages it generates static html-pages and thus only requires a simple http-server. The input pages (the content) can be written in various markup languages: markdown, multimarkdown, Textile, reStructuredText, plain text and some others. Ikiwiki seamlessly integrates with version control and unlike many other wiki systems does not re-invent the wheel but rather uses already existing VCS (supported are Git, Subversion, Darcs, … full list of supported VCS).

The default markup language for creating content is markdown. This article uses markdown as it is easy to learn, readable in source form and generally a good idea1.

As for the VCS we stick with Git which is the default of Ikiwiki. For teams the use of Git allows for collaboration, tracking of the author information and many more.

While the generated html-pages only require a simple http-server the search-functionality of Ikiwiki is realised with Xapian/Omega which requires CGI-support. As for all but the smallest installations (only one or two users, few content) search is mandatory in my opinion (even for personal wikis search is advisable) and the setup of search will be described too.

The examples will use apache2 as the web server (but any webserver should work).

Outline of the Setup

This is the first article of a mini series that will guide through the installation of an example Ikiwiki. The following steps will be covered:

  • setup the wiki myiki with Ikiwiki using git backend and apache as the webserver for delivering the pages

  • create our first page

  • add search functionality to myiki

  • integrate myiki with a Xymon server

  • some theming to give Ikiwiki a more pleasant look

  • author/client machines that write content and use git push to publish

Ikiwiki Server Setup and create myiki

As the author of Ikiwiki (Joey Hess) is an active Debian developer there are always up-to-date packages in the Debian repositories.

Setup on Debian 7.6 (Wheezy), 64-bit, in a separate VM ikiwiki.local. [ Note: we do all this as user root to avoid permission problems and make the documentation leaner ]

  • use version from debian/exterimental (most current)

      # echo "deb http://ftp.debian.org/debian unstable non-free contrib main" >> /etc/apt/sources.list.d/ikiwiki.list
      // make sure we do not switch to "experimental" for our installation: 
       echo "APT::Default-Release "wheezy";" >> /etc/apt/apt.conf.d/70default-release
    
      # apt-get update
    
      // update 2014-11-07: use apt-pinning instead of `apt-get install -t unstable ikiwiki`
      // to avoid unstable packages to sneak in:
      // pin ikiwiki to unstable:
      # cat /etc/apt/preferences.d/ikiwiki
      Package: ikiwiki
      Pin: release a=unstable
      Pin-Priority: 999
    
      # apt-get install ikiwiki
    
      // result:
      # ikiwiki --version
      ikiwiki version 3.20140613
    
  • install a web server to serve the wiki later on

      # apt-get install -y apache2
      // enable userdirs
      # a2enmod userdir
      # service apache2 restart
    
  • ensure git is installed

      # apt-get install git
    

Here we switch to a normal user, to setup the wiki (in the sample this user is vagrant).

  • basic git preparations

      $ git config --global user.name "John Doe"
      $ git config --global user.email "jd@example.com"
    
  • basic configuration of ikikwiki:

      $ ikiwiki -s /etc/ikiwiki/auto.setup
      What will the wiki be named? myiki
      What revision control system to use? git
      Which user (wiki account or openid) will be admin? vagrant
    
    
      Setting up myiki ...
      Importing /home/vagrant/myiki into git
      Initialized empty shared Git repository in /home/vagrant/myiki.git/
      Initialized empty Git repository in /home/vagrant/myiki/.git/
      [master (root-commit) 7e7362a] initial commit
       1 file changed, 1 insertion(+)
       create mode 100644 .gitignore
      Counting objects: 3, done.
      Writing objects: 100% (3/3), 220 bytes, done.
      Total 3 (delta 0), reused 0 (delta 0)
      Unpacking objects: 100% (3/3), done.
      To /home/vagrant/myiki.git
       * [new branch]      master -> master
      Directory /home/vagrant/myiki is now a clone of git repository /home/vagrant/myiki.git
    
    
      Creating wiki admin vagrant ...
      Choose a password:
      Confirm password:
    
    
      ikiwiki-update-wikilist: cannot write to /etc/ikiwiki/wikilist
      ** Failed to add you to the system wikilist file.
      ** (Probably ikiwiki-update-wikilist is not SUID root.)
      ** Your wiki will not be automatically updated when ikiwiki is upgraded.
    
    
      Successfully set up myiki:
              url:         http://ikiwiki.local/~vagrant/myiki
              srcdir:      ~/myiki
              destdir:     ~/public_html/myiki
              repository:  ~/myiki.git
      To modify settings, edit ~/myiki.setup and then run:
              ikiwiki -setup ~/myiki.setup
    

Note: The warning from ikiwiki-update-wikilist can be ignored — it’s only relevant for multi-wiki setups (not covered here).

At this point we are ready to “compile” the default-wiki. The optional -v as usual gives a bit of extra output:

    $ ikiwiki -s myiki.setup -v

And now access http://ikiwiki.local/~vagrant/myiki/ to check what you have (replace vagrant by your user).

Our first Page

At this stage the generated content comes from a so-called underlay, defined in myiki.setup (it points to /usr/share/ikiwiki/basewiki if you care to have a look) that ships with Ikiwiki.

We start creating pages on the machine we just installed ikiwiki on (the server). Later we will learn how to add/edit content remotely.

The following is a mini-example of some often-used markdown markup, see formatting or the nice human markdown reference by Fletcher Penney for more details.2

cd ~/myiki
$ cat index.mdwn
# heading1: myiki is my 1st ikiwiki

We write markdown, that allows for _italic_ and **bold** markup.

## heading2

Lists are possible too

- a list item
- another one

    - a nested list
    - bla

and even numbered lists

1. 1st
1. 2nd
1. 3rd
10. numbering is automatic but
- using correct numbering in the markdown source may help


And inline `code`

    code blocks
    blocks of code

and citations

> Citations are indented a bit in the default style sheet but
> that can be changed.

Once the index.mdwn-file is created commit it to the git repo. The git push3 will trigger the new page to be rendered from the just created markdown file:

$ git add index.mdwn
$ git commit -m "my 1st own wiki page" index.mdwn
$ git push

Now the startpage on http://ikiwiki.local/~vagrant/myiki/ shows the the new content.

Directories can be created in the natural way. Next we are creating a very basic structure to keep the documentation-files we are going to create for our Xymon-monitored hosts in a separate directory.

The next article will cover the search function of Ikiwiki.


  1. Combined with Pandoc markdown can be converted to a lot of formats, including plain-txt, html, epub, odf and MS Word.

  2. There exist quite some flavors or markdown, including GitHub Flavored Markdown, but that goes beyond the scope of this article.

  3. For the the git savy users: the bare-repository is located in ~/myiki.git/).