Farmer Plugin

This plugin allows you to set up a "DokuWiki Farm" – a single DokuWiki installation that can be used for many different Wikis ("animals") sharing the same code base but having different content. The plugin is similar to what's described in DokuWiki Farms but offers more features and sometimes takes a slightly more opinionated approach1).

A CosmoCode Plugin

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

  • setup the farm
  • create or delete animals
  • copy data from other animals on creation
  • manage animal plugins
  • let animals inherit settings from the farmer
  • automatically generate a logo and favicon for new animals
  • list existing animals
  • handle unknown animals

A farm setup is recommended for experienced Wiki administrators only. This plugin makes things easier, but a general idea of what you're doing is helpful. Best read DokuWiki Farms on how farms are usually set up manually first to understand what this plugin does in the setup phase.

The Farmer is the "main" wiki. It is a normal DokuWiki installation containing all the PHP code that makes DokuWiki. It also contains all Plugins and Templates you may want to use in the animals.

The Farmer is where you configure the whole farm setup (using the farmer plugin). Animals can inherit settings from the farmer. New animals are created from here.

The Farmer is a completely functional wiki. You can use it for it's own content, though generally it's recommended to keep the farmer mostly empty and have animals for each topic.

The Farmer is the only wiki you need to upgrade and the only wiki where you install and upgrade plugins and templates in.

A farm setup can have as many Animals as you wish. Each behaves like a real DokuWiki installation with it's own content and media data. It can inherit settings and users from the Farmer or have it's own unique configuration.

You can not install Templates or Plugins in an Animal – that's done in the Farmer only. But you can have different Templates and Plugins activated for different Animals.

There are two ways to access an animal:

Rewrite-Based

This is the poor man's version of farming. All animals are accessible under the same domain as the farmer, identified by a !parameter in the URL.

For example, if your farmer is available on http://yourdomain.com/dokukwiki/, an animal called foo would be accessible under http://yourdomain.com/dokukwiki/!foo/.

To have this working certain rewrite rules have to be set up. The farmer plugin offers to create these rules in your .htaccess file for you (requires an Apache webserver).

The !bang URL is a restriction of the farmer plugin - manual farms offer more flexibility here.

(Sub-)-Domain-Based

This is the cooler method, but requires a certain setup in your DNS. Animals are recognized by the domain name. That could be a full qualified domain or a subdomain. To make this work, the domain's web root has to point to the directory the farmer is installed in.

So if your farmer is available on http://yourdomain.com/, an animal could be accessible under http://foo.yourdomain.com/ or even http://www.thefoo.wiki/.

Setting up a wildcard sub domain in your DNS makes it easy to create new animals with a button click using the farmer plugin.

If you don't understand this section at all, it's probably not for you ;-).

One cool feature of the farmer plugin is that it manages how animals load their configuration info allowing you to set up inheritance. This means you can configure the default of all animals centrally in the farmer. Eg. you could configure to use a certain template in the farmer and all animals would automatically use the same template.

Of course each animal can then overwrite these configurations in their own settings.

Once installed, you'll find a new "Farming" entry in the Admin window. When a farm hasn't been set up yet, the Farm Setup dialog will occur automatically. It allows you to specify where your animals should be stored. Completing this setup will make your Wiki the Farmer.

The setup can also modify your .htaccess to use rewrite based farms.

If you're already running a manual farm, you have to jump a little hoop.

First make sure your inc/preload.php does not contain anything that's unrelated to farming - if it does, backup those parts and readd them later.

Next give an empty/non-existing directory as the animal part and complete the setup. When done, edit the newly created conf/farm.ini in your Farmer and point farmdir to where your old animals reside.

From that point on your farm should be up and running again. You might want to manually clean up your animal directories and make use of the inheritance feature for most settings.

The configuration tab of the farmer plugin allows you to setup some basic info and what settings should be inherited from the farmer. The integrated help text should get you started there.

Additional tabs in the farmer plugin allow you to:

  • create new animals – including the option to copy data from one animal to another (so you could have template animals)
  • configure plugins for animals – animal administrators are not able to install or enable plugins, this has to be done by the Farmer admin
  • delete animals

Change Log

Known Bugs and Issues


1)
it does not use inc/farm.php but manages the farming on it's own