01501: make release software tree "no-need-to-touch"

Summary: make release software tree "no-need-to-touch"
Created: 2024-04-09 21:40
Status: Open
Category: Feature, Documentation
Priority: 421
Version: 2.3.32

Description: for maintenance purposes, mainly easy updates of the pmwiki software, the release tree should be as such, that no changes need to be made to it. update procedure (at least at my site): have a release-free main directory, called eg "pmwiki" under which the software is symlinked out of the release-tree, namely the directories "scripts" and "wikilib.d" and the file "pmwiki.php".

scripts -> ../pmwiki-2.3.32/scripts/
wikilib.d -> ../pmwiki-2.3.32/wikilib.d/
pmwiki.php -> ../pmwiki-2.3.32/pmwiki.php

all other directories, like "cookbook", "files", "local", "wiki.d" are local and under my control. the only issue is the directory "pub", where there are some things coming from the release, mixed together with local stuff from cookbook, own skins, edittoolbar, LaTeXMathML, etc. from the maintenance perspective, this is messy. my proposal would be to keep the software-tree clean, so to say put the release stuff under a different directory, eg "defauts" (or whatever), so that "pub" could be used for local stuff only. goodguy00?

I agree, intermixed recipe/cookbook files are more difficult to update, that's why I started working on Cookbook:ExtensionHub.

If you update the PmWiki core from Subversion, it takes care of everything, leaving intermixed local files alone.

If you update from a downloaded release, you can use rsync which should take care of the core, leaving intermixed local files alone.

It is already possible to have a pristine "pmwiki" directory and run wikis with it, and it is a variant of WikiFarm, where your running wiki is a "field". Here is how.

  1. Have PmWiki in its own directory, separate from the wiki website (field), if possible outside of the document root.
  2. In the wiki field landing directory:
    1. Have a file index.php that only includes pmwiki/pmwiki.php.
    2. Create new directories "local", "cookbook", "pub", "pub/css", "pub/skins".
      • Place all Cookbook addons in "cookbook".
      • Place all local configuration in "local".
      • Place all custom CSS in "pub/css".
      • Place all custom skins in "pub/skins". This includes any core skin that you may have adapted for your needs.
    3. Move there your wiki.d directory to the field, or PmWiki will create a new one.
  3. If the "pmwiki" directory is outside the document root (recommended):
    1. Symlink the pmwiki/pub directory to the wiki, but with a different name, for example "defauts", "common" or "pmwiki-pub". I use "common" but maybe "pmwiki-pub" is more descriptive and future-proof if some day another person takes over the maintenance of your wiki.
    2. In your field/local/config.php file, define the $FarmPubDirUrl variable to the publicly-reachable URL of the "pmwiki-pub" symlink.
  4. If the "pmwiki" directory is inside the document root and browser-reachable, you probably don't want the core installation to be reachable and editable:
    • Add some server rule like in .htaccess to deny browser access to pmwiki.php (but allow access to pmwiki/pub).
    • Alternatively, deny access to the full pmwiki/ but symlink pmwiki/pub to field/pmwiki-pub as suggested above.
    • Alternatively, create pmwiki/local/config.php with only this: <?php exit();
    • These rules may make the installation non-pristine, remember to check if you need to restore any custom config.php or .htaccess file when upgrading.
  5. In field/local/config.php, if you include core scripts, instead of include("scripts/authuser.php"); use include("$FarmD/scripts/authuser.php"); ("$FarmD/" added).
  6. When you install Cookbook recipes, place them in field/cookbook instead of pmwiki/cookbook. In field/local/config.php instead of include("$FarmD/cookbook/recipe.php"); use include("cookbook/recipe.php"); ("$FarmD/" removed).
  7. When a cookbook recipe ships files for the pmwiki/pub directory, place them in the field/pub directory. If a recipe uses a configuration variable $FarmPubDirUrl to link to its files, normally in config.php you should be able to override this to use $PubDirUrl instead.

If you have more fields, it becomes (a little) more complicated, but I'd basically symlink the field/cookbook and field/pub/skins directories into the new field directory.

These quick ideas can get you started. We can add a better written Cookbook page some day. --Petko