This wiki is designed to be distributed and "redundant" (as in having multiple copies). Basically, this is to allow you to access the documentation even if the network goes down. This is done through ikiwiki, which is a the engine behind this wiki.

Note that this documentation should probably be merged into tips/distributed wikis. I copied most of it there, but I am not sure i want to completely remove this important documentation...

Basic offline editing and sharing

Basically, this wiki is a collection of markdown-formatted pages committed to a git repository. The git repository can be freely cloned using this command:

git clone git://wiki.reseaulibre.ca/

This will at least provide you with the raw source, the text files that generate the wiki website. There you can make changes, commmit and push them to the same URL.

Use this for new copies, as it is faster than the regular wiki, hosted on a residential connexion. This is in a real datacenter:

git clone git://git.koumbit.net/reseaulibre.git

Creating a mirror

To create a mirror of this wiki, if it ever goes down, you can start from the above repository and create a new wiki. Hosting mirrors of the wiki is also encouraged as it provides redundancy for the main site, and also allows you to develop new features for the wiki without disrupting the main site.

This procedure shows you how to create a one time clone of the wiki that is editable both through the web interface (optional) and through the git repository. It will not sync back to or from the original wiki, for this you need to make extra configurations detailed in the second section.

Preparation

You need to install the ikiwiki package for the mirror to work. You can use ikiwiki to publish the actual HTML pages elsewhere if you don't plan on letting people edit the wiki, but generally you want the package to be installed on the webserver for editing to work.

apt-get install ikiwiki

Install all the recommended packages.

Make sure you run at least version 3.20120319 of ikiwiki, available in since Debian squeeze (through backports). However, there were several bugfixes to the OpenStreetMap plugin (osm) in 3.20120725, which is available only since Debian Jessie. To enable Debian Jessie repositories on your Debian install, use:

cat > /etc/apt/preferences.d/jessie.pref <<EOF
Package: *
Pin: release a=jessie
Pin-Priority: 1
EOF
echo 'deb http://ftp.ca.debian.org/debian/ jessie main' > /etc/apt/sources.list.d/jessie.list
apt-get install -t jessie ikiwiki

If you disable the osm plugin and do not use the map feature, you don't need to worry about versions.

Setting up the wiki

Optionnally: create a user just for this wiki. Otherwise the wiki will run as your user from here on.

We assume your username is user and that you will host the wiki under the hostname reseaulibre.example.com, and that you have root on your machine, but those things are not all necessary.

The following steps should get you going:

cd ~user
# setup base repository, named source.git
git clone --bare git://wiki.reseaulibre.ca/ source.git
# setup srcdir, named source
git clone source.git
# convenience copy of the setup file
git clone -b origin/setup source.git setup
cd setup
edit ikiwiki.setup # adapt configuration

When editing ikiwiki.setup, make sure you change the following entries:

cgiurl: http://reseaulibre.example.com/ikiwiki.cgi
cgi_wrapper: /var/www/ikiwiki.cgi
srcdir: /home/user/source
destdir: /var/www/reseaulibre.example.com
libdir: /home/user/source/.ikiwiki
git_wrapper: /home/user/source.git/hooks/post-commit
git_test_receive_wrapper: /home/user/source.git/hooks/pre-receive
ENV:
  TMPDIR: /home/user/tmp

This assumes that your /var/www directory is writable by your user.

Then render the wiki:

ikiwiki --setup ikiwiki.setup

You may need to go over the maintenance guide for the plugins to enable and the hooks configuration. Every time you change the ikiwiki.setup file, you will want to call the above --setup argument.

Editing the wiki through git

At this point, your wiki should already be visible in /var/www/reseaulibre.example.com, the destdir. You can edit it and changes should show up automatically in the destdir.

However, you need yet another clone for this, the srcdir being used internally by the web interface of Ikiwiki. So clone the repository elsewhere:

git clone ~user/source.git checkout
cd checkout
edit index.mdwn
git commit index.mdwn
git push

This will refresh the main page of the wiki, for example.

Webserver configuration

You will also need a webserver to serve the content in the destdir defined above. We assume you will configure a virtual host named reseaulibre.example.com. Here are some examples on how to do those, see setup and tips/dot cgi for complete documentation.

Apache configuration

<VirtualHost *:80>
    ServerName reseaulibre.example.com:80
    DocumentRoot /var/www/reseaulibre.example.com
    <Directory /var/www/reseaulibre.example.com>
        Options Indexes MultiViews ExecCGI
        AllowOverride None
        Order allow,deny
        allow from all
    </Directory>
    ScriptAlias /ikiwiki.cgi /var/www/ikiwiki.cgi
    ErrorDocument 404 "/ikiwiki.cgi"
</VirtualHost>

Nginx configuration

server {
    root /var/www/reseaulibre.example.com/;
    index index.html index.htm;
    server_name reseaulibre.example.com;

    location / {
        try_files $uri $uri/ /index.html;
    }
    location /ikiwiki.cgi {
        fastcgi_pass  unix:/tmp/fcgi.socket;
        fastcgi_index ikiwiki.cgi;
        fastcgi_param SCRIPT_FILENAME   /var/www/ikiwiki.cgi;
        fastcgi_param  DOCUMENT_ROOT      /var/www/reseaulibre.example.com;
        include /etc/nginx/fastcgi_params;
    }
}

Start this process as your own user (or the user that has write access to srcdir, destdir, etc):

spawn-fcgi -s /tmp/fcgi.socket -n -- /usr/sbin/fcgiwrap

Make this writable:

chmod a+w /tmp/fcgi.socket

Other extensions

Also make sure you disable the search, ikiwikihosting and branchable plugins, as they require extra configuration not covered by this manual. See plugins/search and http://ikiwiki-hosting.branchable.com/ for more information.

If you want to enable search, you will want to install those packages.

• libsearch-xapian-perl
• xapian-omega

Other plugins in the default .setup file may require:

• libsort-naturally-perl
• libtext-wikicreole-perl

You're done!

At this point, you are done! You can edit your own clone of the wiki, although your changes will not go back to the main site. However, you can always push or pull manually from the repository in ~user/source.git to update the main site.

Add your site to the list in mirrors.

Other guides

Another guide is the tips/laptop wiki with git guide. To get a better understanding of how ikiwiki works, see rcs/git.

This may also be of use if the above doesn't work.

There is some work being done to host copies of this wiki on OpenWrt nodes. See ikiwiki+openwrt.

Two-way replication

So you may also want keep your mirror up to date with the main site. You can also see your local edits sent automatically to the main site.

Keeping the mirror up to date

There are two options here. One is to regularly pull from the master, either through a cron job or by hand. This is less reliable, klunky, but doesn't require cooperation from the master. Try:

cd ~user/source.git
git pull --rebase

The other option is to make the master push to the mirror. For this, the master needs to enable the plugins/gitpush plugin and add the following to the setup file:

git_push_to:
- ssh://user@reseaulibre.example.com/source.git

The repository URL above needs to point to the "repository" directory of the mirror, see the rcs/git documentation for a good explanation of the layout of the different git repositories in ikiwiki.

It also needs to allow the following SSH key to push to the repository:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDQsHWlypnPe+4e0mKkE51oDHK2yXrEeja6299Es/wFvqihvzY4hQhJdUdl2KVmz5CGjRYqhnQ8l5Al5vtHoi9IxlI7yS7cOsj/wFt4EKDophqoyUFDaiWtXuFCNYwdTeX5Fb9N6nT8ihUUK/q9k8Ew9kuBTbznsVra5zqJv+LhfAMIesPwmP6iF966Evi0uXxz0CkIevttvYgRZyPIvdVN90nr5f7um1vOP6L1KkQne8guHpuNfxd9XZg0e3XPG6decGREy8jdOc3xlIADc+yxKpB+XqZyE3iYi2RsxnjqWbSURvOhvI5z4EVj5Qv8ktSj8g3LkukQr25EgNMl1cv9 r-wiki@marcos

Announcing the mirror

Once your mirror works, it needs to be added to the list of mirrors. You can ask the mirror where you take it from (and why not, all mirrors) to add it to their setup file. As an example, here's the configuration for the first mirror:

mirrorlist:
  example: https://reseaulibre.example.com/

The plugins/mirrorlist plugin of course needs to be enabled.

Pushing changes back to the main site

The final step is to push edits on the mirror back to the master site. That way the mirror is not only for reading, but can also be edited, even when the master is offline or the network is separated.

To do this, the mirror needs to push back to the master, again using the gitpush plugin:

git_push_to:
- git://wiki.reseaulibre.ca/

This will ensure that commits done on the mirror will propagate back to the master.

Deprecated documentation

Those steps may not be necessary in your setup and are not used in this wiki.

The following steps are not required for the wiki to work correctly, but may nevertheless be useful.

Multiple committers

Note that this is done automatically by the ikiwiki-hosting package, which handles this through anonymous git pushes.

The rcs/git page details a bit of the git internals of ikiwiki, but doesn't explain clearly how to do such a setup. In order to allow multiple committers, I therefore had to go through a few hoops to be able to allow the web interface, myself and others to push commits to the repository.

First, create the sandbox user:

adduser --system --group reseaulibre

Those bits ensure the wrappers are suid with the group.

# group for wrappers to run in
wrappergroup => 'reseaulibre',

Then the git repository (~user/source.git) needs to be marked as shared so that permissions are kept right:

git config core.sharedRepository group
chmod -R g+ws .

To allow users to push to the repository, use:

adduser anarcat reseaulibre

Publishing the wiki source git repository through HTTP

Note that this has been is configured automatically by the ikiwiki-hosting package, which configures a git daemon for each wiki.

To publish the git repository through HTTP, you can change the post-update hook as described here, which means specifically changing the git-wrapper parameter to:

git_wrapper => '/home/user/source.git/hooks/post-update.ikiwiki

then creating the post-update hook with the following content:

#!/bin/sh
./hooks/post-update.ikiwiki
exec git update-server-info

... and setting it executable. Then the URL of the repository can be published through the repolist plugin:

repositories => [qw{http://reseaulibre.example.com/source.git/}],

You will need an Alias directive in your Apache configuration to make ~user/source.git appear as /source.git.

CIA.vc notifications

We are not using this anymore, and instead use KGB, but that has to be documented.

We used Koumbit git-hooks to do CIA.vc notifications. To deploy the script, install both the ciabot.pl and ciabot-post-receive hooks in the source.git/hooks directory. It is important that both script be in the same directory. Symlink the post-receive hook in place:

ln -s ciabot-post-receive post-receive

.. and configure the script according to your preference:

git config hooks.ciaproject reseaulibre
git config hooks.ciafrom ciabot@marcos.reseaulibre.ca

We use email notifications because the potentially disconnected nature of the mesh.

Note that the scripts are available in the setup branch.