Update

The old content bellow is works for 1.1.9, but the changes in the configure in the 1.2 allows reduce the script to few lines. Here is the minimal working app.psgi for the Foswiki 1.2.

use Plack::Builder;
use CGI::Emulate::PSGI;

my($root);
BEGIN {
   $root = "./foswiki/core";  # the path to the foswiki root directory (the example is for an standard github checkout)
   die "Wrong $root directory! Can't found $root/bin/setlib.cfg" unless -f "$root/bin/setlib.cfg";
   $ENV{FOSWIKI_SCRIPTS} = "$root/bin";
   require "$root/bin/setlib.cfg";
   $Foswiki::cfg{Engine} = 'Foswiki::Engine::CGI';
}

my $foswiki = CGI::Emulate::PSGI->handler(sub {
   CGI::initialize_globals();
   use Foswiki();
   use Foswiki::UI ();
   $Foswiki::engine->run();
});

builder {
   enable "Static", path => qr{/pub/}, root => "$root";
        enable 'Rewrite', rules => sub { s|^/|/bin/view/| unless m|^/bin/| }; #allows short url's
   mount "/bin" => $foswiki;
   mount "/" => sub { return [ 302, [ 'Location' => "/Main/WebHome" ], [ '' ] ]; };
};

So in short:

• add the above into app.psgi
• install from CPAN Plack, CGI::Emulate::PSGI
• clone foswiki distro from the github
• run the pseudo installer
• run: plackup
• done = working foswiki

Here is already an great tools/lighttpd.pl script for quick foswiki hacking, but the above is for the PSGI evangelists or for users who want do some brutal runtime hacking... e.g.

use Plack::Builder;
use CGI::Emulate::PSGI;
use Data::Dumper;
#you can preload all CPAN modules what are needed by Foswiki here...

my($root);
BEGIN {
    $root = "./foswiki/core";
    die "Wrong $root directory! Can't found $root/bin/setlib.cfg" unless -f "$root/bin/setlib.cfg";
    $ENV{FOSWIKI_SCRIPTS} = "$root/bin";
    require "$root/bin/setlib.cfg";
    $Foswiki::cfg{Engine} = 'Foswiki::Engine::CGI';
}

my $foswiki = CGI::Emulate::PSGI->handler(sub {
    CGI::initialize_globals();
    use Foswiki();
    use Foswiki::UI ();
    $Foswiki::engine->run();
});

builder {
    #add some debugging
    #enable "StackTrace";
    enable "Debug";
    enable "Debug::Ajax"; #foswiki and this is bugged together in some cases - but sometimes helps...

    enable "Static", path => qr{/pub/}, root => "$root";
    enable 'Rewrite', rules => sub { s|^/|/bin/view/| unless m|^/bin/| }; #allows short url's

    # you can do any brutal hacking here - inject into requests, hack the results and so on...
    # add any number of "inline" middlewares...
    #enable sub { my $app = shift; return sub { my $env = shift;
    #   say "  ENV: ", Dumper $env; #your code here...
    #$app->($env); }; };

    # also keep in mind - the $foswiki is alrealy initialized, e.g. the LocalSite.cfg is already loaded
    # so you can hack the $Foswiki::cfg here...

    # e.g. set an temporary easy password. (the password in LocalSite.cfg remains intact...)
    #$Foswiki::cfg{Password} = '$apr1$V4zo62kS$P3ys8zpSMckfeZJUZ64E7.';

    # site configured as "http://localhost" and you want quick-test something? Set the DefaultUrlHost...
    #$Foswiki::cfg{DefaultUrlHost} = 'http://0:5000';

    #etc - limitless brutality... :)

    mount "/bin" => $foswiki;
    mount "/" => sub { return [ 302, [ 'Location' => "/Main/WebHome" ], [ '' ] ]; };
};

One problem is - when you run the configure after the save you need restart plackup (CTRL-C and plackup). It somewhat freezes. If you run the above app.psgi under the Starman its recovering (after a short time) but i'm not sure fully - not tested. Simply, remember - this is for development, and you need restart the plackup after the configure.

Old Content

It is possible to run foswiki in PSGI environment with CGI emulation layer. See CGI-Emulate-PSGI.

Warning

This guide and the attached script is only for development/testing purpose. The script is NOT TESTED for any security issues. Don't use it in production environment. You have been warned. The script developed under Mac OS X + macports + CPAN, other platforms are not tested - but probably will work on UNIX like systems.

Prerequisites

You must know how to install CPAN modules into your system. Admin rights are not required if you install modules locally, however this is not tested.

1. Install the following cpan modules
   • cpanm Cwd
   • cpanm Plack
   • cpanm CGI::Emulate::PSGI
   • cpanm Plack::App::WrapCGI
   • cpanm Plack::Middleware::IPAddressFilter
   • maybe some others...

Assumptions

• The whole installation is in one directory-tree. (For example: ~/psgi)
• Foswiki distribution is unpacked into the above dir. (e.g. ~/psgi/Foswiki-1.1.3-RC1)
• bin, lib, pub are inside the distro-dir - this is the default (e.g. ~/psgi/Foswiki-1.1.3-RC1/bin ~/psgi/Foswiki-1.1.3-RC1/lib)

Downloads

1. Download Foswiki 1.1.3-RC1 - only tested with this one
2. Download the foswiki.psgi script attached to this topic
3. Download the start_foswiki.command shell-script (.command is for OS X users, if you're on Linux rename it to start_foswiki.sh or so)

Installation

1. mkdir some directory, for example: ~/psgi
2. unzip the foswiki distribution in this directory, so you get ~/psgi/Foswiki-1.1.3-RC1 - for the latest beta. Do not change owership of files.
3. (optional) If your perl is not in /usr/bin/perl use the following to change shebang lines
   cd your_psgi_dir/FOSWIKI_DIR/tools
/path/to/your/perl -I ../lib rewriteshebang.pl (check the perl path and answer "y" to change #!/usr/bin/perl lines)
4. move the downloaded foswiki.psgi into ~/pgsi/foswiki.psgi
5. editthe foswiki.psgi. For now, all configuration is inside the script.
   • edit password for the /bin/configure access - cleartext password - remember, this is NOT for production.
   • edit hosts, what are allowed to access /bin/configure - default is only localhost. (must be IP numbers)
   • change the fwdir value, to your foswiki directory (default Foswiki-1.1.3-RC1)
   • change the env_path if need. (this will go into $ENV{PATH} and must not contain any writable directory, otherwise /bin/configure will complain. (-T tainted environment)

Example:

 ###################################
    # Config
    $cfg = {
        config_user => "admin",             #auth-name for the config script (for now doesn't use Foswiki::cfg)
        config_pass => "Z0a9q8..#",         #clear-text password - the simpliest way ;( - need better handling here...
        config_hosts => ['+ 127.0.0.1'],    #hosts, allowed access the configure script
        fwdir => "Foswiki-1.1.3-RC1",       #name of the foswiki subdirectory. Must be in the dir, where is this script.

                                            #$ENV{PATH} - MUST BE without writable dirs, or configure will complain
        env_path => "/opt/local/bin:/opt/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin",
    };
    ###################################

Configure and run

1. start plackup server (OS X - double click on start_foswiki.command, others run "start_foswiki.sh" from a terminal). This will start the plackup web-server on the port 5080, in your terminal window.
2. point the broser to http://localhost:5080/bin/configure
3. save the config, and enter internal foswiki's config-password. Now you got access to the whole config.
4. configure as usually...
5. save config
6. RESTART THE SERVER (Ctrl-C the current one and start again)

Party time

Finished - you can start testing your new and lightning fast foswiki under PSGI (http://localhost:5080/bin/view/Main/WebHome)

Final notes

• The /bin/configure is run in forked CGI environment, so like in classic CGI installation. (read: still slow)
• The standard parts of Foswiki are run in persistent environment under pure perl server.
• (Someone who know english should re-edit this topic)

• foswiki.psgi: the psgi script
• start_foswiki.command: startup script

---

Most excellent. Thank you for writing this up!

-- PaulHarvey - 17 Apr 2011