START HERE! This is the Foswiki project "Distribution". It is a monolith repository with the core + default extensions.
Perl JavaScript HTML CSS Shell XSLT Other
Permalink
Failed to load latest commit information.
AutoViewTemplatePlugin Item13883: Update extension versions and releas notes Apr 9, 2016
BehaviourContrib Item11808: perltidy them all, so people are not accidentally impacted… May 4, 2012
BuildContrib Item14022: upload site is https://, not http:// Apr 17, 2016
CommentPlugin Merge branch 'master' into Item14033 May 27, 2016
CompareRevisionsAddOn Item13504: update attachment data Jul 21, 2015
ConfigurePlugin Item13206: Upgrade to latest jquery-ui Nov 28, 2016
DEL_ImageGalleryPlugin Item11267: Delete unneeded ImageGalleryPlugin Aug 21, 2014
EditRowPlugin Item14258: Fix crash with empty column format Dec 21, 2016
EditTablePlugin Item14236: Included compressed / gzipped css & js Nov 28, 2016
EmptyJQueryPlugin Item12855: Core extensions should require JQueryPlugin 6.00 Dec 18, 2014
EmptyPlugin Item14022: Foswiki.org changed to https: Mar 10, 2016
FamFamFamContrib Item13883: Fix release notes, versions and copyrights Feb 3, 2016
FastCGIEngineContrib Item14221: Merge branch 'Release02x01' Dec 5, 2016
HistoryPlugin Item13504: Update plugin versions for Foswiki 2.0.2 Sep 8, 2015
HomePagePlugin Item13478: after sleeping on it, concluded that it is *not* appropria… Jun 30, 2015
InterwikiPlugin Item13883: Update extension versions and releas notes Apr 9, 2016
JEditableContrib Item13504: update attachment data Jul 21, 2015
JQueryPlugin Item13883: Preparing docs for release. Dec 13, 2016
JSCalendarContrib Item13504: update attachment data Jul 21, 2015
JsonRpcContrib Merge remote-tracking branch 'origin/Release02x01' Nov 28, 2016
MailerContrib Item14216: Support utf-8 webs/topics in mailnotify Nov 16, 2016
ModPerlEngineContrib Merge remote-tracking branch 'origin/Release02x01' Nov 28, 2016
NatEditPlugin Item14265: fixed unblocked ui Jan 16, 2017
PatchFoswikiContrib Item13759: Release PatchFoswikiContrib Nov 17, 2015
PatternSkin Item13831: merge master Jan 16, 2017
PlainFileStoreContrib Item14008: Warn if AutoAttach used with PlainFile Mar 10, 2016
PreferencesPlugin Item9693: Item12864: Item13423: Bump version, update copyrights, Jun 15, 2015
PubLinkFixupPlugin Item13696: Add empty dependencies file Oct 1, 2015
QueryAcceleratorPlugin Item11808: add TIDY flag file to various extensions May 8, 2012
RCSStoreContrib Item14066: Bump version, update release notes. Nov 26, 2016
RenderFormPlugin Item13651: Prepare RenderFormPlugin for release to Extensions web (sigh) Aug 31, 2015
RenderListPlugin Item13883: Update extension versions and releas notes Apr 9, 2016
SlideShowPlugin Item14170: typo Sep 6, 2016
SmiliesPlugin Item13725: Remove height for better compatibility. Sep 17, 2015
SpreadSheetPlugin Item13883: Update extension versions and releas notes Apr 9, 2016
SubscribePlugin Item14033: Fix unit tests for new Request::Rest Apr 7, 2016
TWikiCompatibilityPlugin Item13504: update attachment data Jul 21, 2015
TablePlugin Item13883: Fix release notes, versions and copyrights Feb 3, 2016
TestFixturePlugin Item13423: Fix test fixtures May 22, 2015
TinyMCEPlugin Item13504: update attachment data Jul 21, 2015
TipsContrib Item13796: Rename setting, and fix TipsContrib to not need it. Nov 9, 2015
TopicUserMappingContrib Merge branch 'Release02x01' Dec 28, 2016
TwistyPlugin Item13883: Bump TwistyPlugin version due to doc updates Apr 25, 2016
UnitTestContrib Item14260: Broke the unit tests Dec 29, 2016
UpdatesPlugin Item13524: Don't report "0 updates" by default Jul 24, 2015
WysiwygPlugin Item14253: Don't insert extra white space before [[links]] Dec 19, 2016
ZonePlugin Item12381: added some more LABELs Jan 19, 2015
core Item14266: Merge branch 'Release02x01' Jan 16, 2017
README.md Item9693: Update README documentation. Feb 11, 2015

README.md

Foswiki Installation based on git

These instructions are more geared for developers, and admins who want to use the "bleeding edge" of Foswiki. We recommend using our packaged distributions. See our Download page

You can run a Foswiki instance from this clone simply by pointing Apache at it. See the ApacheConfigGenerator

Note:Configure has been completely rewritten on the master branch. Foswiki is now able to "bootstrap" itself without a configuration. After pseudo-installing the default extensions, Point your browser at your default URL for the new site as configured in ApacheConfigGenerator. (ex. http://yoursite.com, http://yoursite.com/foswiki, or http://yoursite.com/foswiki/bin/view depending upon the apache configuration)

To "install" extensions in a checkout area, you should 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. Use:

  • pseudo-install.pl default to install the default contribs and plugins (e.g. Extensions.TwistyContrib which is relied on by Extensions.PatternSkin)
  • pseudo-install.pl developer to install the additional developer extensions. The developer option also installs all the default extensions. See the header comment of the pseudo-install.pl script (core directory 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 Extensions.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 "master" branch. 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 master branch from git and doing the pseudo-install. We assume that you want to run your git 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. git clone https://github.com/foswiki/distro.git foswiki
  3. This will check out core and all the default and developer extensions, however they are not installed yet.
  4. cd core && ./pseudo-install.pl default
  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

git clone https://github.com/foswiki/distro.git foswiki
Cloning into 'foswiki'...
remote: Counting objects: 134190, done.
remote: Compressing objects: 100% (37847/37847), done.
remote: Total 134190 (delta 87343), reused 132136 (delta 85289)
Receiving objects: 100% (134190/134190), 66.86 MiB | 1.63 MiB/s, done.
Resolving deltas: 100% (87343/87343), done.
Checking connectivity... done.

# By default this will leave you in the "master" branch, where leading edge development happens
# If you want to use the current release branch, change to the Release01x01 branch
# Skip this step if you want to remain on the experimental master branch.

cd foswiki
git checkout Release01x01
Branch Release01x01 set up to track remote branch Release01x01 from origin.
Switched to a new branch 'Release01x01'

# The extensions have all been checked out one level up from the "core" directory
# the next step is to link / copy them into the installation.  This is done with pseudo-install.

cd core
perl -T pseudo-install.pl default
Installing extensions: PatchFoswikiContrib, AutoViewTemplatePlugin, CompareRevisionsAddOn, CommentPlugin, EditTablePlugin, EmptyPlugin, FamFamFamContrib, HistoryPlugin, InterwikiPlugin, JSCalendarContrib, JQueryPlugin, MailerContrib, TablePlugin, TwistyPlugin, PatternSkin, PreferencesPlugin, RenderListPlugin, SlideShowPlugin, SmiliesPlugin, SpreadSheetPlugin, TipsContrib, WysiwygPlugin, TinyMCEPlugin, TopicUserMappingContrib, TWikiCompatibilityPlugin, core
Processing AutoViewTemplatePlugin
Linked data/System/AutoViewTemplatePlugin.txt
mkdir /var/www/fw/core/lib/Foswiki/Plugins
...
#...
#... A large amount of output is generated.
#... Errors about dependencies on foswiki extensions can generally be ignored.
#... The extensions are not installed in the order that would resolve all dependencies.
#...


# 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 foswiki

# Now configure Apache to use the Foswiki in /var/www/foswiki/core
  1. Use the ApacheConfigGenerator
  2. Clipboard copy and save this to core/../foswiki.httpd.conf
  3. Include this foswiki.httpd.conf from your apache httpd.conf OR
    • On many linux distributions, you can save this file into /etc/apache2/sites_enabled or /etc/apache2/vhosts.d, or /etc/apache2/Include ... Check your local distribution's instructions.
    • 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.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.

At this point, if you point your browser to your foswiki url, it should "just work", but will display a bootstrap warning at the top of the configuration. To fully configure foswiki, visit the bin/configure URL, resolve any warnings and errors, and save the configuration. Caution: Once you save the configuration, you will be unable to use configure again unless you have registered and granted yourself "Adimin" authority. You can control who can use configure by setting Security and Authentication -> Access Control {ConfigureFilter}. When that option is set, it replaces the check for Admin authority and can allow any user including the guest user to use configure. So use caution!.

Now and then you will want to keep your installation in sync with the latest version in the foswiki git repository. 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), git fetch. And finally does a new pseudo-install.

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

Normally just doing the git pull 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 BuildContrib and a number of other components useful to developers.

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 (If it's not there, create it by copying bin/LocalLib.cfg.txt) 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 1.2 no longer ships with CPAN modules. It is now recommended to use your system's package manager, or cpan to install dependencies. see http://foswiki.org/System/SystemRequirements. In the event that you are unable to install the CPAN dependencies, pseudo-install the CpanContrib to get the 1.x style Foswiki specific dependencies. (CpanContrib is not yet released). In order to test these modules, 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 non-default extensions

The example commands above describe how to install a minimalist Foswiki. The pseudo-install script knows some additional tricks to use with non-default extensions. If you pseudo-install an extension that is not currently checked out, pseudo-install will automatically clone the extension from github using https://github.com/foswiki/ExtensionName.git

Note: Although we use release managed branches (master, Release01x00, Release01x01) in the Foswiki core distribution ("distro"), non-default extensions typically only have a "master" branch.

Here's how to install a non-default extension, using AntiWikiSpamPlugin as an example:

cd foswiki/core
 ./pseudo-install.pl AntiWikiSpamPlugin
Useless use of \E at ./pseudo-install.pl line 1553.
Useless use of \E at ./pseudo-install.pl line 1553.
Installing extensions: AntiWikiSpamPlugin
Processing AntiWikiSpamPlugin
Trying clone from git://github.com/foswiki/AntiWikiSpamPlugin.git...
Cloning into 'AntiWikiSpamPlugin'...
remote: Counting objects: 489, done.
remote: Total 489 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (489/489), 86.42 KiB | 0 bytes/s, done.
Resolving deltas: 100% (185/185), done.
Checking connectivity... done.
Cloned AntiWikiSpamPlugin OK
Linked data/Main/AntiWikiSpamBypassGroup.txt
Linked data/System/AntiWikiSpamLocalList.txt
Linked data/System/AntiWikiSpamRegistrationWhiteList.txt
Linked data/System/AntiWikiSpamRegistrationBlackList.txt
Linked data/Sandbox/AntiWikiSpamTestTopic.txt
Linked data/System/AntiWikiSpamPlugin.txt
Linked lib/Foswiki/Plugins/AntiWikiSpamPlugin.pm
Linked lib/Foswiki/Plugins/AntiWikiSpamPlugin
Linked test/unit/AntiWikiSpamPlugin
Linked /var/www/fw/core/tools/develop/githooks/commit-msg as /var/www/fw/AntiWikiSpamPlugin/.git/hooks/commit-msg
Linked /var/www/fw/core/tools/develop/githooks/pre-commit as /var/www/fw/AntiWikiSpamPlugin/.git/hooks/pre-commit
Linked /var/www/fw/core/tools/develop/githooks/commit-msg as /var/www/fw/AntiWikiSpamPlugin/../.git/hooks/commit-msg
Linked /var/www/fw/core/tools/develop/githooks/pre-commit as /var/www/fw/AntiWikiSpamPlugin/../.git/hooks/pre-commit
 AntiWikiSpamPlugin installed
Linked /var/www/fw/core/tools/develop/githooks/commit-msg as /var/www/fw/core/.git/hooks/commit-msg
Linked /var/www/fw/core/tools/develop/githooks/pre-commit as /var/www/fw/core/.git/hooks/pre-commit
Linked /var/www/fw/core/tools/develop/githooks/commit-msg as /var/www/fw/core/../.git/hooks/commit-msg
Linked /var/www/fw/core/tools/develop/githooks/pre-commit as /var/www/fw/core/../.git/hooks/pre-commit

Delete all broken soft links

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. You'll also need to do this when switching between Release01x01 and master branches.

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 Extensions.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

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 http://foswiki.org/Development/UnitTests#SettingUpATestEnvironment