====== Wiki Farms with DokuWiki ======

This page describes a special setup of [[doku>DokuWiki|DokuWiki]] called a **wiki farm**. In such a setup, one single copy of the engine of the wiki (the parent wiki or farm controller or **farmer**) is used to run several (read many) child instances of a wiki (i.e. individual wikis or **animals**). The biggest advantage is that only one instance of the wiki engine has to be maintained and upgraded, while keeping many wiki animals with completely separated contents (i.e. configuration and data) use that engine.

Alternative approaches are the [[Symlink Farm]], the [[lazy farm]] and [[plugin:farm|farm plugin]].

**Plugins and Templates** are common to all the wikis: You have to [[:plugin_installation_instructions#manual_instructions|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.

===== Farm Directory Structure =====

The farm directory can theoretically be anywhere in the file system but we recommend the following structure:

  * ''/var/www/farmer'' -- the DokuWiki instance
  * ''/var/www/farm'' -- contains all the animals
  * ''/var/www/farm/animal1''
  * ''/var/www/farm/animal2''

===== Install the farmer =====

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

  * **[[:Install]] the latest stable DokuWiki release** (or a development version) or use an already existing installation with the correct release version (this guide assumes you use ''/var/www/farmer'')
  * **Disable the plugin manager** of the main DokuWiki instance (so it doesn't appear in the admin menu of the farms) <code bash>touch /var/www/farmer/lib/plugins/plugin/disabled</code>
===== Add preload.php =====

Copy the following into ''/var/www/farmer/inc/preload.php'' and **set the ''$farm'' variable** to your farm directory.

<code php preload.php>
<?php
/**
 * This overwrites the DOKU_CONF. Each animal gets its own configuration and data directory.
 *
 * The farm ($farm) can be any directory and needs to be set.
 * Animals are direct subdirectories of the farm directory.
 * There are two different approaches:
 *  * An .htaccess based setup can use any animal directory name:
 *    http://example.org/<path_to_farm>/subdir/ will need the subdirectory '$farm/subdir/'.
 *  * A virtual host based setup needs animal directory names which have to reflect
 *    the domain name: If an animal resides in http://www.example.org:8080/mysite/test/,
 *    directories that will match range from '$farm/8080.www.example.org.mysite.test/'
 *    to a simple '$farm/domain/'.
 *
 * @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)
*/

$farm = '/var/www/farm'; // SET THIS to your farm directory

if(!defined('DOKU_CONF')) define('DOKU_CONF', conf_path($farm));
if(!defined('DOKU_FARM')) define('DOKU_FARM', false);


/**
 * Find the appropriate configuration directory.
 *
 * If the .htaccess based setup is used, the configuration directory can be
 * any subdirectory of the farm directory.
 *
 * Otherwise try finding a matching configuration directory by stripping the
 * website's hostname from left to right and pathname from right to left. The
 * first configuration file found will be used; the remaining will ignored.
 * If no configuration file is found, return the default confdir './conf'.
 */
function conf_path($farm) {

    // htaccess based
    if(isset($_REQUEST['animal'])) {
        if(!is_dir($farm.'/'.$_REQUEST['animal'])) nice_die("Sorry! This Wiki doesn't exist!");
        if(!defined('DOKU_FARM')) define('DOKU_FARM', 'htaccess');
        return $farm.'/'.$_REQUEST['animal'].'/conf/';
    }

    // virtual host based
    $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("$farm/$dir/conf/")) {
                if(!defined('DOKU_FARM')) define('DOKU_FARM', 'virtual');
                return "$farm/$dir/conf/";
            }
        }
    }

    // default conf directory in farm
    if(is_dir("$farm/default/conf/")) {
        if(!defined('DOKU_FARM')) define('DOKU_FARM', 'default');
        return "$farm/default/conf/";
    }
    // farmer
    return DOKU_INC.'conf/';
}


/* 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'
    ),
);
</code>


The file will overwrite DokuWiki constants (path to the configuration settings, etc.) before DokuWiki's initialization phase according to the farm 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). And it adds the possibility to have a ''default'' config directory in the farm (in case you have trouble with the farmer config, which can happen with some rewrite settings).

This is just a minimal farm setup. You could use other resources to pull the farm directories from, like databases etc. You could automate the whole farm creation process with registering a farm etc. to your liking. Get creative, and if possible, share your ideas on this page.


===== Two different setups =====

Now you have the choice between two possible farm setups:

**Virtual Host Based Setup**:
  * needs some kind of access to the server to create [[wp>Virtual_hosting|virtual hosts]] ((This doesn't mean you cannot do it in a shared host environment. Many hosting providers allow the setting up of subdomains through their usual web interface.))
  * allows any kind of domain, from ''%%example.org%%'' to ''%%subdomain.example.net%%'' or even ''%%test.example.org:8080/foo/bar/%%'' ((although subdirectories can get complicated))
  * can use the [[config:userewrite]] config option with .htaccess

**Directory (.htaccess) Based Setup**:
  * your server needs the ability to use [[wp>.htaccess]] on Apache or other URL rewriting means on other web servers
  * allows only URLs in the form of ''%%example.org/farm/foo%%'', ''%%example.org/farm/bar%%'', etc.
  * can use the [[config:userewrite]] config option with .htaccess when setting the [[config:basedir]] configuration option in each animal.

==== Virtual Host Based Setup ====

For this setup you have to configure the [[wp>Virtual_hosting|virtual host]] for each new animal.

<code apache>
NameVirtualHost *

<VirtualHost *:8080>                     # this only works for a specific port
    ServerName example.org
    ServerAlias *.example.org            # this works for all subdomains of example.org
    DocumentRoot /var/www/farmer/        # the document root always needs to be the DokuWiki *farmer* directory
</VirtualHost>

<VirtualHost *>
    ServerName subdomain.example.org     # this only works for one specific subdomain
    DocumentRoot /var/www/farmer/        # the document root always needs to be the DokuWiki *farmer* directory
</VirtualHost>
</code>

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.

==== Directory (.htaccess) Based Setup ====

In this scenario we just use a single domain and access the animals via directories, like ''%%http://example.org/farm/cat%%'' and ''%%http://example.org/farm/dog%%''.

This ''.htaccess'' (needed to redirect the accessed animal to the farmer) has to be put into the ''/var/www/farm'' directory which holds all the animals.
Remember to enable .htaccess in the Apache Configuration (AllowOverride All)

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

Be careful if you have a **redirection loop**, your DocumentRoot needs to be ''/var/www/'' (neither ''/var/www/farmer/'' nor ''/var/www/farm/'').
=== Comments ===

<son@lincolnix.net>, 29. July 2011: Can someone clarify and be more specific (or at least make reference links) to the details of apache2 configuration? I am uncertain as to where/how to enable .htaccess in the Apache Configuration. I'll be researching it starting [[http://httpd.apache.org/docs/2.0/howto/htaccess.html|here]] and [[http://www.techrepublic.com/article/learn-how-to-configure-apache/5076696|here]]; I can add what I find out. If someone else is more knowledgeable in this area and can add just a little more information here, I think that could be helpful.

<albin.blaschka@standortsanalyse.net>, 25. November 2009: The buttons "Login" et al. do not work for me: If clicked, I get to the main "farmer" - instance of the wiki, not to the individual animal, called http://server/farm/animal. At the moment, I have no solution for the problem (FIXME forms seem not to get re-written), working on it, it is a showstopper for me, if I am right...looking deeper, I will report back...

<benjamin.seclier@univ-nancy2.fr>, 7. December 2009: With the .htaccess script above, I have a redirection loop if I call an animal (which doesn't exist) without the last slash on the URL. For instance, if I call this bad animal :
  http://my-wiki.fr/badanimal/
the preload.php file send me "This wiki doesn't exist" but if I call 
  http://my-wiki.fr/badanimal
I have a redirection loop.\\
In order to fix it, I had to modify my .htaccess (which I wrote in my Apache's configuration file instead) like this :
<code apache>
RewriteEngine On
RewriteRule index - [L]
RewriteRule ^([^/]+)/(.*) ./dokuwiki/master/$2?animal=$1 [QSA,L]
RewriteRule ^([^/]+)$ http://my-wiki.fr/$1/ [QSA,L]
</code>
Thanks to this hack, when I type an URL without the last slash, it is rewrited with this last slash and I don't have this redirection loop anymore.

=== URL redirection with Abyss Webserver ===

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)  --- //[[dh2mll@web.de|Charly]] 2009/10/22 10:49//


===== Creating an Animal ====

You can
  * go through the following steps
  * or [[#using_a_script_to_setup_an_animal|use the script]] which combines all of these steps
  * or create one master template directory which you can just copy to each new animal directory.

==== Step by Step ===

=== Create a Directory ==

The rules how to name the directory in which your animal stores all its files depends on the setup:

  * The **virtual host setup** needs animal directory names which reflect the virtual host: e.g. ''%%example.com%%'' or only ''%%example%%'' or ''%%project.example.com%%'' or even ''%%8080.project.example.com.foo.bar%%'' (for the URL example of ''%%project.example.com:8080/foo/bar/%%''). ((This approach is based on [[http://www.drupal.org/|Drupal]]'s way of farming, see their [[http://drupal.org/getting-started/6/install/multi-site|multi-site page]] for more information on this.))
  * The **directory / htaccess setup** needs the animal directory names as they are called by the URL: e.g. ''%%yourdomain.org/farm/foo%%'' would need an animal directory called ''foo''.

You can use the following shell commands to create the ''/data'' (together with all its subdirectories: ''/attic'', ''/cache'', ''/index'', ''/locks'', ''/media'', ''/media_attic'', ''/media_meta'', ''/meta'', ''/pages'', ''/tmp'') and ''/conf'' (together with the following files: ''local.php'', ''local.protected.php'', ''acl.auth.php'', ''users.auth.php'', ''plugins.local.php'') directories and set the required permissions((*nix systems only)).

<code bash>
cd /var/www/farm
mkdir -p domain.org/{data/{attic,cache,index,locks,media,media_attic,media_meta,meta,pages,tmp},conf}
cd domain.org
find ./ -type d -exec chmod -v 777 {} \;
touch conf/{local.php,local.protected.php,acl.auth.php,users.auth.php,plugins.local.php}
chmod 666 conf/{local.php,acl.auth.php,users.auth.php,plugins.local.php}
</code>

**Note:** If you have root access on the server you could also change the owner of the respective directories and configuration files to the user/group under which your webserver is running and use more restrictive (secure) ''chmod'' settings. Assuming that the webserver user and group are ''www-data'' you could use the following commands inside the animal directory.

<code bash>
find ./ -exec chown www-data:www-data {} \;
find ./ -type d -exec chmod 775 {} \;
chown -R www-data:www-data conf/
chmod 664 conf/{local.php,acl.auth.php,users.auth.php,plugins.local.php}
</code>

=== Add Basic Configuration ===

This adds a basic configuration (with [[config:title]], [[config:lang|language]], [[config:superuser]] and activating [[:ACL]]s with [[config:useacl]]).

<code bash>
cat > conf/local.php <<'EOF'
<?php
$conf['title'] = 'Animal Wiki Title';
$conf['lang'] = 'en';
$conf['useacl'] = 1;
$conf['superuser'] = '@admin';
?>
EOF
</code>

=== Add Fixed Configuration ===

This adds some configuration to the ''local.protected.php'' ([[config:savedir]] and [[config:updatecheck]]) so that the admin of the wiki instance isn't able to overwrite it.

<code bash>
cat > conf/local.protected.php <<'EOF'
<?php
$conf['savedir'] = DOKU_CONF.'../data';
$conf['updatecheck'] = 0;
?>
EOF
</code>

=== Set Basic Permissions ===

This sets some basic permissions to "all can read, members of the ''@admin'' group can do anything" which can be altered later via the [[:ACL]] manager.

<code bash>
cat > conf/acl.auth.php <<'EOF'
# <?php exit()?>
* @admin 255
* @ALL 1
EOF
</code>

=== Add Admin User ===

The following adds a user 'admin' with password 'admin', the password and the user credentials should be changed via the update profile form ASAP.

<code bash>
cat > conf/users.auth.php <<'EOF'
# <?php exit()?>
admin:$1$cce258b2$U9o5nK0z4MhTfB5QlKF23/:admin:admin@example.org:admin,user
EOF
</code>

==== Using a Script to Setup an Animal ====

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.

<code bash 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:
</code>

**Usage Example:**

<code bash>
$> cd /var/www/farm
$> addanimal cat.domain.org
</code>

<code bash>
$> cd /var/www/farm
$> addanimal subdir
</code>


===== URL Rewriting =====

You can use **[[:rewrite|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 [[config:basedir]] configuration option in each animal.

The [[Symlink Farm]] supports URL rewriting, too.

===== Enabling/disabling plugins in animals =====

Since Angua the plugins can be enabled and disabled per animal using the plugin manager ([[devel: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 [[devel: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:

<code php>
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';
</code>

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
<code php>
$conf['disabled_plugins']['discussion'] = '1';
</code>

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

===== Discussion =====

==== Patch for using preload.php in an older release ====

If you want to get this with releases before rc2009-02-06, you could patch "init.php" like this <code php>
--- 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__).'/../').'/');
</code>

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. --- [[marg@rz.tu-clausthal.de|Christian Marg]]

==== Patch/Code for making DokuWiki commandline programs work (somehow) with DokuWiki farm ====

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:

<code php>
--- 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');
</code>
To create an index for every farm animal, you just have to iterate over all farm animals and call the indexer script for each one.\\
 --- //[[marg@rz.tu-clausthal.de|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:

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

With that you can use all cli scripts by executing
<code bash>
animal=YOUR_ANIMAL ./YOUR_SCRIPT.php
</code>
 --- [[user>Michitux]] //2010/10/30 14:39//
==== Variant of the directory based setup (farmer and animal at same directory level) ====

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).

<code>
<?php
/**
 * This overwrites the DOKU_CONF. Each farm gets its own configuration and data directory.
 * 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;
}
</code>

==== How to have subdirectories with the virtual host setup ====

You can have subdirectories with the [[#virtual host based setup]] (i.e. without a ''.htaccess'' file in the farm). After adding the animal directory to the farm (should be something like "domain.org.subdir"((see [[http://drupal.org/getting-started/6/install/multi-site|Drupal's multi-site page]] for more information on this))), you only need to create a [[wp>symlink]] in the farmer directory like this: <code>ln -s . subdir</code>

If you need to make subdirectories within a virtual directory setup work with [[config:userewrite]]=1, you need to add the following to the farmer's ''.htaccess'' for every subdirectory, right **before** ''RewriteRule ^$ doku.php  [L]'':
<code>
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
</code>

FIXME 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.

==== How to solve the problem with the login ====

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/farm/animal. To solve this, edit inc/preload.php and add these two lines into **if(isset($_REQUEST['animal'])**. You have to change the farm directory if you choose another.

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