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.
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.
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
For either system, you will want to add:
(Where farm-animal is the name of the new wiki, and mydomain.net is appropriate for your system.)
example.com/farm/dog, but with a more complex setup nearly the same flexibility as with the other setup is possible
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, 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: 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
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:
subdomain.example.comworks with a directory named
example.com/farm/catwould 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/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.
.htaccess file needs to be put into the farm directory. Remember to enable .htaccess in the Apache Configuration (AllowOverride All)
RewriteEngine On RewriteRule ^/?([^/]+)/(.*) /dokuwiki/$2?animal=$1 [QSA] RewriteRule ^/?([^/]+)$ /dokuwiki/?animal=$1 [QSA] Options +FollowSymLinks
/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
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
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.
You can add questions and requests to the discussion page.
One example for setting a farm has been detailed here.