Foswiki Installation based on Subversion

SUBVERSION IS NOW READ ONLY See GitBasedInstall for information about running from a git checkout.

Once you have followed the instructions in SvnRepository you can run a Foswiki from this checkout area simply by pointing Apache at it in the normal way and running configure.

By default the checked-out Foswiki core won't include any of the extensions (plugins or contribs). To enable extensions in a checkout area, you can either install them the normal way, or use the pseudo-install.pl script to install them. On Unix/Linux this script generates soft-links from the core tree to the extensions, so you can work on your code in situ and see the impact of the changes on your live foswiki without needing to do an install step. Windows doesn't support soft links, so the script can also be run in -copy mode (the default on Windows), but in this case you will have to re-run it each time you change your extension. Remember you have to enable any plugins you want to test in configure.

Use pseudo-install.pl default to enable the default contribs and plugins (e.g. TwistyContrib which is relied on by PatternSkin) and pseudo-install.pl all to install the whole works.

See the header comment of the pseudo-install.pl script (top level of checkout) for options and more information. Note that pseudo-install.pl only works with extensions that have a MANIFEST file, as required by the BuildContrib.

Script examples below are for bash shell.

Example of running pseudo-install

The typical situation is that you want to run a pseudo-installed Foswiki checked out from the trunk. And if you develop plugins, you want to be able to activate your plugin in this installation. This is the entire sequence for checking out the trunk from subversion and doing the pseudo-install. We assume that you want to run your Subversion based install in /var/www/foswiki

The following commands check out an absolutely minimal Foswiki (the core + default user mapping only). This is the smallest checkout that will run. The steps are:

1. create the root directory called foswiki
2. checkout the core from the subversion trunk
3. checkout TopicUserMappingContrib
4. pseudo-install TopicUserMappingContrib
5. change the ownership so the entire tree is owned by the user running the Apache. In this example the user name is "apache".
6. point Apache at the checkout

Change the commands to fit your actual file locations and Apache user. Some commands may have to be run as root.

cd /var/www
mkdir foswiki
cd foswiki
svn co http://svn.foswiki.org/trunk/core core
svn co http://svn.foswiki.org/trunk/TopicUserMappingContrib TopicUserMappingContrib
cd core
# create a default LocalSite.cfg config
./pseudo-install.pl -A
# install TopicUserMappingContrib (defaults to use softlinks)
./pseudo-install.pl TopicUserMappingContrib
# create a password file for users
htpasswd -c data/.htpasswd foswiki
# adjust bin/LocalLib.cfg.txt to add your paths to @INC and save it as bin/LocalLib.cfg
#  - also enable ASSERT and CPANBASE prepending in LocalLib.cfg if desired
# cp bin/LocalLib.cfg.txt bin/LocalLib.cfg
# pwd -P  # copy this answer to your clipboard
# emacs bin/LocalLib.cfg  # Use this clipboard'd line for $foswikiLibPath =
cd ..
# If necessary, change ownership of all files to the webserver user.
# In this case that is 'apache:apache', though it may also be 'www-data:www-data'
# e.g. on Debian and Ubuntu systems, or something else entirely. Check first.
chown -R apache:apache .
# Now configure Apache to use the Foswiki in /var/www/foswiki/core

1. Use to generate configuration http://foswiki.org/Support/ApacheConfigGenerator?vhost=example.com&dir=%2Fvar%2Fwww%2Fexample.com%2Ffoswiki&pathurl=%2Ffoswiki&allowconf=&requireconf=&engine=CGI&fastcgimodule=fastcgi&apver=2&shorterurls=enabled&loginmanager=Template&phpinstalled=None&errordocument=UserRegistration
2. Clipboard copy and save this to core/../foswiki.httpd.conf
   • cat > foswiki-svn_httpd.conf
3. Include this httpd.conf from your apache httpd.conf
   • If you are on a Mac, you can put this file into /etc/apache2/other/ and line "Include /private/etc/apache2/other/*.conf" will pick it up.
   • Otherwise, edit your httpd.conf and add: Include /path/to/foswiki-svn_httpd.conf
   • Ensure your new .conf file has chmod a+r access

Note: If the apache error log has lots of Symbolic link not allowed or link target not accessible type messages, then you probably need to add +FollowSymLinks to the Options for the /var/www/foswiki/dev/core/pub directory in your apache configuration.

This is the most basic Foswiki install possible. Normally you will want to checkout and pseudo-install the default skins and plugins (PatternSkin, SpreadSheetPlugin, TablePlugin, CommentPlugin etc.

cd /var/www/foswiki
for module in `grep '!include' core/lib/MANIFEST | sed -e 's/^.*\///g'`
do
    svn co http://svn.foswiki.org/trunk/$module
done

(This is bash shell script. The script-challenged can get the list of modules to check out by inspecting the !include lines in core/lib/MANIFEST)

OR You can also use the checkout_extensions script to checkout these extensions in a easier way:

./tools/checkout_extensions --default

Once you have checked these modules out you can install them all in one go using the special default parameter to pseudo-install.pl

cd core
perl pseudo-install.pl default

Now and then you will want to keep your installation in sync with the subversion server. The pseudo-install script is not intelligent enough to cope with changes to MANIFESTs, so this is the idiot proof way to update. It first removes all the links (or copied files), then does the svn update. And finally does a new pseudo-install.

cd /var/www/foswiki/core
./pseudo-install.pl -uninstall all
svn update ..
./pseudo-install.pl default
chown -R apache:apache ..

Normally just doing the svn update will be enough, unless someone has removed files (and even then you can usually ignore it).

If you are a developer you can also install the kit required to run unit tests, by passing the developer parameter to pseudo-install.pl

cd /var/www/foswiki/core
./pseudo-install.pl developer

This will also install the BuildContrib and a number of other components useful to developers. There is presently no documented means to check out just the larger set of extensions needed to develop, so developers will likely have to take the maximalist approach shown below.

Tips, hints, and useful commands

Enable ASSERTS for more extensive testing

The unit tests run with ASSERTS enabled, but the live web environment does not. In order to enable ASSERTS, edit bin/LocalLib.cfg and un-comment the following line

$ENV{FOSWIKI_ASSERTS} = 1;

This enables additional validation tests that will impact performance, but will catch some issues that might be missed during normal web usage.

Use the CPAN modules shipped with Foswiki

Foswiki ships with a number of CPAN modules that are used only when the underlying platform is missing the modules. In order to test using the modules that are shipped with Foswiki, CPAN lib prepending should be enabled in bin/LocalLib.cfgby uncommenting the following line:

$CPANBASE = '';                     # Uncommented: Default path prepended

. See the comments in bin/LocalLib.cfg.txt for more details.

It is probably best to test using platform modules as well as the shipped modules.

Installing everything

The example commands above describe how to install a minimalist Foswiki, which requires you to check out and install each additional extension by hand. You can also take a maximalist approach and check out the entire trunk. This may be appropriate if you are going to be working on a lot of different extensions, or simply want to have everything at hand and don't care how long (or how much space) it takes. You can see the scripts that maintain an auto-updating Foswiki site in core/tools/develop.

Here's how:

cd /var/www
mkdir foswiki
cd foswiki
# checkout *everything*
svn co http://svn.foswiki.org/trunk .
cd core
#create default LocalSite.cfg and install the default extensions
./pseudo-install.pl -A default
# or use 'developer' in place of 'default' to install the default extensions and the development extensions
# or use 'all' in place of 'default' to install all plugins and extensions (not recommended!)
cd ..
chown -R apache:apache .
# Now configure Apache to use the Foswiki in /var/www/foswiki/core

Now you can install additional extensions using perl pseudo-install.pl extension_name and uninstall with perl pseudo-install.pl -uninstall extension_name

Delete all broken soft links in a subversion-based install

This is handy if you have changed a lot of MANIFESTS or have manually soft-linked any files, and want to remove any broken soft links. Assume your trunk checkout is at /var/www/foswiki

find -L /var/www/foswiki/core -type l -exec rm \{\} \;

Create a new extension

You can quickly and easily create a new extension using the create_new_extension.pl script that is installed in core when you pseudo-install the BuildContrib.

Set up the unit test framework

If you are developing new code you will want to set up the development and test environment. For this you will need to pseudo-install BuildContrib, UnitTestContrib and TestFixturePlugin.

./pseudo-install.pl developer

which is equivalent to the older pseudo-install.pl BuildContrib UnitTestContrib TestFixturePlugin

Then:

cd test/unit
export FOSWIKI_LIBS=/var/www/foswiki/core/lib
perl ../bin/TestRunner.pl FoswikiSuite

(or equivalent on Windows)

For full details, see Development.UnitTests#SettingUpATestEnvironment

Pseudo-installing extensions from trunk to work with a Release branch based pseudo-install

To ensure we have a stable code base for releases the Foswiki project maintains a parallel release branch. For Foswiki 1.0.X this branch is found in http://svn.foswiki.org/branches/Release01x00. For release 1.1 it's Release01x01, and so on.

The release branch only contains

• The core code
• The default set of distributed extensions
• The extensions needed for development like BuildContrib and UnitTestContrib

All other extensions are maintained only in trunk.

Developers of both core and extensions will need to run with extensions from trunk in a pseudo-installed ReleaseXXxXX checkout. This is easy to do by following these steps.

• First make an SVN checkout of the http://svn.foswiki.org/branches/ReleaseXXxXX (e.g. Release01x00)
• Then do a normal pseudo-install default and get the apache config and configure run so all works as normal with the default set of plugins.
• Then you either
  • make an SVN checkout of trunk incl all the extensions. This takes more time and space but probably what most developers will choose to do
  • or make an SVN checkout from trunk of the extensions you are interested in developing or testing or just trying out.
• Then you set an environment variable called FOSWIKI_EXTENSIONS and let is point to the directory from which you can see the directory of the extension from trunk. Let us say you have a complete trunk svn checkout in /var/www/foswiki. Then you set the variable with export FOSWIKI_EXTENSIONS=/var/www/foswiki
• You can now run pseudo-install from the release branch and it will install the extension from the trunk directory tree instead. Example perl pseudo-install.pl ChartPlugin will link the ChartPlugin from trunk on to your release checkout.

Let us show an example of a script that does it all for you.

We assume you have trunk checked out in /var/www/foswiki

And we assume you have Release01x00 checked out in /var/www/Release01x00

And we assume you have some webs that you share between trunk and release branch so you can test the same topics in both environments. We have put these webs in /var/www/testwebs

The following script will remove all old links, pseudo-install the default and developer extensions from release branch and additional 5 extensions from the trunk. It will also svn update the release branch but not the trunk. We assume you svn update the trunk independently of the release branch. Additionally we symlink two common test webs: Myweb and Newrenamedweb

#!/bin/sh
cd /var/www/Release01x00
rm -f `find . -type l -print`
svn update
cd core
export FOSWIKI_EXTENSIONS=.
./pseudo-install.pl developer
export FOSWIKI_EXTENSIONS=/var/www/foswiki
cd data
ln -s /var/www/testwebs/data/Myweb Myweb
ln -s /var/www/testwebs/data/Newrenamedweb Newrenamedweb
cd ../pub
ln -s /var/www/testwebs/pub/Myweb Myweb
ln -s /var/www/testwebs/pub/Newrenamedweb Newrenamedweb
cd ../../..
chown -R apache:apache Release01x00

With this setup you can develop plugins in trunk and test them in the current release branch.