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.

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.

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.

• When talking about a farm it describes the whole setup containing all of the below. Usually there is only one farm per server.
• The farmer (aka parent wiki) is the actual DokuWiki installation. This is where all the code resides, where you install plugins and templates and what you will update on new releases. You only have one farmer per farm.
• The setup of a farm directory is what is needed to start farming. It is the physical parent directory of all the animals on your server. Just one single location on your farm server.
• The animals (aka child wikis) are the individual wiki instances. This means you can have plethora of these but each one will only contain the wiki data and animal specific configurations, no more code duplication.

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

• /var/www/dokuwiki – the DokuWiki engine, this needs to be accessible from the web
• /var/www/farm – the DokuWiki farm directory which contains all the animals

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

• /var/www/farm/animal – one wiki
• /var/www/farm/example.com – another wiki

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.

• What to configure: virtual hosts via Apache's httpd.conf or your hosting control panel.
• Resulting URLs: anything, e.g. example.com, subdomain.example.net or test.example.org:8080/foo/bar/.
• Advantages: It can create much more flexible URLs which are independent of the underlying file structure.
• Disadvantages: The possibility to set up virtual hosts is not always available. Some (especially cheap) hosting providers don't allow it.

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

• What to configure: .htaccess. Apache also needs to permit htaccess configuration.
• Resulting URLs: only "subdirectories" of one domain and farm, e.g. example.com/farm/cat or example.com/farm/dog, but with a more complex setup nearly the same flexibility as with the other setup is possible
• Advantages: If virtual hosts are not supported by the hosting provider, this is the only possible solution.
• Disadvantages: .htaccess files are not always supported by some hosting providers. But this solution is more likely to be supported than virtual hosts.

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.

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.

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

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:

• The virtual host setup needs animal directory names which reflect their URL. E.g. subdomain.example.com works with a directory named subdomain.example.com. ¹⁾
• The .htaccess setup needs the animal directory names exactly as they are called in the URL. E.g. example.com/farm/cat would need an animal directory called cat. If you are using a separate .htaccess file for each animal you can specify the animal name there.

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

If you're not used to server configuration, this is the only more complicated bit. 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.

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.

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.

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.

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.

You can add questions and requests to the discussion page.

Orginalbeitrag: www.dokuwiki.org/farms