phpwiki for Debian
------------------

This PHPWiki package should work straight out of the box, using a SQLite
database to store all of the PHPWiki pages.  Better performance can be
achieved by storing pages in an SQL database, such as MySQL or PostgreSQL. 
If you wish to do this, please read /usr/share/doc/phpwiki/INSTALL.mysql or
INSTALL.pgsql for full instructions.

The schemas are stored in /usr/share/doc/phpwiki/schemas.  One thing to
note: the default prefix (phpwiki_) should be removed for SQL backends
unless you have a desire to modify the provided schema files.

Known Bugs / Limitations
------------------------

In several situations, (initial page load after setup, editing pages, etc)
PHPwiki appears to be very inefficient in its memory usage. In cases where
this occurs you will be presented with an ugly error message about the 
PHP4 memory limit being reached. This is particularly common if your PHP
is still configured to the default memory limit of 8MB. In some cases 
(loading initial pages) you can work around the bug simply by reloading 
pages several times. 

A more robust solution is to modify php.ini to set PHP's memory limit to 
a higher value. I have found 16MB to be adequate for most tasks, but your
milage may vary. This issue has been raised with the PHPwiki upstream 
developers and it is hoped that it will be resolved in a future release.

In some situations on AMD64 the initial page load scripts have been
observed to get into a infinite memory allocation loop when the memory
limit is reached.

Wiki Configuration
--------------------

PHPWiki 1.3.10 introduced a new configuration file format which seperates 
the configuration directives from the index.php file. The package attempts 
to upgrade existing configurations seamlessly and should work in 95+% of 
cases.

However, if you have a complex configuration, particularly using external
authentication methods then it is highly likely that you will need to 
manually check over the upgraded configuration file.

Wiki Upgrades
--------------

When upgrading PHPwiki there are three major steps that need to be undertaken:

1) Upgrade the database
2) Upgrade the configuration file
3) Run the PHPwiki Upgrade Wizard

The package should automatically take care of the first two for you
(eg, upgrading and migrating configuration and database files) but it will
only do this for the system wiki (and is subject to the proviso on external
auth methods in the previous section). If you have created additional wikis not
managed by the Debian package you will need to upgrade them yourself. 

In all cases you will always need to perform the third step manually.

STEP 1: Database Schema

NOTE: If you only have a single wiki managed by the package you can skip this
step.

Database schema upgrades are usually handled by the PHPwiki upgrade wizard,
however this does not work reliably for database types other than MySQL. For
this reason the Debian PHPwiki packages ship upgrade schemas that can and 
are used to upgrade the database between versions without using the PHPwiki
upgrade wizard. In testing this has been found to be the most reliable way
of upgrading PHPwiki. 

The schemas are located in /usr/share/doc/phpwiki/schemas and are named
upgrade-<version>.sql. The is one schema file for each version of the package
in which the database changed. If there is no upgrade file for a particular
version of PHPwiki then the database format was not changed in that version. In
cases where database specific operations are required to perform an upgrade you
will find schemas named like <dbtype>-upgrade-<version>.sql. Where present you
should use this schema *instead* of the standard upgrade-<version>.sql schema.
Currently sqlite is the only database type to ship schemas of this type. 

An example will help to clarify things here:

You have a database created with the PHPwiki 1.3.7-4 package in 
/var/phpwiki/phpwiki_pagedb.db, you've just installed PHPwiki 1.3.11p1-1 and
need to upgrade your database. You would execute the following commands

# /usr/bin/sqlite /var/lib/phpwiki/phpwiki_pagedb.db < \
 /usr/share/doc/phpwiki/schemas/sqlite-upgrade-1.3.10.sql

# /usr/bin/sqlite /var/lib/phpwiki/phpwiki_pagedb.db < \
 /usr/share/doc/phpwiki/schemas/sqlite-upgrade-1.3.11.sql

If you had modified the package's configuration and were using MySQL instead of
SQLite then you could use the following commands

# mysql <dbname> <  /usr/share/doc/phpwiki/schemas/upgrade-1.3.10.sql
# mysql <dbname> <  /usr/share/doc/phpwiki/schemas/upgrade-1.3.11.sql

Once you applied each schema between the original version and the version of
the package to which you are updating to your database you are ready to move on
to the configuration upgrade step.

STEP 2: Configuration Upgrade

NOTE :This step is only required if you are moving from a version less than
1.3.10.

NOTE: If you only have a single wiki managed by the package you can skip this
step. But don't forget to verify the automatically generated config.ini

There is a script that you can use to move from your old index.php based 
configuration to a new config.ini configuration. It is called 
migrate-phpwiki-config and is found in /usr/share/phpwiki/ . The script 
takes a single argument which is a template config.ini that values from 
the old index.php configuration file should be inserted into. The old 
index.php should be fed to the script on stdin and the new config.ini 
file will be output to stdout. The template config.ini used for the 
transition can be found at /usr/share/phpwiki/config/config-template.ini

Example:
# /usr/share/phpwiki/migrate-phpwiki-config \
 /usr/share/phpwiki/config/config-template.ini < \
 /etc/phpwiki/index.php > /etc/phpwiki/config.ini

The migration script is expected to get most configurations correct, however
it is known not to handle complex external authentication setups. You should
verify the entire config by hand before using it just to be sure. Once you are
happy with the new configuration, make sure your webserver is running and move
on to step 3 to finish the upgrade.

STEP 3: Wiki Upgrade Wizard

To complete the final step run the PHPwiki Upgrade Wizard by firing up:
 http://<servername>/<wikilocation>/?action=upgrade
eg:
 http://localhost/phpwiki/?action=upgrade

You will need to login as the admin user so make sure you have configured the
ADMIN_USER, ADMIN_PASSWD and ENCRYPTED_PASSWD options correctly in config.ini
The package ships with no password by default, so if you haven't already
created one, do it now.

If you are using Postgres or MySQL you will also be prompted for your Database
Administrator credentials. In the Debian scenario 99% of the database upgrade
tasks have already been performed in Step 1 of the upgrade process. The upgrade
wizard simply finishes this off by updating some fields that changed locations
in the database (eg. cached_html). Due to this you can usually get away with 
entering your standard wiki database user credentials at the prompt. If you
want to skip the database upgrade completely and handle it yourself, choose
'Cancel' when prompted for the admin username and password.

As the upgrade wizard processes the new pages, it can run into the same bug
described above for the initial load scenario (it runs out of memory). If 
this happens, simply reload the page, it is idempotent, so running it two or
three times until you get the full page rendered should not have adverse
effects.

Once that's done you should be ready to roll with a brand new version of
PHPwiki!

Wiki Administration
---------------------

The Debian package of PHPWiki comes pre-installed with the Wiki
administration login disabled.  This is for security and ease of basic
installation.  Most common uses of the wiki are unaffected.  If you want to
enable wiki administration (needed for doing in-wiki backups, page deletion,
and page blocking, amongst other things) edit the ADMIN_USER, ADMIN_PASSWD,
and possibly the ENCRYPTED_PASSWD options in /etc/phpwiki/config.ini and set
them to your preferred values.

DBA Support
-------------

Previous versions of the PHPWiki package, (prior to 1.3.7-2), used DB4 by
default to store the Wiki pages. Existing Wikis will continue to use the
DB4 system, although I may figure out a smooth upgrade for those Wikis at
some later point.

SQLite is a fast, local SQL engine, with no separate server process, and
limited in-built security (file-permissions only).  This is perfect for
PHPWiki.

MySQL, PostgreSQL and mSQL are still supported by the Debian PHPWiki
package, you just have to edit your configuration and install the database
engine yourself.

External Authentication
-----------------------

PHPwiki supports using external methods (DBA, IMAP, LDAP) to manage wiki
user accounts. Use of these methods is currently not supported in any 
way by the PHPwiki packages. 

PHPwiki also appears slightly buggy with these methods, particularly in the
area of error handling. If you simply get a blank page when trying to login
to the wiki using an external authentication method it is likely that it is
misconfigured or you are missing a required PHP module to enable support for
that protocol (php4-imap, etc). Check the Recommends field of the package
control file for some suggested packages and the comments in the default
configuration file.

Multiple / Local wikis
------------------------

The following instructions were correct for versions of this package prior
to 1.3.10-1. They are untested with 1.3.10-1 however it is highly expected
that they will continue to work. You will also need to create a config.ini
file in the config directory in /~user/mywiki/config/ to contain the 
directives mentioned below. Use these instructions at your own risk and 
please submit a patch to update them once you get it working :) See the 
section entitled "Wiki Migration" above for some notes on upgrading 
wikis not managed directly by the package.

One gotcha that has been reported for versions 1.3.10 and greater is that 
the locales directory may not be a symlink to /usr/share/phpwiki/locales. 
Copying this directory explicitly to your new wiki location appears to fix
the problem.

This method assumes that you'll be accessing it from a user's home webspace
under the directory /~user/mywiki/:

* Copy /etc/phpwiki/index.php to somewhere else (say
$HOME/public_html/mywiki/).  You'll need root access for this part of the
task, since index.php can potentially contain passwords, it's not good to
leave it world-readable.

* Edit $HOME/public_html/mywiki/index.php to suit your new, local
customisations.  Remember to modify such things as the WIKI_NAME,
ADMIN_USER, ADMIN_PASSWD, perhaps ACCESS_LOG (since there's no guarantee
you'll be able to get a peek at the Apache one), set your database settings,
and anything else that looks nice.

* Point people at /~user/mywiki, and let them get wikiing (hmm, have I just
created a new word?)

That should give you a nice, happy user-run Wiki.  Creating multiple global
Wikis is similar, just copy index.php somewhere else (either under
DocumentRoot, or some other directory with an alias).

 -- Matt Brown <debian@mattb.net.nz>, Sat,  8 Jul 2006 10:23:31 +1200