DokuWiki Farms

A wiki farm is a collection of wikis running on the same web server and sharing one parent wiki engine. So, by running just one single parent wiki, you can power hundreds of independent other wikis (aka "animals"). All animals share one set of plugins and templates but each of them can have a different set of enabled plugins, a different template and a different configuration. The concept of farms is also called "multi-site", "multi-domain" or "sub-sites" in the context of other CMS.

Setup with Farmer Plugin

There are multiple ways to achieve running a wiki farm. Probably the easiest way is to use the Farmer Plugin which will set up the farm for you and provides means to create and manage the animals.

Manually Setup

This page describes how to manually set up a farm in the easiest and most straightforward way to run a wiki farm with DokuWiki. More advanced setups and tips are described on a separate page.

Terms

Directory Setup

The following example is the most common directory setup and it is used throughout this document. But you can have a very different setup.

In your farm directory you can have as many animals as you like, e.g.:

Two different setups

There are two different setups: Virtual host based and .htaccess based.

The Virtual host (or 'virtual web server') method combines features of a web-server and the way names are translated to internet addresses to provide access to different farm animals in the wiki farm based on the hostname used in accessing the wiki. In this case, multiple hostnames end up referring to the same web server – "wiki.mydomain.net" may provide access to the farmer wiki, while "programming.mydomain.net" may provide access to your wiki with programming tutorials, but they both connect to the same physical machine.

The .htaccess (or 'server script') method only requires features of a webserver to make different file paths refer to distinct wikis. A small script tells the webserver how to handle each wiki's top level directory differently, which allows for independent wikis. In this case, "www.mydomain.net/dokuwiki/" could be the start page for my farmer wiki, and "www.mydomain.net/programming" would access the programming tutorial wiki.

Regardless, both methods require some sort of server configuration.

Virtual host based setup

For systems you will want to access from elsewhere, you will need to publish the new name for the web server's host. When you want to run this setup, you will need to provide the new hostnames to any machine that might want to access your farms usually configuring a DNS server. If unsure, contact your system administrator or service provider for specific instructions.

To have access from your local machine, you have to edit the local 'hosts' file to make sure that your computer will know its new names. :!: This method only works when connecting from the same machine; other systems will not know the machine's additional names.

For Windows users, you will need to change the file c:\windows\system32\drivers\etc\hosts. In most setups, you will need to have administrator privilege to edit this file.

For Linux and other Unix-like systems, you will need to edit the file /etc/hosts.

For either system, you will want to add:

127.0.0.1	farm-animal.mydomain.net

(Where farm-animal is the name of the new wiki, and mydomain.net is appropriate for your system.)

.htaccess based setup

How to create a farm

0. Prerequisites

In the following steps we assume you have already installed a standard DokuWiki. Please make sure to either install it properly, so that it works like a normal wiki, or remove install.php for security reasons.

1. Create the farm directory

Create an empty directory named /var/www/farm. That will be your farm directory and needs to be writeable by the web server. That should be protected in the same way you would protect a normal DokuWiki.

2. Activate the farm

In the farmer directory, copy ./inc/preload.php.dist to ./inc/preload.php, open it and uncomment the two relevant lines and set your farm directory, so that it looks like this:

// set this to your farm directory
if(!defined('DOKU_FARMDIR')) define('DOKU_FARMDIR', '/var/www/farm');
 
// include this after DOKU_FARMDIR if you want to use farms
include(fullpath(dirname(__FILE__)).'/farm.php');

Note: If you don't have DokuWiki version Adora Belle (2012-10-13) or newer, those two files will be missing. In that case you can simply copy them over from here: farm.php and preload.php.dist.

Note: the path that you enter for DOKU_FARMDIR may need to be based on the "true" path to the server directory (as revealed by the PHP variable $_SERVER['DOCUMENT_ROOT']). Sometimes using a symbolic link does not work. For example, even if you normally access your farm server directory as "/public_html/farm", you might need to enter something like "/home/<htmlusername>/public_html/farm".

3. Add an animal

Extract this animal template into your farm directory. It is a directory (called _animal) which includes an (as good as) empty data and a pre-filled conf directory.

Then you need to rename that extracted directory. But the rules how to name the directory in which your animal stores all its files depends on the setup:

In case you're using the .htaccess based setup, you need to uncomment and change your animal's $conf['basedir'] in conf/local.protected.php to the path in the URL under which the animal can be accessed (for example '/animal/' if accessible at http://example.com/animal – but can be stored in /var/www/farm/animal).

4. Add required server settings

If you're not used to server configuration, this is the only more complicated bit. FIXME This and the following needs elaboration.

The alternatives are presented in processing order in inc/farm.php. If a .htaccess-based setup is recognized, the virtual server setup is ignored.

a. .htaccess Based Setup

This .htaccess file needs to be put into the farm directory. Remember to enable .htaccess in the Apache Configuration (AllowOverride All)

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

Change the /dokuwiki/ part to the path to the farmer.

b. Virtual Host Based Setup

For this setup you have to configure the virtual host for each new animal in your web hosting control panel or httpd.conf. Here is the httpd.conf example for subdomain.example.com:

NameVirtualHost *
 
<VirtualHost *>
    ServerName subdomain.example.com    # this is the URL of your wiki animal
    DocumentRoot /var/www/dokuwiki/     # the document root always needs to be the DokuWiki *farmer* directory
</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.

In some cases, a generic approach may be applied as well. For this, you don't need modifications in the apache configuration when you add a farm animal. Generic Apache configuration:

<VirtualHost *:80>
    ServerName example.com
    ServerAlias *.example.com
    VirtualDocumentRoot /var/www/%-2/%-3
    RewriteEngine On
</VirtualHost>

Each subdomain is automatically mapped to /var/www/example.com/<subdomain>. This arrangement makes sense when several domains point to the same server. In each of these subdomain directories, a symlink to the dokuwiki code directory must be created.

Each individual animal itself is in DOKU_FARMDIR/<subdomain>.example.com (mirrors the original URL).
This path must be created and the animal template (see above) may be copied herein.

5. Change the admin password

You're done, you can now simply go to your animal's URL (either subdomain.example.com or example.com/farm/animal/ depending on your setup).

:!: As the animal template includes a default "admin" user account with the password "admin". Please change the admin password as soon as possible. Just login with admin/admin, go to "Admin" > "User Manager", click on the admin user and change its password below. You should also change the admin's email address.

How to add more animals

After the initial setup, you only need to repeat add an animal, add required server settings (only in case of a virtual host setup) and change the admin password for each new animal.

Discussion

You can add questions and requests to the discussion page.

Orginalbeitrag: www.dokuwiki.org/farms

1)
But it would also work with any other of the following directory names: example or example.com