So we have made some plugins and patches to our IkiWiki installation and now we want to use it elsewhere. Boom - nothing works out. After three times figuring out stuff again let’s document it.


IkiWiki is one of the exceptions of the no Perl policy.


Debian packages

apt-get install libxapian-dev gettext libhighlight-perl libperl-dev libmagickcore-dev


We use some IkiWiki plugins and therefore need the default IkiWiki modules, as well as some additional ones. The Perl Bundle worked on one machine, but not on the other. So we made our own, smaller list of needed modules.

for m in \
    CGI::Session \
    CGI::FormBuilder \
    HTML::Scrubber \
    HTML::Template \
    Text::Markdown \
    Mail::Sendmail \
    Text::MultiMarkdown \
    XML::Simple \
    YAML::XS \
    Sort::Naturally \
    Search::Xapian \
    Image::Magick \
    ; \
do PERL_MM_USE_DEFAULT=1 cpanm $m ; done

ToDo: Image::Magick will fail to build, because it does not use the architecture specific include and library paths. Here is a quick fix, YMMV.

  1. Find out where cpanm tried to build the ImageMagick Perl module from the error message (Hint: directory of the log file).

  2. Get the include path for ImageMagick from:

pkg-config --cflags-only-I ImageMagick
  1. Get the library directory for libperl from
dpkg -L libperl-dev |grep
  1. Enter the build directory and edit Makefile.PL

    • find my $INC_magick and prepend with -Iinclude¬†path,
    • find my $LIBS_magick and prepend with -Llibrary¬†directory
  2. Run

perl Makefile.PL
make install


  • Build directory: ~/.cpanm/work/1521471045.16573/PerlMagick-6.89
  • Include path: -I/usr/include/x86_64-linux-gnu//ImageMagick-6
  • Library path: -L/usr/lib/x86_64-linux-gnu

Install our homemade IkiWiki plugins

cd /usr/local/share
git clone IkiWiki

Perl will look at /usr/local/share when it looks for modules.

Get the source, Luke

cd ~/progs && \
git clone ikiwiki.magma-soft

This one is a bummer. Our patches to IkiWiki are hidden in a personal account on a production server… We should merge them with current IkiWiki sources and offer them as a branch.

Compile IkiWiki

cd ~/progs/ikiwiki.magma-soft
perl Makefile.PL
make install

Clone a wiki

All of our websites are in ~/Websites, this path is referenced in the .setup configuration file, keep it so for the moment. LocationPlugin shows you why, and how to move things around.

The names of the directories are completely inconsistent. Here is the “canonical” list, pick what you need.

Software Wiki -
mkdir -p ~/Websites && cd ~/Websites
git clone
cd ~/Website/
Magma Soft Website -
mkdir -p ~/Websites && cd ~/Websites
git clone"]]
cd ~/Website/magma-soft

Compile a wiki

We have two setups: dev and host

dev setup

This is the development / testbed setup used at home.

The website is compiled and installed to /var/www/domain/subdir, for example /var/www/

The gatling web server is ?set up on localhost so that the website can be viewed on localhost, for example: http://localhost/

Run one of the following lines inside the cloned website git repository:

ikiwiki --setup .setup --location dev

host setup

On the server, there might be a completely different web server and setup. The server configuration is set up via the host location, the LocationPlugins default.

make host
ikiwiki --setup .setup
ikiwiki --setup .setup --location-host

Upload the changes

You now how to git push, right?

Well, the master has to be ?setup correctly for this to work.