Relocating or Sharing a Wikka installation

A bit of history

From the Wikka archeology department.

From the earliest point in its history, Wakka version 0.1 (dated 2002-09-04, going by the README signed by Hendrik Mans), Wakka has supported a mechanism to locate its configuration file somewhere else than in the installation directory. That mechanism was to look for an environment variable called WAKKA_CONFIG, using the PHP call getenv(). If that variable is set and the file it points to exists, that is loaded as the configuration file, otherwise the default location in the installation directory is used.

I have not been able (yet?) to trace any documentation of why this was done, but my guess would be it was intended to be able to store the configuration file outside the webroot for security reasons: the configuration includes all data necessary to access the database the wiki uses, which is a security risk.

From the earliest incarnation of its successor Wikka (version 1.0.0) right through version, that mechanism has remained in place. Unfortunately, getenv() (AKA GetEnv()) itself constitutes a security risk, as pointed out by several Wikka users on this site and on one of the mailing lists. Not sure who got there first, but a likely candidate is DotMG, whose original post on WikkaBugs now lives on as #98: GetEnv is not a good idea. In effect, we had an insecure method to enhance security...

Meanwhile I was looking at security aspects for several areas of Wikka, and came up with a possible solution for a secure configuration in Securing the configuration, its first incarnation dated 2004-12-16. My primary concern was the presence of such sensitive data as database access parameters in the installation directory, but I did refer to the security risk posed by using getenv(). The last edit on that page was 2005-05-29... nothing much came of it, it seems. Until several people independently discovered that getenv() itself was a security risk, and started mentioning it to us here and there.

Security: getting rid of GetEnv() first

A preliminary solution

In February it came to our attention that a "highly critical" bug in PHP had been fixed in version 5.2 but not in any 4.x version. After a bit of research, it seemed we could devise a workaround - important since many hosters still provide PHP 4.x and not any 5.x version, and many Wikka installations run on such servers. We decided to create a special "security release" (which became with a workaround for this PHP security problem, and then put in all other security fixes we had already in place in the trunk, as well as every other security fix we could come up with. So... trawling through old emails, I stumbled over good old GetEnv() again. No time for any architectural work, but GetEnv() had to go.

I opted for a very simple solution, replacing the optional environment variable WAKKA_CONFIG with the equally optional constant WAKKA_CONFIG. Unfortunately, the release notes for originally only mentioned that GetEnv() had been "dropped", while in fact it had been replaced (now amended). But one has to edit the core wikka.php file to get the functionality back: clumsy, though functional.

Of course this clumsy (but secure) solution was never meant to be more than a preliminary solution, so for the upcoming version 1.1.7 the plan was to come up with a more structural solution.

Getting back to relocating files

A more structured approach.

A single file relocatable?

A more structured approach? Well, it's obvious that we still need to be able to relocate the site configuration file. It's also obvious that having admins edit the wikka.php file isn't really a good idea - that was a crutch. But the idea of using a constant (rather than GetEnv()) to point to a file's real location instead of the default location as assumed in the default Wikka installation is fine.

It's also an extensible idea. If you can relocate one file, you can relocate other files. And if you can relocate files by pointing to another location, you can also share files.

All code relocatable and shareable!

For instance, we bundle several third-party libraries that people may actually already have installed. Why install them twice? It would be far more sensible and economical to just point Wikka to where it's already installed. Upgrading such a third-party library or class would then also need to be done only once, with all packages using it (including Wikka) automatically inheriting the newer version.

Or, you may have adapted or even translated the language files that come with Wikka. If you then install a second wiki using Wikka, it would be nice if you could just share the language libraries instead of copying it all over to your new install.

If you added a number of new home-grown or third-party actions or handlers, you might want to share those with a second installation of Wikka running on the same server as well.

Files, code...

All of these can be relocated or shared using the same simple mechanism already used for the site configuration file: using an optional constant defining an alternative path, and having the core wikka.php look for these and use them as override for an internal constant if found.

A single file to do it all

All optional

Please note that all of this is completely optional: Wikka will install just fine without making any changes to the "override file": no need to edit anything at all before running a new installlation.

But if you have access to a directory outside the webroot, read on how to make your Wikka installation more secure by just editing one line of code. See Case 1.
Wikka now (as of the current trunk version) comes with a file called override.config.php in the installation directory which is the key to this mechanism. As installed, it consists of nothing but comments, but if you want to relocate or share any of the relocatable components, just open the file, uncomment the appropriate define() statement, and edit it so it points to where the file or directory lives, or where you want the site configuration to be created on install. However, you really should do this before embarking on a (new) installation: doing it afterwards is not impossible but takes more manual work.

The override file override.config.php is more than just comments - those comments actually consist mostly of extensive documentation for how it works and for each of the overridable paths. The names of the definable constants also give a clue to what they are for. The main documentation block of override.config.php explains:
  1. /**
  2.  * Override control: relocate or share Wikka components between installations.
  3.  *
  4.  * This file allows the administrator to override standard or default paths used
  5.  * by Wikka. This makes it possible to:
  6.  * - locate the site configuration file outside the webroot for security
  7.  * - share Wikka code between several Wikka sites running on the same server
  8.  * - share Wikka language files between several Wikka sites running on the same
  9.  *   server: useful if you make adaptations to the texts or add a new translation
  10.  * - use an already-installed 3rd-party component from its own location instead
  11.  *   of the one bundled with Wikka
  12.  *
  13.  * To use an override, uncomment the corresponding define and adapt the path
  14.  * to reflect your situation.
  15.  *
  16.  * There are two types of overrides:
  17.  * - Direct overrides will be used directly by Wikka
  18.  * - Configuration overrides define a <b>default</b> value for the configuration,
  19.  *   which may be changed during installation or later by modifying the site
  20.  *   configuration file. By using the overrides here you can provide consistent
  21.  *   setup values for a collection of Wikka installations
  22.  *
  23.  * Naming indicates purpose:
  24.  * - All constants have a prefix "LOCAL": 'LOCAL' in this context means applicable
  25.  *   to this particular instance of Wikka, although it these constants can
  26.  *   actually be used to share system files between different installations, by
  27.  *   pointing this all at the same location in all instances.
  28.  * - Constant names ending in "_PATH" define a <b>filesystem directory</b>; they
  29.  *   should not end in a (back)slash
  30.  * - Constant names ending in "_CONFIGFILE" define a <b>filesystem path</b> for a
  31.  *   configuration file; LOCAL_SITE_CONFIGFILE is for the site configuration file
  32.  *   and does not need to exist before installation.
  33.  * - Constant names ending in "_URIPATH" define a <b>URI path component</b> to
  34.  *   be used by Wikka to build a fully-qualified URL; they should not end in
  35.  *   a slash.
  36.  *
  37.  * Tip 1:
  38.  * When defining <b>filesystem paths</b>, you can use relative, absolute, or
  39.  * fully_qualified paths (with a drive letter on Windows).
  40.  * You may also use a (normal) slash instead of a backslash on a Windows server:
  41.  * Wikka canonicalizes the paths, which automatically provides the slash type
  42.  * appropriate for the system it's running on.
  43.  *
  44.  * Tip 2:
  45.  * When defining <b>URI path components</b>, you can use the little "Compatibility"
  46.  * function <b>filesys2uri()</b> to convert any backslashes in an already-built
  47.  * or default filesystem path into forward slashes to use as a URI path.
  48.  */

Finally, when wikka.php finds one or more overrides active, it does some "sanity checks" on the overrides to be reasonably sure they are actually usable for their purpose - if not, the internal default path is used.

What this can do for you

A few example use cases.

This section gives a few example of use cases and how to accomplish relocating or sharing files for them. In (nearly) all cases you first need to unpack the installation archive, find the file called override.config.php in the base directory, and edit it. Individual cases below will outline what to edit, and how - and what to do next.

Case 1: Moving the site configuration file out of the web root

If you have access to a directory that is outside the web root and which is therefore "invisible" to a browser, you really should be doing this as this will make your Wikka installation more secure. It all takes much longer to describe than to do! We'll go into a bit more detail in this first case: the technique used here is basically the same as that for all following cases.

Many hosts provide one extra level "above" the web root. For instance, you may have a home directory that corresponds to the root you FTP to, and within that a "WWW" directory which is your webroot, and what the browser will see. The webroot may also be called something like "html". Consult your host's documentation. Any files located "next" to that webroot directory (maybe in a separate directory that you can create there) cannot be seen by a browser but are usable by any software running on the server, including Wikka. If you're running your own server, you will have access to a whole file system and more freedom to find a secure location for your site configuration file.

Situation 1: fresh install
I'm going to take my own local test server (running on Windows) as an example, but the principles remain the same. Plan where to install your Wikka, and where to have your configuration file created so it's outside the webroot. Then, figure out the path for the configuration file, either as an absolute path or as a path relative to your Wikka installation directory.

My test server runs on a "J:" drive, where the webroot corresponds to J:\Server\XAMPP 1.5.0\htdocs; I'm going to install Wikka in its own directory below the webroot. I've also created a var directory (modeled on a Unix system) at J:\Server\XAMPP 1.5.0\var which would be a good location for the configuration file.

Howto 1
In override.config.php uncomment the line
#if (!defined('LOCAL_SITE_CONFIGFILE')) define('LOCAL_SITE_CONFIGFILE','path/to/your/wikka.config.php');

and edit it to:
if (!defined('LOCAL_SITE_CONFIGFILE')) define('LOCAL_SITE_CONFIGFILE','J:\Server\XAMPP 1.5.0\var\wikka.config.php');   // outside webroot

For the target location, each of the following would actually work:
J:\Server\XAMPP 1.5.0\var\wikka.config.php
\Server\XAMPP 1.5.0\var\wikka.config.php
/Server/XAMPP 1.5.0/var/wikka.config.php

That's because wikka.php will canonicalize all those and come up with "J:\Server\XAMPP 1.5.0\var\wikka.config.php". (Note that the last path is relative to the (intended) Wikka installation in a subdirectory below the webroot: one ".." takes it up to the webroot, the second ".." takes it to XAMPP 1.5.0, and then it goes down into var again.)

Once that's done, save the modified file. Now copy the lot into the intended subdirectory under the webroot, and run the installer from the browser. wikka.php will interpret (and validate) the override before triggering the installer; the installer in its turn will pick up the overridden path, and create the site configuration file there.

Situation 2: moving the file from an existing installation
Actually, relocating the site configuration file is one of the cases where it's actually easy to do this on an already-installed Wikka.

Howto 2
  1. Copy your existing site configuration file wikka.config.php to the new location
  1. Find the override.config.php file in your installation (download if necessary) and edit as indicated above
  1. Save the edited override file (and upload if necessary): the site should now be using the configuration file in the new location
  1. Remove the site configuration file from the installation directory

You can even combine these two when upgrading your Wikka to the latest version - just make sure you *copy* your existing site installation file to the new location before editing the override file and then running the installer to upgrade as usual.

Case 2: Sharing language files between multiple Wikka versions

Consistency helps to make sites more user-friendly, and defining things in just one place is good programming practice. So when you've done extensive work on the language files, maybe adding a translation, or just replacing our Americanisms with your Britishisms, and now want to create a second Wikka installation, it would be great if you can just share those language files, instead of copying them and getting them out of sync when you do more work on them. Now you can!

In general, the approach is like that for the site configuration file, only this time you're sharing a directory instead of relocating a file. And again, all it takes is editing a single line of code. Let's assume your existing Wikka installation (with no relocations) lives in subdirectory smartwiki below the webroot, and your new one is going to be next to it, at dumbwiki.

In override.config.php uncomment the line
#if (!defined('LOCAL_LANG_PATH')) define('LOCAL_LANG_PATH','path/to/your/lang');

and edit it to:
if (!defined('LOCAL_LANG_PATH')) define('LOCAL_LANG_PATH','../smartwiki/lang');

That makes it a relative path: one ".." takes it up to the webroot from your new dumbwiki directory, then down into smartwiki, within which we find the lang directory at its normal location. Note that for a directory path you should not add a slash at the end (as described in the documentation in the file!). Of course here again you can also use a fully-qualified path or an absolute path.

Once that's done, you no longer need to copy the lang directory from the installation package to your new wiki: you'll be saving some space as well. Just install with your modified override file, and your new dumbwiki will use smartwiki's adapted language files, and be always up to date when you make changes to those files there.

Case 3: Sharing an expanded actions collection between multiple Wikka versions


Case 4: Sharing GeSHi with another application


Case 5: Installing a second Wikka sharing as much as possible with the first one


Case 6: Starting from scratch and installing two instances of Wikka



CategoryDevelopmentArchitecture CategoryDevelopmentSecurity
There is one comment on this page. [Display comment]
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki