git-svn-id: svn://pmwiki.org/pmwiki/trunk@1397 524c5546-5005-0410-9a3e-e25e191bd360

1 files changed, 11 insertions, 10 deletions

diff --git a/wikilib.d/PmWiki.WikiFarms b/wikilib.d/PmWiki.WikiFarms
index 6ffb9934..2f15c7b5 100644
--- a/wikilib.d/PmWiki.WikiFarms
+++ b/wikilib.d/PmWiki.WikiFarms
@@ -1,10 +1,11 @@
-version=pmwiki-2.1.beta38 ordered=1 urlencoded=1
-agent=Mozilla/5.0 (X11; U; Linux i686 (x86_64); en-US; rv:1.8) Gecko/20051128 SUSE/1.5-0.1 Firefox/1.5
-author=Pm
-csum=remove trailing ?>
-host=24.1.26.255
-name=PmWiki.WikiFarms
-rev=56
-targets=PmWiki.WikiFarms,PmWiki.WikiGroups,PmWiki.LocalCustomizations,PmWiki.Installation,PmWiki.PerGroupCustomizations,PmWiki.UploadsAdmin,PmWiki.DocumentationIndex
-text=%25audience%25 administrators (intermediate)%0a[[WikiFarms]] are a mechanism for running multiple independent wikis on the same web server from a single PmWiki installation.  If a `WikiFarm is a collection of independent wikis, then each independent wiki in the farm is commonly called a ''`WikiField''.  A person who manages the PmWiki software installation is commonly called a ''farm administrator'', the location of the PmWiki software is called the "farm directory" and any administrators of individual fields are called ''field administrators''.  Each field must have its own base URL, but can [[Cookbook:SharedPages|share pages]] and [[WikiGroups]], uploads, page templates, passwords, and other [[local customizations]] with other fields. For a quick explanation of what goes where and what it controls, see PmWiki:QuickFarms.%0a%0aThe remainder of this document describes how to setup `WikiFarms and individual fields of the farm, and assumes you are already somewhat familiar with the details of PmWiki [[installation]].%0a%0aAny PmWiki [[installation]] can become the `WikiFarm on a particular web server.%0a%0a!!!Setting up a `WikiFarm (farm administrator)%0a%0aSetting up a PmWiki installation to act as a `WikiFarm is fairly straightforward.  The farm administrator simply creates a ''local/farmconfig.php'' file in the farm's "home directory" (the directory in which pmwiki.php is installed).  This file would contain any [[local customizations]] that are to be performed for every field in the farm (''farmconfig.php'' replaces the ''config.php'' file of  a typical installation). Usually, this will mean setting $FarmPubDirUrl to reasonable settings for the new field.  A minimal ''farmconfig.php'' file might look like this:%0a%0a    [@%3c?php if (!defined('PmWiki')) exit();%0a      $FarmPubDirUrl = 'http://www.example.com/pmwiki/pub';%0a    @]%0a%0a$FarmPubDirUrl is used to provide fields with the URL location of the farm's ''pub/'' directory.%0a%0a->%25note%25Note: Depending on your setup, you may want to choose to install the main farm script (i.e. pmwiki.php) in a non-web-server-accessible location. If you don't, or can't, you may want to control access using .htaccess. See Cookbook:FarmSecurity for more info. %0a%0aYour PmWiki installation is now set up for farming.  Now you need to create fields to see it in action.%0a%0a!!!Setting up a field within the `WikiFarm (field administrator)%0a%0aOnce PmWiki has been set up for `WikiFarming, a new field is created by doing the following:%0a%0a1. Create a directory to hold the field.  Normally the field directory goes in a web-accessible directory (e.g., under ''public_html''), but it can be placed anywhere that a PmWiki installation would normally go. This could be a directory outside or inside the farm's home-directory.%0a%0a2. Create a PHP script (e.g., ''field.php'') in the field directory with the following line%0a%0a    %3c?php include([='=]''path/to/pmwiki.php'''); %0a%0awhere ''path/to/pmwiki.php'' is the file path to the farm's installation of PmWiki. Either an absolute file path ([@/home/username/pmwiki/pmwiki.php@]) or relative file path ([@../pmwiki/pmwiki.php@]) will usually work, although PHP doesn't understand ~username in file paths. Do not use a url path, i.e., there shouldn't be an '[@http://@]' in it anywhere. %0a%0a->%25note%25  Note that it's not sufficient to use symbolic links or file shortcuts to connect to the farm installation of ''pmwiki.php''; one has to use an include statement in order for PmWiki to be able to correctly determine the location of the farm's ''scripts/'' and other directories.%0a%0a3.  Change the field's directory permissions to 777.%0a%0a4.  Open a web browser and execute the ''field.php'' script you created in step #2.  This will create the needed directories for the field and should bring up a default PmWiki installation (with any default settings the farm administrator may have set).%0a%0a%0a!!!Local customizations in fields and farms%0a%0aEach field administrator can create a ''local/'' directory within the field directory for [[local customization(s)]] to be applied to the field.  This works just like a normal PmWiki installation--the file ''local/config.php'' holds settings for the entire field, and files of the form ''local/Group.php'' and ''[=local/Group.PageName.php=]'' are used for per-group and per-page customizations (see [[PerGroupCustomizations]]).%0a%0aThe PmWiki variable ''$FarmD'' points to the "home directory" for the PmWiki farm installation; thus a field administrator can use ''$FarmD/scripts/'' and ''$FarmD/pub/'' to refer to the farm's ''scripts/'' and ''pub/'' directories.%0a%0aA farm administrator can use the ''local/farmconfig.php'' file for customizations to be applied to all fields within the farm.  By default, farm customizations are performed before any field-customization files; however, the farm administrator can override some field-customizations by explicitly calling the field's config.php files (this effects all fields), as in:%0a%0a  %3c?php if (!defined('`PmWiki')) exit();%0a    # Settings performed before field-customizations%0a    $FarmPubDirUrl = 'http://www.example.com/pmwiki/pub';%0a    $Skin = 'pmwiki-farm';%0a%0a    # load the field's global and per-group customizations%0a    include_once('local/config.php');%0a    include_once('local/pgcust.php');%0a%0a    # Override field customizations here%0a    $EnableUpload = 0;            # disable uploads%0a  ?>%0a%0aIf extension scripts are used farm-wide and they are located in the farm's cookbook directory they should be loaded through entries in local/farmconfig.php like:\\%0a    [@include_once("$FarmD/cookbook/scriptname.php");@]\\%0asimilar includes can be done in any field's local/config.php file. Note the double quotes "..."; single quotes do not work.%0a%0a!!!Notes%0a%0a* Field directories can also contain local ''pub/'' (for installing any custom skins for the field for instance) and ''uploads/'' directories.  A per-field ''uploads/'' directory will normally be created in the field directory if uploads are enabled (see [[UploadsAdmin]]).%0a%0a* Pages distributed with PmWiki (e.g., documentation) are automatically shared among all fields in a farm.  This is controlled through the $WikiLibDirs variable, which defaults to looking in the farm's copy of ''wikilib.d/''.%0a%0a* Other pages can be shared by multiple fields in a farm (See [[Cookbook:SharedPages]]).%0a%0a* The file ''farmmap.txt'' in the farm's ''local/'' directory can be used to provide farm-wide InterMap links.  This may be useful for creating links to pages in other fields of the farm.%0a%0a* In general, fields can be created and administered from user accounts other than the one maintaining the farm if the underlying operating system permissions and PHP configuration settings allow it.  PHP's default configuration normally allows this, but some system administrators and web hosting services change the PHP configuration such that this is not possible.%0a%0a%25trail%25 %3c%3c|[[DocumentationIndex]]|>>
-time=1142183967
+version=pmwiki-2.1.2 ordered=1 urlencoded=1
+agent=Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.0.1) Gecko/20060111 Firefox/1.5.0.1
+author=NeilHerber
+csum=made number of steps = 3
+ctime=1142482306
+host=69.159.224.112
+name=PmWiki.WikiFarmsNeil
+rev=12
+targets=PmWiki.WikiFarmsAdvanced,PmWiki.WikiFarmsExamples
+text=%25audience%25 administrators (intermediate)%0aA [[(PmWiki:)WikiFarm(s)]] is a collection of two or more wikis running on the same web server and sharing a set of common components. There are many ways to configure wiki farms, but this page describes only one, in an effort to simplify the admin tasks for new wiki "farmers".%0a%0a!!!Why use a farm?%0aThe primary motivation for using a wiki farm is to reduce the amount of administrative work involved in managing several wikis. In a farm, most of the PmWiki code is stored in one place and is shared by all the wikis. An administrator can (for example) upgrade to a new version of PmWiki on every wiki in the farm by simply updating the shared components in a single location. %0a%0aEach wiki can have its own look and feel and can even have its own add-ons or "recipes" from the [[(Cookbook:)Cookbook(Basics)]]. From a reader's point of view, each wiki in a farm is completely independent, and appears as a separate web site. %0a%0a!!!Why not to use a farm%0aBecause the wikis in a farm are all independent, it is difficult (but not impossible) to provide services that require access to more than one wiki. For example, the PmWiki search function can only search within one wiki. Using a farm as a way of subdividing related content is generally a bad idea. A much better way to subdivide content is to use [[(PmWiki:)WikiGroups]].%0a%0a!!!I still can't decide if I need a farm ...%0aThe good news is that you don't have to decide in advance. In fact, the recommended procedure is to first do a "normal" or single [[(PmWiki:)installation]] of PmWiki. Use it for a while. Create pages and edit them. Get to know how to add recipes. Be sure to try out [[(PmWiki:)WikiGroups]] (they may be all you need).%0a%0aOnce you have decided that you need another wiki, you have two basic choices:%0a#Do a complete [[(PmWiki:)installation]] of PmWiki in a new directory. This gives you two totally independent wikis that are completely self-contained. This is '''not''' a wiki farm.%0a#Create a wiki farm using your existing wiki as the "home wiki" where most of the shared PmWiki components will live. %0a%0aChoice number 1 can be a good choice for several reasons:%0a*it is not a wiki farm, and requires no additional administrative knowledge - it's just two installations%0a*if you decide to move one of the wikis to another server, you can simply copy the wiki directory structure to the second server, and it will work (assuming there is a web server and PHP in place).%0a*you can run different versions of PmWiki on each wiki (good for testing new versions)%0a*no matter how badly you mess up one installation, it doesn't affect the other%0a%0aIf you choose to create a wiki farm, then read on ...%0a%0a!!!Prerequisites%0aBefore you create a farm, make sure that:%0a*you have a working installation of PmWiki ready to become the home wiki for your farm%0a*all of the wikis in your farm will be on the same web server%0a*each wiki will have a unique URL, such as http://www.example.com/wiki1/, http://www.example.com/wiki2/ and so on%0a%0a!!!Creating the home wiki%0aYou do have a working installation of PmWiki at this point, don't you? That's good, because it is about to become the home wiki of your farm.%0a%0aIn the directory that contains your home wiki, create the file ''local/farmconfig.php''. This file is used to hold any [[(PmWiki:local )customizations]] that apply across the whole farm. For example, you could assign an admin password in ''farmconfig.php'' that will be used by all of the wikis in your farm.%0a%0aIf the URL used to access your home wiki is http://www.example.com/pmwiki/ then a minimal ''farmconfig.php'' file would look like this:%0a%0a    [@%3c?php if (!defined('PmWiki')) exit();%0a      $FarmPubDirUrl = 'http://www.example.com/pmwiki/pub';@]%0a%0aThis loads the variable $FarmPubDirUrl with the URL location of your home wiki's ''pub/'' directory. All of the wikis in your farm will share this ''pub/'' directory, because that is where the skin definitions are kept.%0a%0aAmazing as it may sound, this completes all of the changes you need to make in order to turn your existing wiki into the home wiki of your farm.%0a%0a!!!Creating an additional wiki in your farm%0a1. Create a directory to hold the new wiki. This directory must be web-accessible, just like the directory that holds your home wiki.%0a%0a2. Create a file called ''index.php'' in the directory with the following contents:%0a%0a    %3c?php include([='=]''path/to/pmwiki.php''');%0a%0aThis allows your new wiki to share the PmWiki code stored in your home wiki. The ''[@path/to/pmwiki.php@]'' is the file path to ''pmwiki.php'' in your home wiki. Use an absolute file path ([@/home/username/pmwiki/pmwiki.php@]) or a relative file path ([@../pmwiki/pmwiki.php@]). Do not use a url path - there should not be an '[@http://@]' in it anywhere. For a web server running under Windows, you need to use a complete file path as in [@C:/Apache Group/Apache2/www/mynewwiki/@].%0a%0a3. Open a web browser and browse the URL of the new wiki.  This will be a web address starting with '[@http://@]'.  PmWiki will attempt to automatically create a writable ''wiki.d/'' directory where the wiki's pages will be stored.  If you see an error message, follow the instructions.  If you choose the option for a "slightly more secure installation" be sure to execute both commands.%0a%0aYour new wiki is now set up, and your farm now contains 2 wikis. To add more wikis, just repeat these 3 steps.%0a%0a%0a!!!Customization%0aEach wiki in a farm inherits the settings stored in ''farmconfig.php''. Do any customization that you want to apply farm-wide (to all the wikis) in ''farmconfig.php''.%0a%0aCreate a ''local/'' directory within each wiki's directory to hold [[(PmWiki:)local customization(s)]] that apply only to that wiki. Farm-wide customizations are processed before the individual wiki local customizations. %0a%0aThe PmWiki variable ''$FarmD'' points to the directory of your home wiki and it is used as a prefix to allow the other wikis to share PmWiki components stored in the home wiki. For example:%0a*''$FarmD/scripts/'' points to the shared ''scripts/'' directory%0a*''$FarmD/pub/'' points to the shared ''pub/'' directory%0a%0a!!!Notes%0a*It is important to remember that not all of the recipes in the Cookbook have been written for or tested with farms. Be sure to look for instructions on how to use a recipe on a farm.%0a*There are many, many more things you can do with farms. Some are described on [[WikiFarmsAdvanced]].%0a*If you would like to see some step-by-step examples of setting up a farm, see [[WikiFarmsExamples]].
+time=1142603539