[[:farms|⇐ Go back]]

====== An example of setting up a wiki farm ======

When I set up my first wiki farm it took about 5 hrs.  The next one I expect will be significantly less than one hour.  So I thought it might be useful to others for me to post my administator's notes in a public place.  Please note that we're not necessiarly recommending this as the best way to do things but rather as a case study that works for us.

This page is meant to augment the offical documentation [[:farms]] not to replace it.  Please at least read that explanation before this one.

===== What we're trying to do =====

This server is in a specialized research center which is part of the Physics department in a large university.  We currently have 3 professors one full time staff (me) and between 15 an 30 graduate and undergraduate students participating in the research.

We want a semi-public wiki for the center and private wikis for each professor to manage projects and post results before being made public.  We will probably want very private wikis for working on grant proposals, or assembling data for publication

===== Environment =====

Our web server is running Scientific Linux 6.3 (SL6), similar to CentOS 6.3.  We are using Apache 2.2.

Our IT department has given us one external fixed IP address and one DNS entry.  It might be possible to get additional CNAME entries which are aliases for the IP address to allow one server to host multiple sites (see [[wp>CNAME_record|wikipedia's description]].  Thus we chose to use the .htaccess method, sort of.

We are using PHP v5.3.3 with the Zend Engine v2.3.0.

===== Overview of the process =====

Apache, PHP was already set up and running with a trusted SSL certificate.  The steps we're going to cover are:

  * Install the latest version of Dokuwiki from the tarball. (overview only)
  * Configure the base wiki (overview only)
  * Install the farm
  * Lock it down for restricted access

From the browser side of things the user cannot tell the difference between a farm of wikis and multiple installations of full or parent wikis.  We could install multiple copies of the whole dokuwiki tarball into separate directories on the web server but that would make the ongoing maintenance tasks much more complicated.

The reason for setting up a farm is that only the parent wiki needs to be updated to a new version, and plugins need only be installed once.  The Apache web server is also more efficient with one copy of the program but that is secondary.

===== The latest version of DokuWiki =====

In general, I am a big fan of using prepackaged software for each OS.  In this case however the package software was 2 years old, did not contain the farm module and scattered the php files in /usr/share/dokuwiki, /etc/dokuwiki and who knows where else.  Now that we have a working installation, we could probably work with the package but it was confusing.

The [[:install|installation guide]] is quite simple and easy to follow if you decide to go this route.

===== Configure the base wiki =====

There is nothing special about configuing the base wiki.  This is referred to as the "farmer" in the documentation and is the initial set up of a working Dokuwiki as explained in the installation guide.

This wiki needs to be up and running before we address the farm.  It contains all the code (PHP files) that drive the wikis.  The other wikis in the farm have only enough PHP code to separate them from each other.

===== Install the farm =====

==== Review of terminology ====

The farm metaphor maybe taking things too far but we'll be consistent and try to avoid the common computer documentation foible of mixing our metaphors.

  * **Farm**: The entire setup with one parent wiki (the farmer) and multiple child wikis (the animals)
  * **Farmer**:  The parent wiki that contains most of the PHP files that drive Dokuwiki.  It is also a complete wiki in its own right.  What's important in the setup is that we are able to access both the individual modules used by an animal (see below) and the main modules used by all the wikis.
  * **Farm Directory**: Not to be confused with the farm, is the root directory of all the child wikis.  This is just a directory in the webspace.  
  * **Animal**:  Remember the difference between a child wiki (animal) and the parent wiki (farmer) is what PHP files are kept in their directory.  Each animal contains a minimal number of .php files that are used to configure the dokuwiki plus directories containing all of the data for that wiki, while the farmer has a complete dokuwiki installation that is shared by all animals plus its own directories for data.  Thus only the parent needs to install plugins and only parent needs to be updated to a new version.  

==== What the browser sees ====

Our webspace is organized as:
  * ''%%http://whatsamatta.edu%%'' - home page
    * ''%%http://whatsamatta.edu/wiki%%'' - The parent wiki with material for consumption by authorized users, the **farmer**.
    * ''%%http://whatsamatta.edu/einstein%%'' - First professor's private wiki, an **animal** (child wiki).
    * ''%%http://whatsamatta.edu/keppler%%'' - Second professor's private wiki, another **animal**.

Everything else is ''%%http://whatsamatta.edu/somethingElse%%'' which is independent of Dokuwiki.

==== How our directories are organized ====

The organization and location of web server configuration files and content is flexible to say the least.  Conventons vary considerably especially if your in a shared or hosted environment.  This is a description of our system, not to be confused with a recommendation of how your system does or should look.

Web server configuration for these wikis are all contained in /etc/httpd/conf.d/dokuwiki.conf.  We created that file.

Web content is in /var/www/html and the relevant directories are:

<code>├── wiki                <--The farmer (parent wiki)
│   ├── bin
│   ├── conf
│   ├── data                  <-- These folders are what Dokuwiki uses
│   ├── inc
│   └── lib
└── wikis                     <--The farm (folder with child wikis)
    ├── _animal               <-- template for new child wiki
    ├── kepler                <-- animal (child wiki) #1
    ├── Kepler -> kepler      <--symbolic link for common errors
    ├── einstein              <-- animal #2
    └── Einstein -> einstein  <--symbolic link
</code>

The _animal directory is the template available on the [[farms:]] page {{:dokuwiki_farm_animal.zip|this animal template}}.  It is owned by root with 600 privileges so it is not accessible by the webserver. To prepare a new animal (child wiki) enter:

<code>
cp -r _animal newton
chown -R apache:apache newton
ln -s newton Newton
</code>

The symbolic links are just a pet peeve of mine.  I never know how people will capitalize a name, this makes newton and Newton go to the same place.

For our system every file and directory shown here (and their subdirectories) are owned by apache:apache and have permissions 640 for the files and 750 for directories.  Note the user and group names also varies considerably across installations.

==== The fun part: Configuration ====

The following files are modified or created:

=== In each animal (child wiki): (/var/www/html/wikis/einstein, /var/www/html/wikis/kepler...) ===

Edit  ''conf/local.protected.php uncomment'' and set ''$conf['basedir']''

For example change:
   //$conf['basedir'] = '/farm/animal/';
to
  $conf['basedir'] = '/wikis/einstein/';

I believe the trailing / is necessary so be careful.

We also changed ''conf/local.php'' to set the wiki title to help debugging but that can be done through the web interface after things are working.  If you want to do that, change:

  $conf['title'] = 'Animal Wiki Title';
to
  $conf['title'] = 'Albert\'s Wiki';
  
=== In the farmer directory (/var/www/html/wiki) ===


To activate the farm go the the inc directory in the farmer (parent wiki) directory

Copy the file ''preload.php.dist'' to ''preload.php''.  Note if you decided to work with an older version of Dokuwiki you will have to download farm.php and preload.php.dist (see the [[farms:|farms documentation page]]).

Uncomment the DOKU_FARMDIR definition and set the path.  Change:

  //if(!defined('DOKU_FARMDIR')) define('DOKU_FARMDIR', '/var/www/farm');
to
  if(!defined('DOKU_FARMDIR')) define('DOKU_FARMDIR', '/var/www/html/wikis');
  
Uncomment the farm module include:

  //include(fullpath(dirname(__FILE__)).'/farm.php');
  
=== Apache configuration ===
 
During the Dokuwiki installation we created a configuration file /etc/httpd/conf.d/dokuwiki.conf with several <Directory> directives that control access to the various directories. (I am looking for the link to the instructions on how to do that).

What we will do now is define aliases needed to shorten the url our users will enter and add the rewrite rules.

=== Aliases ===

As it stands user can enter a url that looks like ''%%http://wattsamatta.edu/wikis/einstein%%'' to get to that animal in the farm (child wiki), however the fact we chose to name our farm wikis is irrelevant so to shorten it to ''%%http://wattsamata.edu/enistein%%'' we include an alias directive for each child wiki:

  Alias /einstein /var/www/html/wikis/kepler
  Alias /kepler /var/www/html/wikis/kepler

=== Rewrite rules ===

The farms documentation presents two different methods for addressing farms:  Virtual Hosts and .htaccess.  With the virtual host method (which we don't use) the user would enter a url like ''%%http://einstein.whatsamatta.edu%%''.  With the .htaccess method (described below) that url would be ''%%http://whatsamatta.edu/einstein%%''.  The choice is usually determined by what tools you have access to.  We chose the .htaccess method because we cannot easily add CNAME records to the university's DNS server.

This is the only really, really arcane and obscure part.  What we want our users to do is enter ''%%http://whatsamatta.edu/einstein%%'' and what dokuwiki needs is more like ''%%http://whatsamatta.edu/wiki/doku.php?animal=einstein%%'' except of course when there not at the home page of the wiki then the uri is a lot more complicated.

This is done with rewrite rules which Apache uses to transform the actual url into the one we want.  It is a regular expression (which is bad enough) with additional flags.  For the most part you can copy these rules with minor, obvious modifications.  If you want to understand them better I found this Swedish website with a nice way to play with mod_rewrite rules see [[http://martinmelin.se/rewrite-rule-tester/]] (
tack så mycket Martin).

The farm instructions do this with a .htaccess file but we prefer to put them in a <Directory> directive.  Both work, Apache recommends the directive for performance reasons but .htaccess method works for people without root privileges.  Add the following to the dokuwiki.conf file:

<code>
  <Directory /var/www/html/wikis>
        AllowOverride All
        Options +FollowSymLinks
  
        RewriteEngine On
  
        RewriteRule ^/?([^/]+)/(.*)  /wiki/$2?animal=$1 [QSA]
        RewriteRule ^/?([^/]+)$      /wiki/?animal=$1 [QSA]
  
  </Directory>
</code>

At this point, if neither of us missed anything restarting the web server will produce a working wiki farm.  Type:
  service httpd restart
  
then try it from a browser.  

Good luck.