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
myikiwith Ikiwiki using git backend and apache as the webserver for delivering the pages
create our first page
add search functionality to
myikiwith a Xymon server
some theming to give Ikiwiki a more pleasant look
author/client machines that write content and use
git pushto publish
Ikiwiki Server Setup and create
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
[ 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
# apt-get install git
Here we switch to a normal user, to setup the wiki (in the sample this user is
$ git config --global user.name "John Doe" $ git config --global user.email "firstname.lastname@example.org"
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
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
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.
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.
index.mdwn-file is created commit it to the git repo. The
push3 will trigger the new page to be rendered from the just created
$ 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.
For the the git savy users: the bare-repository is located in