DokuWiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

====== Farmer Plugin ======

---- plugin ----
description: Easier creation and maintenance of animals in a dokuwiki farm
author     : Michael Große, Andreas Gohr 
email      : dokuwiki@cosmocode.de 
type       : admin, action
lastupdate : 2019-03-20
compatible : Greebo, Frusterick Manners, Elenor of Tsort, !Detritus, !Hrun, !Ponder Stibbons, !Binky
depends    : 
conflicts  : 
similar    : 
tags       : Farm

downloadurl: https://github.com/cosmocode/dokuwiki-plugin-farmer/zipball/master
bugtracker : https://github.com/cosmocode/dokuwiki-plugin-farmer/issues
sourcerepo : https://github.com/cosmocode/dokuwiki-plugin-farmer
donationurl:

screenshot_img : plugin:farmer:03_create.png
----

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 [[:farms|DokuWiki Farms]] but offers more features and sometimes takes a slightly more opinionated approach((it does not use ''inc/farm.php'' but manages the farming on it's own)).

[[https://www.cosmocode.de/en/open-source/dokuwiki-plugins/|{{ http://cosmocode.de/static/img/dokuwiki/dwplugins.png?recache|A CosmoCode Plugin}}]]

===== Installation =====

Search and install the plugin using the [[plugin:extension|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 [[:farms|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|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

===== Screenshots =====

===== Development =====
=== Change Log ===

{{rss>https://github.com/cosmocode/dokuwiki-plugin-farmer/commits/master.atom date}}

=== Known Bugs and Issues ===

Please report bugs and issues at: https://github.com/cosmocode/dokuwiki-plugin-farmer/issues

Please fill all the letters into the box to prove you're human. L S R H T Please keep this field empty:

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 4.0 International