Learn about DokuWiki
Learn about DokuWiki
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.
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
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 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.
Apache, PHP was already set up and running with a trusted SSL certificate. The steps we're going to cover are:
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.
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 installation guide is quite simple and easy to follow if you decide to go this route.
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.
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.
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.
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:
├── 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
The _animal directory is the template available on the farms page 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:
cp -r _animal newton chown -R apache:apache newton ln -s newton Newton
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 following files are modified or created:
conf/local.protected.php uncomment and set
For example change:
//$conf['basedir'] = '/farm/animal/';
$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';
$conf['title'] = 'Albert\'s Wiki';
To activate the farm go the the inc directory in the farmer (parent wiki) directory
Copy the file
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 documentation page).
Uncomment the DOKU_FARMDIR definition and set the path. Change:
//if(!defined('DOKU_FARMDIR')) define('DOKU_FARMDIR', '/var/www/farm');
if(!defined('DOKU_FARMDIR')) define('DOKU_FARMDIR', '/var/www/html/wikis');
Uncomment the farm module include:
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.
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
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:
<Directory /var/www/html/wikis> AllowOverride All Options +FollowSymLinks RewriteEngine On RewriteRule ^/?([^/]+)/(.*) /wiki/$2?animal=$1 [QSA] RewriteRule ^/?([^/]+)$ /wiki/?animal=$1 [QSA] </Directory>
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.