In a farm, one single copy of wiki engine (the farmer) is used to run several individual wikis (the animals). For a generic introduction, and for different approaches to set up a DokuWiki farm, see farm.

This page describes how to setup a farm in a particularly elegant way, letting the web server do the main work of redirecting HTTP requests to the pertinent wiki.

Plugins and Templates are common to all the wikis: You have to install them manually in the farmer wiki. Templates can be chosen from each individual animal wiki. Plugins cannot be enabled or disabled in the animal wiki at the time of writing (8 Nov 2009), although there are plans to make it possible. But it is possible to configure the plugins per animal.

There are two different methods to organize the binding of URLs to animal directories:

Method (1), using RewriteRules:

• you need either
  • a server with a user space URL rewrite mechanism like .htaccess on Apache, or
  • access to a server configuration file where you can place RewriteRules;
• allows only one domain; URLs have forms like example.org/barn/cow;

Method (2), using virtual hosts:

• you need some access to the server to create virtual hosts ¹⁾
• allows different URLs and subdomains example.org to cow.example.net,
  • allows use of different ports like in farm.example.org:8080
  • using subdirectories like farm.example.org/barn/cow/ is more complicated;

You can use the userewrite config option with .htaccess, regardless of the URL rewrite method. With method (1) ²⁾, the basedir configuration option must be set in each animal.

In this section, we will explain how to set up a most basic wiki farm with just one animal (called cow) under the URL localhost:barn/cow. The order of the installation steps is chosen so that we can test some new functionality after each step.

We will install into the following directories:

• /var/www/farmer – the DokuWiki engine
• /var/www/barn – contains all the animals
• /var/www/barn/cow — one animal wiki

We will choose the URL binding method (1). For method (2), see below (Advanced Configuration).

Supposing your login is bob, and your web server runs in group www-data:

sudo mkdir          /var/www/{farmer,barn}
sudo chown bob      /var/www/{farmer,barn}
sudo chgrp www-data /var/www/{farmer,barn}

If you install to a private directory (say ~bob/public_html), root privilege is not needed.

Test: point your browser to http://localhost. You should see an index containing the empty directories farmer and barn. If not, debug the web server configuration.

Here we describe the simples URL rewrite method, using .htaccess under Apache.

Copy the following to /var/www/barn/.htaccess:

.htaccess

RewriteEngine On
RewriteRule ^/?([^/]+)/(.*)  /farmer/$2?animal=$1 [QSA]
RewriteRule ^/?([^/]+)$      /farmer/?animal=$1 [QSA]
Options +FollowSymLinks

Test: Point your browser to http://localhost/barn/foo. You should see the index of farmer. Point to http://localhost/barn/foo/bar. You should get a 404 error “The requested URL /farmer/bar was not found”. This shows that the URL binding works.

If the test fails:

• .htaccess must be enabled in the in the Apache Configuration (AllowOverride All);
• mod_rewrite must be Included.
• If you have a redirection loop, your DocumentRoot needs to be /var/www/ (neither /var/www/farmer/ nor /var/www/barn/).

The farmer is the DokuWiki instance which is used to run all the animals.

Install a recent DokuWiki release to the farmer directory /var/www/farmer).

Disable the plugin manager of the main DokuWiki instance (so it doesn't appear in the admin menu of the animals)

touch /var/www/farmer/lib/plugins/plugin/disabled

Test: point the browser to http://localhost/farmer. You should get some response from DokuWiki, though possibly not more than a “DokuWiki Setup Error” because subdirectories are not accessible or writeable.

Unless the test brings you to the DokuWiki installer page, permissions must be corrected:

If you have root rights, do

cd /var/www/farmer
sudo chown -R bob:www-data .                # replace 'bob' by your account
find ./ -type d -exec chmod 775 {} \;  # make directories accessible
# not needed? chmod 664 conf/*                       # make config files writeable

Without root privilege, less restrictive settings are needed:

find ./ -type d -exec chmod -v 777 {} \;
chmod 666 conf/*

Test: point the browser to http://localhost/farmer. You should get to the installer page that prompts you for the name of the wiki and for a superuser registration. You do not need to fill that form since the farmer wiki will not be filled with any contents.

The script preload.php listed below will overwrite DokuWiki constants (path to the configuration settings, etc.) before DokuWiki's initialization phase according to the barn directory you specify. This allows to have a different configuration and data directory for each DokuWiki animal. This also sets a constant (DOKU_FARM) to use in other code (e.g. plugins). For a more powerful variant that also support redirect method (2) and that falls back to a default conf directory, see below (Advance Configuration).

Copy this script into /var/www/farmer/inc/preload.php:

preload.php

<?php
/**
 * DokuWiki farm setup according to http://www.dokuwiki.org/tips:redirect_farm.
 *
 * @author Anika Henke <anika@selfthinker.org>
 * @author Michael Klier <chi@chimeric.de>
 * @author Christopher Smith <chris@jalakai.co.uk>
 * @author virtual host part of conf_path() based on conf_path() from Drupal.org's /includes/bootstrap.inc
 *   (see http://cvs.drupal.org/viewvc/drupal/drupal/includes/bootstrap.inc?view=markup)
 * @license GPL 2 (http://www.gnu.org/licenses/gpl.html)
*/
 
$barn = '/var/www/barn'; // SET THIS to your barn directory
 
if(!defined('DOKU_CONF')) define('DOKU_CONF', conf_path($barn));
if(!defined('DOKU_FARM')) define('DOKU_FARM', false);
 
/* Get the appropriate configuration directory from $_REQUEST */
function conf_path($barn) {
    if(isset($_REQUEST['animal'])) {
        if(!is_dir($barn.'/'.$_REQUEST['animal']))
            nice_die("Sorry! This Wiki doesn't exist!");
        if(!defined('DOKU_FARM')) define('DOKU_FARM', 'htaccess');
        return $barn.'/'.$_REQUEST['animal'].'/conf/';
    } else {
        // is this ever needed?: return DOKU_INC.'conf/';
        // better fail with error message:
        nice_die( "Invalid call to preload: wiki not specified" );
    }  
}
 
/* Use default config files and local animal config files */
$config_cascade = array(
    'main' => array(
        'default'   => array(DOKU_INC.'conf/dokuwiki.php'),
        'local'     => array(DOKU_CONF.'local.php'),
        'protected' => array(DOKU_CONF.'local.protected.php'),
    ),
    'acronyms'  => array(
        'default'   => array(DOKU_INC.'conf/acronyms.conf'),
        'local'     => array(DOKU_CONF.'acronyms.local.conf'),
    ),
    'entities'  => array(
        'default'   => array(DOKU_INC.'conf/entities.conf'),
        'local'     => array(DOKU_CONF.'entities.local.conf'),
    ),
    'interwiki' => array(
        'default'   => array(DOKU_INC.'conf/interwiki.conf'),
        'local'     => array(DOKU_CONF.'interwiki.local.conf'),
    ),
    'license' => array(
        'default'   => array(DOKU_INC.'conf/license.php'),
        'local'     => array(DOKU_CONF.'license.local.php'),
    ),
    'mediameta' => array(
        'default'   => array(DOKU_INC.'conf/mediameta.php'),
        'local'     => array(DOKU_CONF.'mediameta.local.php'),
    ),
    'mime'      => array(
        'default'   => array(DOKU_INC.'conf/mime.conf'),
        'local'     => array(DOKU_CONF.'mime.local.conf'),
    ),
    'scheme'    => array(
        'default'   => array(DOKU_INC.'conf/scheme.conf'),
        'local'     => array(DOKU_CONF.'scheme.local.conf'),
    ),
    'smileys'   => array(
        'default'   => array(DOKU_INC.'conf/smileys.conf'),
        'local'     => array(DOKU_CONF.'smileys.local.conf'),
    ),
    'wordblock' => array(
        'default'   => array(DOKU_INC.'conf/wordblock.conf'),
        'local'     => array(DOKU_CONF.'wordblock.local.conf'),
    ),
    'acl'       => array(
        'default'   => DOKU_CONF.'acl.auth.php',
    ),
    'plainauth.users' => array(
        'default'   => DOKU_CONF.'users.auth.php',
    ),
    'plugins' => array( // needed since Angua
        'local'     => array(DOKU_CONF.'plugins.local.php'),
        'protected' => array(
            DOKU_INC.'conf/plugins.required.php',
            DOKU_CONF.'plugins.protected.php',
        ),
    ),
    'userstyle' => array(
        'default' => DOKU_CONF.'userstyle.css', // 'default' was renamed to 'screen' on 2011-02-26, so will be deprecated in the next version
        'screen'  => DOKU_CONF.'userstyle.css',
        'rtl'     => DOKU_CONF.'userrtl.css',
        'print'   => DOKU_CONF.'userprint.css',
        'feed'    => DOKU_CONF.'userfeed.css',
        'all'     => DOKU_CONF.'userall.css',
    ),
    'userscript' => array(
        'default' => DOKU_CONF.'userscript.js'
    ),
);
?>

Test: Point your browser to http://localhost/barn/cow. You should get a “DokuWiki Setup Error” explaining that “This Wiki doesn't exist!”.

Instead of going through the remaining steps, you can

• use a script which combines all of them,
• or create one master template directory which you can just copy to each new animal directory.

Create the animal directory cow:

mkdir /var/www/barn/cow

Test: http://localhost/barn/cow should bring you to a wiki start page with error messages due to a missing conf directory.

Create a few configuration files.

In particular, create a user 'admin' with password 'admin'. The password and the user credentials should be changed as soon as possible, via the update profile form.

cd /var/www/barn/cow
mkdir conf
cat > conf/local.php <<'EOF'
<?php
$conf['title'] = 'Animal Wiki Title';
$conf['lang'] = 'en';
$conf['useacl'] = 1;
$conf['superuser'] = '@admin';
?>
EOF
cat > conf/local.protected.php <<'EOF'
<?php
$conf['savedir'] = DOKU_CONF.'../data';
$conf['basedir'] = '/barn/cow';
$conf['updatecheck'] = 0;
?>
EOF
cat > conf/acl.auth.php <<'EOF'
# <?php exit()?>
* @admin 255
* @ALL 1
EOF
cat > conf/users.auth.php <<'EOF'
# <?php exit()?>
admin:$1$cce258b2$U9o5nK0z4MhTfB5QlKF23/:admin:admin@example.org:admin,user
EOF

Set group and permissions:

sudo chgrp -R www-data conf
chmod 775 conf                       # allow wiki to write into this directory
chmod 664 conf/*                     # allow wiki to modify the files created above
chmod 644 conf/local.protected.php   # this one must not be modified by the wiki

Without root privilege, it is necessary to set file permissions 666 and directory permissions 777.

Test: http://localhost/barn/cow should yield a “DokuWiki Setup Error” because there is no datadir ('pages').

Create data directory with some subdirectories. Assuming you have a powerful shell, the following commands will do it:

cd /var/www/barn/cow
mkdir -p data/{attic,cache,index,locks,media,media_attic,media_meta,meta,pages,tmp}
sudo chgrp -R www-data data
chmod -R 775 data

Without root privilege, it is necessary to set directory permissions 777.

Test: http://localhost/barn/cow should bring you again to a wiki start page, now without error messages.

Login as admin, and update the user profile.

Here's a little bash script which will perform the above steps in one go inside the directory it's executed in (if you're using this with other scripts you have to make sure you cd into the designated directory before executing it). Save it as addanimal, make sure it's in your shell $PATH (i.e. by putting it into /usr/local/bin), and make it executable. It takes the domain/directory of the new animal as argument.

addanimal.sh

#!/bin/bash
# This script is under public domain do with it whatever you want (yes, that includes eating it).
if [ $# -lt 1 ]; then
    echo "Usage: $(basename $0) [animal domain or directory]"
    exit 1
fi
 
ANIMAL=${PWD}/${1}
ANIMAL_TITLE=$1
 
if [ -d $ANIMAL ]; then
    echo "ERROR: $ANIMAL exists already!"
    exit 1
fi
 
echo ">> adding animal $1"
 
echo ">> creating directory structure ..."
mkdir -p ${ANIMAL}/{data/{attic,cache,index,locks,media,media_attic,media_meta,meta,pages,tmp},conf}
find ${ANIMAL}/ -type d -exec chmod 777 {} \;
touch ${ANIMAL}/conf/{local.php,local.protected.php,acl.auth.php,users.auth.php,plugins.local.php}
chmod 666 ${ANIMAL}/conf/{local.php,acl.auth.php,users.auth.php,plugins.local.php}
 
echo ">> creating basic configuration ..."
echo "<?php
\$conf['title'] = '${ANIMAL_TITLE}';
\$conf['lang'] = 'en';
\$conf['useacl'] = 1;
\$conf['superuser'] = '@admin';" > ${ANIMAL}/conf/local.php
 
echo ">> setting fixed configuration ..."
echo "<?php
\$conf['savedir'] = DOKU_CONF.'../data';
\$conf['updatecheck'] = 0;" > ${ANIMAL}/conf/local.protected.php
 
echo ">> setting basic permissions ..."
echo "# <?php exit()?>
* @admin 255
* @ALL 1" > ${ANIMAL}/conf/acl.auth.php
 
echo ">> adding admin user ..."
echo '# <?php exit()?>
admin:$1$cce258b2$U9o5nK0z4MhTfB5QlKF23/:admin:admin@mail.org:admin,user' > ${ANIMAL}/conf/users.auth.php
 
echo ">> IMPORTANT: Don't forget to change your admin username + password!"
echo ">> finished!"
echo ">> bye!"
 
exit 0
 
# vim:ts=4:sw=4:noet:enc=utf-8:

Usage Example:

$> cd /var/www/barn
$> addanimal cat.domain.org

$> cd /var/www/barn
$> addanimal subdir

You can use nice URLs. Just add the .htaccess file into your /var/www/farmer directory as if this were a singleton copy, and then each animal may set their URLs how they chose without further intervention from the farmer. If you are using the directory (.htaccess) based setup you additionally need to configure the basedir configuration option in each animal.

Since Angua the plugins can be enabled and disabled per animal using the plugin manager (develonly). Activating and deactivating is stored in the plugins.local.php config file. You can globally (or locally) fix the enabling or disabling of plugins by adding their values to plugins.protected.php. But before Angua you would need to change the following:

As described in farm you need to create your own plugin manager class in order to disable or enable plugins on a per animal basis. You can put the following code into inc/preload.php as a start:

require_once DOKU_INC.'inc/plugincontroller.class.php';
class Farm_Plugin_Controller extends Doku_Plugin_Controller {
    function Farm_Plugin_Controller() {
        parent::Doku_Plugin_Controller();
        if (!isset($conf['disabled_plugins']) || !is_array($conf['disabled_plugins'])) {
            $conf['disabled_plugins'] = array();
        }
    }
 
    function isdisabled($plugin) {
        global $conf;
        if (parent::isdisabled($plugin)) {
            return true;
        } elseif (isset($conf['disabled_plugins'][$plugin])) {
            return $conf['disabled_plugins'][$plugin];
        } else {
            return false;
        }
    }
}
$plugin_controller_class = 'Farm_Plugin_Controller';

This farm plugin controller class first asks if a plugin is globally disabled and if not it looks for a configuration setting named $conf['disabled_plugins'][$plugin]. You can disable plugins in any configuration file with lines like

$conf['disabled_plugins']['discussion'] = '1';

This code should be further improved to hide disabled plugins in the configuration manager.

As the Abysss Webserver does not feature .htaccess the URL redirection has to be configured within the server itself. The farmer is located in the subdirectory “dokuwiki” and the animals are also in own subdirectories. The following configuration worked for me (only one redirecting rule was necessary):

Virtual Path Regular Expression: /([^/]+)/(.*)
Case Sensitive: On (default)
No conditions
Apply to subrequests too: On (default)
If this rule matches: Perform an internal redirection
Redirect to: /dokuwiki/$2?animal=$1
Append Query String: On (default)
Escape Redirection Location: On (default) — Charly 2009/10/22 10:49

For this setup you have to configure the virtual host for each new animal.

NameVirtualHost *
 
<VirtualHost *:8080>                  # this only works for a specific port
    ServerName example.org
    ServerAlias *.example.org         # works for all subdomains of example.org
    DocumentRoot /var/www/farmer/     # the DokuWiki engine directory
</VirtualHost>
 
<VirtualHost *>
    ServerName subdomain.example.org  # this only works for one specific subdomain
    DocumentRoot /var/www/farmer/     # as above, this is invariable
</VirtualHost>

On most shared hosts environments you only need to add the server name (your desired domain with or without subdomain) and the document root (always pointing to the farmer directory) through their GUI.

Furthermore, you need to replace the function conf_path in farmer/inc/preload.php by the following variant:

function conf_path($barn) {
 
    // Method (1), using RewriteRules: get animal subdirectory from $_REQUEST
    if(isset($_REQUEST['animal'])) {
        if(!is_dir($barn.'/'.$_REQUEST['animal']))
            nice_die("Sorry! This Wiki doesn't exist!");
        if(!defined('DOKU_FARM')) define('DOKU_FARM', 'htaccess');
        return $barn.'/'.$_REQUEST['animal'].'/conf/';
    }
 
    // Method (2), virtual host based:
       // Use the first conf directory found by stripping the website's hostname
       // from left to right and pathname from right to left. If none is found,
       // return the default './conf'.
    $uri = explode('/', $_SERVER['SCRIPT_NAME'] ? $_SERVER['SCRIPT_NAME'] : $_SERVER['SCRIPT_FILENAME']);
    $server = explode('.', implode('.', array_reverse(explode(':', rtrim($_SERVER['HTTP_HOST'], '.')))));
    for ($i = count($uri) - 1; $i > 0; $i--) {
        for ($j = count($server); $j > 0; $j--) {
            $dir = implode('.', array_slice($server, -$j)) . implode('.', array_slice($uri, 0, $i));
            if(is_dir("$barn/$dir/conf/")) {
                if(!defined('DOKU_FARM')) define('DOKU_FARM', 'virtual');
                return "$barn/$dir/conf/";
            }
        }
    }
 
    // optional: try default directory
    if(is_dir("$barn/default/conf/")) {
        if(!defined('DOKU_FARM')) define('DOKU_FARM', 'default');
        return "$barn/default/conf/";
    }
    // farmer
    return DOKU_INC.'conf/';
}

If you want to get this with releases before rc2009-02-06, you could patch “init.php” like this

--- init.php
+++ init.php.patched
@@ -9,6 +9,9 @@
     return ((float)$usec+(float)$sec)-((float)$start);
   }
   define('DOKU_START_TIME', delta_time());
+
+  // if available load a preload config file
+  @include(fullpath(dirname(__FILE__)).'/preload.php');
 
   // define the include path
   if(!defined('DOKU_INC')) define('DOKU_INC',fullpath(dirname(__FILE__).'/../').'/');

Or you could use PHP's auto_prepend_file option to include the above preload.php and overwrite the configuration settings. In this case you just need to remember that in contrast to “DokuWiki preload” not even DOKU_INC is defined when your auto_prepend_file is executed. — Christian Marg

Since I set “DOKU_CONF” depending on “$_SERVER['Servername'] in my preload.php, the indexing program 'bin/indexer.php' didn't work anymore. At first I opted for a patch to “indexer.php” - it should be possible to also put that code in “preload.php” to avoid this patch. All it does is to search $argv for ”–path <path to one dokufarm-animal>“, remove the additional parameters from $argv and set DOKU_CONF accordingly:

--- indexer.php.dist    2008-09-23 13:43:00.000000000 +0200
+++ indexer.php 2008-09-23 16:54:40.000000000 +0200
@@ -2,6 +2,24 @@
 <?php
 if ('cli' != php_sapi_name()) die();
 
+for($i = 1; $i < sizeof($argv); ++$i)
+{
+  if ($argv[$i] == "--path") {
+       if (!isset($argv[$i+1])) {
+               die("--path: no path given.\n");
+       } else {
+               $path=$argv[$i+1];
+               unset($argv[$i],$argv[$i+1]);
+               $argv=array_values($argv);
+               if (($path= realpath($path."/conf/").'/')===false) {
+                       die("--path: path doesn't exist.\n");
+               }
+               if(!defined('DOKU_CONF')) define('DOKU_CONF', $path );
+               last;
+       }
+  }
+}
+
 if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../').'/');
 require_once(DOKU_INC.'inc/init.php');
 require_once(DOKU_INC.'inc/common.php');

To create an index for every animal, you just have to iterate over all animals and call the indexer script for each one.
— Christian Marg 2008/09/23 17:13

Another approach is using an environment variable for setting the animal and checking for that environment variable in inc/preload.php. I've added the following snippet to inc/preload.php as the first part of the conf_path function:

    // cli
    if ('cli' == php_sapi_name() && isset($_SERVER['animal'])) {
        if (!is_dir($barn.'/'.$_SERVER['animal'])) die("Sorry! This Wiki doesn't exist!");
        if (!defined('DOKU_FARM')) define('DOKU_FARM', 'cli');
        return $barn.'/'.$_SERVER['animal'].'/conf/';
    }

With that you can use all cli scripts by executing

animal=YOUR_ANIMAL ./YOUR_SCRIPT.php

— Michitux 2010/10/30 14:39

If you want to have both DokuWiki farmer and animals each located in an own subdirectory of the server you have to use a different preload.php. basically you have to set additional constants in order to have anything working. of course you still have to set URL rewriting in your webserver (see above).

<?php
/**
 * This overwrites the DOKU_CONF.
 * Animal is not a subdirectory with the farmer, but at same level directory level.
 * Access farmer like this: http://domain.org/farmer/doku.php
 * Access animal like this: http://domain.org/animal/doku.php
 * Farmer on server e.g. /var/www/farmer
 * Animal on server e.g. /var/www/animal
 */
 
// the home directory for all animals and the farmer located in subdirectories
$farmdir = DOKU_INC.'../';
 
// don't do anything if the animal doesn't exist
if(isset($_REQUEST['animal'])) {
    if(!is_dir($farmdir . $_REQUEST['animal'])) {
        nice_die("Sorry! This Wiki doesn't exist!");
    }
    if(!defined('DOKU_CONF')) {
        define('DOKU_CONF', $farmdir . $_REQUEST['animal'] . '/conf/');
    }
    //  correct paths according to animal and make nice looking in HTML source
    if(!defined('DOKU_URL')) define('DOKU_URL',preg_replace('/(.+)\/([^\/]+)\//','$1/'.$_REQUEST['animal'].'/',getBaseURL(true)));
    if(!defined('DOKU_REL')) define('DOKU_REL',preg_replace('/([^\/]+)\/\/([^\/]+)\/(.+)\//','/$3/',DOKU_URL));
 } else {
    // don't do anything on the farmer instance
    return;
}

You can have subdirectories with the virtual host based setup (i.e. without a .htaccess file in the barn). After adding the animal directory to the barn (should be something like “domain.org.subdir”³⁾), you only need to create a symlink in the farmer directory like this:

ln -s . subdir

If you need to make subdirectories within a virtual directory setup work with userewrite=1, you need to add the following to the farmer's .htaccess for every subdirectory, right before RewriteRule ^$ doku.php [L]:

RewriteRule ^$                        subdir/doku.php  [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_URI}            subdir
RewriteRule ^(.*)$                    subdir/doku.php?id=$1  [QSA,L]
RewriteRule ^subdir/index.php$        subdir/doku.php

I am no rewrite rules expert, can someone please check and correct this (if necessary)? Be careful, this is not fully tested and is already known to cause trouble in some setups.

I had a problem with this tip, when I want to login I got to the main “farmer” - instance of the wiki, not to the individual animal, called http://server/barn/animal. To solve this, edit inc/preload.php and add these two lines into if(isset($_REQUEST['animal']). You have to change the barn directory if you choose another.

if(!defined('DOKU_URL')) define('DOKU_URL',preg_replace('/(.+)\/([^\/]+)\//','$1/**barn**/'.$_REQUEST['animal'].'/',getBaseURL(true)));
if(!defined('DOKU_REL')) define('DOKU_REL',preg_replace('/([^\/]+)\/\/([^\/]+)\/(.+)\//','/$3/',DOKU_URL));