This page explains how to install multiple wikis using a single copy of PmWiki.
Specifically, it explains how to install PmWiki (if it's a fresh installation), disable the home wiki (if you would like to), add a farm-wide configuration file, add a new wiki, and then another new wiki, then customize the wikis using bundled scripts, recipes from the Cookbook, and skins.
Introduction
There are many ways to set up a WikiFarm because PmWiki is such a flexible piece of software. In this example, we will start either from scratch or with an existing stand-alone installation, and finish with two (or two additional) freshly configured wikis, ready for authors to add content.
Here is how some terms are used in the context of this page.
- A wiki is a functioning Pmwiki site that has its own URL, stored wiki pages, and local configuration file (local/config.php).
- A WikiFarm is PmWiki configured to run multiple wikis. The term is related to the computing phrase "server farm".
- A home wiki is a wiki in a farm that's in PmWiki's directory. If you start with a stand-alone installation and add a wiki, the original wiki becomes a home wiki.
- Farm-wide refers to something that affects all wikis in a farm.
- Local refers to something that affects a certain individual wiki.
- A URL is a web address that you can reach with your web browser.
- A filesystem location is location on the server's filesystem.
A home wiki may or may not be running in the directory where the PmWiki software is installed. (In this example one won't be if you're starting from scratch.) Aside from the pub/ folder, PmWiki's installation location doesn't even need to be accessible via a URL.
Install PmWiki
(If you already have a stand-alone wiki you can skip ahead to "Add a farm-wide configuration file (farmconfig.php)".)
Start by installing a fresh copy of PmWiki. In this example, we will disable the home wiki so it is not necessary to set up a wiki.d/ directory, as described in installation. The two fresh, additional wikis we will be making, will be outside the PmWiki installation directory in web-accessible directories of their own.
For this example, we will suppose that our PmWiki installation is in:
/home/someuser/public_html/pmwiki/
The URL for the home wiki then would be this:
http://www.example.com/~someuser/pmwiki/pmwiki.php
Disabling the 'home wiki'
With the fresh installation of PmWiki we get one functioning wiki, the home wiki. Soon in this example, we will be adding two (or more) additional wikis placed as you wish at any URL on your site. If you would rather use those conveniently placed wikis, and not the home wiki, this is how you can disable it.
First, we will configure home wiki not to show up if accessed. Let's create a config.php. The filesystem location of the home wiki's local/config.php file is:
http://www.example.com/~someuser/pmwiki/local/config.php
Here are it's contents, just a line to disable the home wiki:
<?php header('HTTP/1.0 403 Forbidden'); exit;
Or, if you want to return an error page, use something like this:
<?php
## config.php - Disable the home wiki for this farm.
header("HTTP/1.1 403 Forbidden");
exit('<html>
<head><title>Forbidden</title></head>
<body><p>Status:403 Forbidden</p></body>
</html>');
At this point, if you visit http://www.example.com/~someuser/pmwiki/ you will probably see the directory file listing. To prevent that, it would be good to create an index.php file with similar contents:
<?php
## index.php - Disable a directory listing.
header("HTTP/1.1 403 Forbidden");
exit('<html>
<head><title>Forbidden</title></head>
<body><p>Status:403 Directory listing forbidden.</p></body>
</html>');
and place it in this filesystem location:
http://www.example.com/~someuser/pmwiki/index.php
Now what we have is essentially a locked-down stand-alone PmWiki installation.
Add a farm-wide configuration file (farmconfig.php)
Wikis in a farm are configured farm-wide (globally, in farmconfig.php) and individually (locally, in config.php). Local configuration overrides global (see PmWiki.WikiCascades?).
The farm-wide configuration file is placed in the local/ directory of the PmWiki installation:
/home/someuser/public_html/pmwiki/local/farmconfig.php
At minimum, farmconfig.php must specify $FarmPubDirUrl, the URL of the farm's pub/ directory. Here's a minimal farmconfig.php:
<?php if (!defined('PmWiki')) exit();
$FarmPubDirUrl = 'http://www.example.com/~someuser/pmwiki/pub';
Add a wiki
You can add a wiki in four simple steps.
- Create a directory somewhere in the web space.
- Add a wrapper script in that directory, that points to pmwiki.php in the initial installation.
- Add a local configuration file
- Let the PmWiki engine create a wiki.d/ directory for page storage.
For our example the directory will be wiki-one/ and the wrapper script will be an index file (index.php) in that directory:
/home/someuser/public_html/wiki-one/index.php
This script only needs one line:
<?php include('/home/someuser/public_html/pmwiki/pmwiki.php');
You could also use a relative path, rather than an absolute path:
<?php include('../pmwiki/pmwiki.php');
The URL will be either of these:
http://www.example.com/~someuser/wiki-one/ http://www.example.com/~someuser/wiki-one/index.php
The local configuration file will be in the local wiki's local/ subdirectory, so it's path will be:
/home/someuser/public_html/pmwiki/wiki-one/local/config.php
Here is an example local/config.php file:
<?php if (!defined('PmWiki')) exit();
## Title of this wiki
$WikiTitle = 'Wiki One';
## Produce a unique cookie prefix for this site.
$CookiePrefix = substr($tmp = md5(__FILE__), 0, 5).'_';
## Set an administrative password. (String from ?action=crypt)
$DefaultPasswords['admin']='yourcryptedpassword';
## Enable graphical user interface buttons on edit pages.
$EnableGUIButtons = 1;
## Enable RSS and Atom web feeds.
if ($action == 'rss' || $action == 'atom') {
include_once("$FarmD/scripts/feeds.php"); }
Now we have this directory structure:
wiki-one/
|-- index.php
`-- local/
`-- config.php
After we visit this wiki's URL and prepare writable a wiki.d/ it will look like this:
wiki-one/ |-- index.php |-- local/ | `-- config.php `-- wiki.d/
Add another wiki
The second new wiki will be installed in the same manner. The same wrapper script will be here this time:
/home/someuser/public_html/wiki-two/index.php
The URL will be either of these:
http://www.example.com/~someuser/wiki-two/ http://www.example.com/~someuser/wiki-two/index.php
The local configuration file goes in local/ subdirectory:
/home/someuser/public_html/pmwiki/wiki-two/local/config.php
Here are the contents of local/config.php for Wiki Two. (Only the wiki title and password are different.):
<?php if (!defined('PmWiki')) exit();
## Title of this wiki
$WikiTitle = 'Wiki Two';
## Produce a unique cookie prefix for this site.
$CookiePrefix = substr($tmp = md5(__FILE__), 0, 5).'_';
## Set an administrative password. (String from ?action=crypt)
$DefaultPasswords['admin']='yourcryptedpassword';
## Enable graphical user interface buttons on edit pages.
$EnableGUIButtons = 1;
## Enable RSS and Atom web feeds.
if ($action == 'rss' || $action == 'atom') {
include_once("$FarmD/scripts/feeds.php"); }
After we visit this wiki's URL and prepare a writable wiki.d/ directory to hold its wiki pages, Wiki Two's directory structure will look like this:
wiki-two/ |-- index.php |-- local/ | `-- config.php `-- wiki.d/
Bundled scripts (the scripts/ directory)
If a wiki isn't a home wiki installed in the same directory as the PmWiki software you will need to make a small change to how you include a bundled script in local/config.php.
Instead of this:
include_once("scripts/somescript.php");
you will use this (with "double" quotes not 'single' quotes):
include_once("$FarmD/scripts/somescript.php");
Recipes (the cookbook/ directory)
Since each wiki in a farm is very similar to a stand-alone wiki, you can install recipes in the wiki's cookbook/ directory (you will need to create one) in the same manner as you would for a stand-alone wiki.
Better yet, you install a recipe in the farm's cookbook/ directory (the one included with the distribution) and it will become available to all of the wikis in the farm. All you need to do is make a slight change to the line that includes the recipe's script.
Instead of this:
include_once("cookbook/somerecipe.php");
you will use this (with "double" quotes not 'single' quotes):
include_once("$FarmD/cookbook/somerecipe.php");
Skins (the pub/skins/ directory)
Skins can be installed farm-wide, locally, or both. Just as with configuration variables, the local version overrides the farm-wide version if both exist.
Skins you want globally available for any wiki in the farm should be installed in the farm's pub/skins/ directory, which you need to create if it's not there. Any exclusive skin for an individual wiki belongs in that wiki's pub/skins/ directory.
Notes
A wiki outside the web document tree
Another way to establish a WikiFarm from scratch:
- Unpack the PmWiki software somewhere outside the web document tree.
- Move the pub/ directory to somewhere in the web space.
- Add a local/farmconfig.php and set two variables:
- Set
$FarmPubDirUrlto the URL of the pub/ directory. - Set
$SkinLibDirsto reflect the new location of your farm's moved pub/ directory.
- Set
- Create wikis using the four steps.
Example farmconfig.php:
<?php if (!defined('PmWiki')) exit();
## The URL location of the farm-wide pub/ directory
## is in the web document root on this server.
## Auto-adapt the protocol to http/https
if (@$_SERVER['HTTPS'] == 'on'
|| @$_SERVER['SERVER_PORT'] == '443')
{
$proto_and_host= 'https://'.$_SERVER['HTTP_HOST'];
} else {
$proto_and_host= 'http://'.$_SERVER['HTTP_HOST'];
}
$FarmPubDirUrl = $proto_and_host.'/pub';
## We moved pub/ - adjust $SkinLibDirs accordingly.
$SkinLibDirs = array(
"./pub/skins/\$Skin" => "$PubDirUrl/skins/\$Skin",
"/var/www/pub/skins/\$Skin" => "$FarmPubDirUrl/skins/\$Skin");
Whenever you move pub/ away from the default
location (a subdirectory of $FarmD) you'll need to
set $SkinLibDirs to reflect the new
filesystem location
of your farm's moved pub/ directory.
Creating empty directories
content/ |-- cookbook/ | |-- .htaccess | `-- index.php |-- local/ | |-- .htaccess | |-- config.php | `-- index.php |-- pub/ | |-- css/ | | `-- index.php | |-- skins/ | | `-- index.php | `-- index.php `-- index.php
It may be less confusing to create some empty directories right from the start when a new wiki is added to the farm. A freshly-minted wiki with empty cookbook/, pub/css/, and pub/skins/ directories has a directory structure like this:
content/ |-- index.php |-- local/ | `-- config.php |-- cookbook/ |-- pub/ | |-- css/ | `-- skins/ `-- wiki.d/
Denying direct access to directories
Your local/ and cookbook/ directories are never accessed directly by browsers in PmWiki. (That's what pub/ is for.) You can add an index.php file to prevent directory listing and a .htaccess? server configuration file to deny access in those directories.
# .htaccess - Apache fileserver configuration file # This file is in the directory to prevent the directory's # contents from being accessed directly by browsers. # (This is a potential, albeit very unlikely, security hole.) Order Deny,Allow Deny from all
See Also
- WikiFarmAlternative provides methods for sharing PmWiki amongst co-located sites and safeguards the wiki.d directory.