Foswiki

Foswiki is a free enterprise collaboration platform written in Perl; developed, supported and maintained by its users and the open-source community.

Installation

Note: foswiki has the following disadvantages:

• Foswiki currently requires some user intervention on every upgrade.
• Foswiki has a convenient mechanism for installing, updating, and removing plugins that does not function unless the installation directory is writeable.

These instructions assume you will be using the directory /srv/http/foswiki to store your Foswiki installation.

The Foswiki Installation Guide is very thorough (although maybe a bit overwhelming), and makes an excellent reference. Follow along using the official guide, but you will find these notes to be more concise, and more specific to Arch Linux.

• You will need to install the following packages in order for Foswiki to work:
  • rcs
  • perl-crypt-passwdmd5
  • perl-cgi-session
  • perl-html-tree
  • perl-json
  • perl-libwww

• From the Foswiki website, determine the URL of the latest Foswiki release.
• Download and unpack the archive as the http user at /srv/http/foswiki. For instance (as root):

• Depending on how keen you are on locking down access to the Foswiki installation, you could restrict access to the installation directory:

# chmod o-rx .

• At this point, you want to ensure that all the files have the correct permissions. (See the Foswiki guide on Setting File Access Permissions for details.)

If you would like to determine whether the files already have the correct permissions, you can make use of to test permissions against the example commands listed in the above Foswiki guide. For instance, this will find any directories that do not have their access mode set to 755:

As of version 1.1.5, I found that only one file was incorrectly set to be owner-writable; all other files appeared to have the correct permissions fresh out of the archive. The following command can be used to set the correct permissions (either as root or http), and will also catch any similar files that may display the same issue in future:

• Copy bin/LocalLib.cfg.txt to , ensuring that ownership and access rights are identical to the original file.
• Edit your newly copied file so that the line reads as follows:

Apache

See the Configure the Webserver section of the Foswiki Installation Guide for guidance on getting set up with Apache.

Nginx

Setting up Nginx to work correctly with Foswiki is tricky, but almost everything you need is provided here. The configuration is heavily commented, to make it as easy as possible to modify it to suit your needs.

Foswiki is written in Perl and is generally intended to be run as a series of CGI scripts. Check out the FastCGIEngineContrib if you are interested in running Foswiki as a FastCGI application, but be aware that some plugins do not work well with this setup.

• Install (See the Nginx#fcgiwrap page). The rest of this configuration assumes you have set up using a socket.

• Create a file with the following contents at :

• Uncomment the directive near the top of the file, and replace with the IP address of your local machine.
• Now, add a new server section to your main nginx configuration file at /etc/nginx/nginx.conf; for instance:

/etc/nginx/nginx.conf

server {
  listen 80;
  server_name foswiki;
  root /srv/http/foswiki;

  include foswiki.conf;
}

• If you have not done so already, add an block before the blocks in , as the file references this:

• Follow the instructions from the Nginx Wiki to create an file at the required location. The above configuration expects such a file at . Do not forget to set sensible file permissions for this file. For instance, as root:

• Navigate your browser to the /configure URL, e.g.: http://foswiki/configure.
• In the General Path Settings section, remove the contents of the } setting. It should be completely blank. (This will make Foswiki use the pretty URLs we have set up in the Nginx configuration.)
• All other settings should be fine, so press "Save Changes", and choose a password to protect your configuration. (You may as well use the same password you set for your HTTP Basic Authentication.)
• Review the Foswiki configuration as desired, and save once more.
• Comment out the directive near the top of to protect the script.
• Your Foswiki installation should now be complete.

After Installation

Once your wiki is set up, you way also want to set up cron rules for:

• E-mail notifications
• Web statistics

Upgrade

The Foswiki Upgrade Guide is the official reference for the upgrade process, and is generally sufficient to help you with the upgrade. Remember to install any plugins that were used in the old installation. The easiest way to do this is to compare the lib/Foswiki/Plugins directories. The most painful part of the upgrade process is the copying of topics from the old installation to the new. A script is available that almost completely automates this process, leaving you only with the task of merging a few core topics that were modified in the old installation.

You can find the script here: https://github.com/giddie/bits-n-pieces/blob/master/Foswiki/foswiki-copy.

• Use (or your favourite derivative) to compare and any topics that need merging manually.
• It may be best to edit certain topics via the Web interface if you want Foswiki to save a revision with the original contents.
• Do not forget to copy:
  • The file containing the revision data if you are simply clobbering the new topic with the old one.
  • The folder of any topic you are merging manually, if it exists.
  • The file, which contains the users' password hashes.