Farmer Plugin

Compatible with DokuWiki

2024-02-06 "Kaos" unknown
2023-04-04 "Jack Jackrum" yes
2022-07-31 "Igor" yes
2020-07-29 "Hogfather" yes

Easier creation and maintenance of animals in a dokuwiki farm

Last updated on: 2024-11-12
Provides: Admin, Action
Repository: Source

Similar to farm

Tagged with farm

Needed for farmsync

By Michael Große, Andreas Gohr

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 approach¹⁾.

Installation

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

Features

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

Glossary

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.

Farmer

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.

Animal

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 .

Inheritance

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.

Farm Setup

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.

Converting a manual Farm

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.

Configuration

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.

Usage

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

Remote API

The plugin provides a few endpoints via the Remote API to inspect the farm configuration and available animals. This can be used to auto-setup reverse proxy routes or Kubernetes ingress. Check the API explorer for details on the available endpoints.