Wiki source for RelocatingWikka

Show raw source

=====Relocating or Sharing a Wikka installation=====
>>See also:
~-[[WikkaSecureConfig | Securing the configuration]]
~-++[[ | #98: GetEnv is not a good idea]]++
~-[[ | #545: GetEnv() revisited AKA "Relocatable Wikka"]]
~~-++[[ | #470: GetEnv is not a good idea (take 2)]]++
~~-++[[ | #81: Retrieving user-information (Session Leakage)]]++
Also related:
~-[[HandlingWikkaConfig | Handling the Config(s) of Wikka]]>>
====A bit of history====
//From the Wikka archeology department.//

From the earliest point in its history, **[[Docs:WakkaWiki | Wakka]]** version 0.1 (dated 2002-09-04, going by the README signed by [[ | Hendrik Mans]]), [[WakkaWiki | 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 **[[Docs:WikkaWiki | 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 [[WikkaSecureConfig | 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, **un**comment 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:
* Override control: relocate or share Wikka components between installations.
* This file allows the administrator to override standard or default paths used
* by Wikka. This makes it possible to:
* - locate the site configuration file outside the webroot for security
* - share Wikka code between several Wikka sites running on the same server
* - share Wikka language files between several Wikka sites running on the same
* server: useful if you make adaptations to the texts or add a new translation
* - use an already-installed 3rd-party component from its own location instead
* of the one bundled with Wikka
* To use an override, uncomment the corresponding define and adapt the path
* to reflect your situation.
* There are two types of overrides:
* - Direct overrides will be used directly by Wikka
* - Configuration overrides define a <b>default</b> value for the configuration,
* which may be changed during installation or later by modifying the site
* configuration file. By using the overrides here you can provide consistent
* setup values for a collection of Wikka installations
* Naming indicates purpose:
* - All constants have a prefix "LOCAL": 'LOCAL' in this context means applicable
* to this particular instance of Wikka, although it these constants can
* actually be used to share system files between different installations, by
* pointing this all at the same location in all instances.
* - Constant names ending in "_PATH" define a <b>filesystem directory</b>; they
* should not end in a (back)slash
* - Constant names ending in "_CONFIGFILE" define a <b>filesystem path</b> for a
* configuration file; LOCAL_SITE_CONFIGFILE is for the site configuration file
* and does not need to exist before installation.
* - Constant names ending in "_URIPATH" define a <b>URI path component</b> to
* be used by Wikka to build a fully-qualified URL; they should not end in
* a slash.
* Tip 1:
* When defining <b>filesystem paths</b>, you can use relative, absolute, or
* fully_qualified paths (with a drive letter on Windows).
* You may also use a (normal) slash instead of a backslash on a Windows server:
* Wikka canonicalizes the paths, which automatically provides the slash type
* appropriate for the system it's running on.
* Tip 2:
* When defining <b>URI path components</b>, you can use the little "Compatibility"
* function <b>filesys2uri()</b> to convert any backslashes in an already-built
* or default filesystem path into forward slashes to use as a URI path.

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
%%(php)#if (!defined('LOCAL_SITE_CONFIGFILE')) define('LOCAL_SITE_CONFIGFILE','path/to/your/wikka.config.php');%%
and edit it to:
%%(php)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
%%(php)#if (!defined('LOCAL_LANG_PATH')) define('LOCAL_LANG_PATH','path/to/your/lang');
and edit it to:
%%(php)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
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki