PSGIEngineContrib

Introduction

A word of warning: This engine runs only with SVN trunk revision >29000, and it is still very experimental. At its present stage it might come in handy for developers who want to avoid permissions trouble with "normal" web servers when running from a SVN checkout, or who want to debug a script in interaction with a browser. Nevertheless, feedback is appreciated at TWiki:Plugins/PSGIEngineContribDev or as bug reports.

This extension allows to run the TWiki codebase from a PSGI conforming web server. Such servers range from single-threaded CLI programs like CPAN:plackup through Perl-based web servers like CPAN:Starman to general purpose web servers with Perl adapters like Apache HTTPD with mod_perl or FastCGI.

With this contrib, the TWikiScripts in the bin directory are no longer needed for browser operations.

Usage

The basic idea is like this:

• You install the PSGI Engine Contrib. It comes with two scripts: One for running TWiki completely under PSGI, and one for running just the Perl part under PSGI and leave the static stuff (pub directory) to an underlying web server.
• You add one of the scripts to your web server. This is the same procedure as for every PSGI application, but we intend to provide examples.

Examples

Developer setup: Run from a SVN checkout

1. Install Plack. Your friendly Linux distribution should offer it (libplack-perl under Debian or Ubuntu, perl-Plack for RedHat). We need at least version 1.0030 (Nov 2013), so unless you are running a pretty hot Linux version, you'll need to install from CPAN.
2. Now cd to the core directory of your SVN checkout area.
3. Say perl pseudo-install.pl PSGIEngineContrib to your computer. It should print a couple of lines, ending with PSGIEngineContrib installed.
4. Examine your lib/LocalSite.cfg: If you want to keep your settings, you might want to set the port:
   • $TWiki::cfg{DefaultUrlHost} = 'http://localhost:5000';
   • $TWiki::cfg{PermittedRedirectHostUrls} = 'http://localhost:5000';
5. Say plackup -Ilib psgi/twiki.psgi to your computer. It should reply with HTTP::Server::PSGI: Accepting connections at http://0:5000/.
   • IF you don't have a LocalSite.cfg, the engine will create one for you, guessing some values. You can improve the results by starting plackup with plackup -I/absolute/path/to/lib psgi/twiki.psgi.
6. Point the browser of your choice http://localhost:5000/ plus your setting of $TWiki::cfg{ScriptUrlPath} - and enjoy.

You might need to fiddle with permissions if you ran your SVN installation with an Apache web server before: Apache sets owner and group to some who probably isn't you.

Debugging while running from a browser

• From the core directory, enter the following command:
  perl -Sd -Ilib plackup --access-log /tmp/twiki.log psgi/twiki.psgi
  This runs the web server under the perl debugger, getting the access log out of your way. Very handy if unit tests or command line scripts fail to capture a critical situation. Note that at the debugger's command prompt, TWiki is not yet compiled. You can just load "your" modules yourself, and set breakpoints before continuing. Example:
  • DB<1> use TWiki::UI::Upload
  • DB<2> b TWiki::UI::Upload::upload
  • DB<3> c
  • HTTP::Server::PSGI: Accepting connections at http://0:5000/
  • Now you can use your browser to navigate as you like. As soon as you hit "upload", you'll get control in the debugger window.

Running with starman

CPAN:starman is a high-performance pure-perl webserver. Running PSGI-enabled TWiki is easy, but you need one workaround:

• perl -Ilib -MFindBin -S starman psgi/twiki.psgi

Settings

This contrib is an engine for TWiki as a whole. The settings are pulled from the TWiki configuration file, LocalSite.cfg.

In contrast to the other engines, the PSGI engine does not perform any guesswork to find the TWiki libraries: The files setlib.cfg and LocalLib.cfg are ignored. You are kindly requested to provide the required directories to your web server.

Installation Instructions

You do not need to install anything on the browser to use this contrib package. These instructions are for the administrator who installs the package on the server where TWiki is running.

Security Considerations

Running PSGI TWiki is convenient, because you don't have to configure a web server. On the downside you can't use any features of the web server you've just abandoned:

• ApacheLogin doesn't make sense without Apache. This may hurt if you are using the "advanced" authentication methods of Apache, e.g. against LDAP directories.
• Fending off bad clients according to their User-Agent header is recommended for TWikis in the internet. Apache can do this for you if you use the TWiki:Codev.ApacheConfigGenerator.
• .htaccess files have no special meaning and no builtin protection with other web servers.

You can, however, use a PSGI-enabled TWiki "behind" an Apache web server, but the howto still needs to be written.

Manifest

Contrib Info

Contrib Author(s):
Copyright:	© TWiki:Main.HaraldJoerg
License:	GPL (Gnu General Public License)
Contrib Version:	30387 (2017-09-06)
Change History:
2017-09-06:	Bugs:Item7751 - improve PSGI bootstrapping
2015-04-03:	First SVN version
2015-04-01:	Publication of the idea
Dependencies:	Name Version Description CGI::Emulate::PSGI =>0 Required for configure. Plack >=1.003 Base class for the engine.
Contrib Home:	http://twiki.org/cgi-bin/view/Plugins/PSGIEngineContrib
Feedback:	http://twiki.org/cgi-bin/view/Plugins/PSGIEngineContribDev
Appraisal:	http://twiki.org/cgi-bin/view/Plugins/PSGIEngineContribAppraisal

Related Topics: TWikiContribs, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences