5. Karrigell with Apache, lighttpd and Xitami

Although Karrigell can work stand-alone with the integrated web server, you may want to use it with an external server. Apache is the most widespread server in the world, it has excellent performance and stability, it can work on secure mode (SSL), offers log services, etc.

There are several ways to run Karrigell with Apache :

mode description pros cons

Proxy mode The integrated web server runs in the background, the Apache server sends all requests to it and returns the response to the client

best performance
session object managed in memory (more flexible)

requires permission to run a long-running process on the server
not fit for long-running requests (the integrated web server will block until the request is completed)

CGI mode Requests are processed by a CGI script

compatible with all web hosting providers
doesn't block with long-running requests (each request runs in a different process)

the CGI overhead reduces performance
session management less flexible (session data must be stored on disk)

Graham Dumpleton wrote instructions for running Karrigell with WSGI

5.1 Apache on proxy mode

5.1.1 Introduction

To use Karrigell in Apache you'll need to download and install the following:

Apache - Web server.
Python - Python.
Karrigell - This!

I recommend you install the latest, stable version of each of the above. Apache will be used as a proxy between the client and the built-in server, so you have to configure Apache so that it sends the requests to the built-in server. Suppose you start Apache on port 80 and the built-in server on port 8081

I copy most of this section from Remi Delon's CherryPy documentation : http://www.cherrypy.org/wiki/BehindApache

For Apache, all you need to do now is add a few lines to Apache's config file httpd.conf (should be under the menu item "configure Apache server" on Windows)

In the Dynamic Shared Object (DSO) section, uncomment the lines

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule rewrite_module modules/mod_rewrite.so

Somewhere else in the main server configuration section, add the following lines to enable the proxy mode :

ProxyRequests On
<Proxy *>
    Order allow,deny
    Deny from none
    Allow from all
</Proxy>

To ask Apache to send the requests to the built-in server, use mod_rewrite. This module parses the original url and changes it according to regular expressions. Here the lines to add are :

RewriteEngine On
RewriteCond  %{SCRIPT_FILENAME} !autostart\.cgi$
RewriteRule ^(.*) http://localhost:8081$1 [P]
ErrorDocument 502 /cgi-bin/autostart.cgi

The main functionality is provided by the RewriteRule : it tells Apache to rewrite all the urls to an absolute url corresponding to the built-in server running on port 8081 and use the proxy mode to pass the request

If the built-in server is not running, an HTTP error 502 is returned ; the last line tells Apache to call the script autostart.cgi in this case. The second line prevents Apache to use the RewriteRule for this specific script (otherwise it would enter an infinite loop)

autoscript.cgi is a short script, looking like this on Linux/Unix :

#!/usr/local/bin/python
print "Content-type: text/html\r\n"
print """<html><head><META HTTP-EQUIV="Refresh" CONTENT="10; 
      URL=/"></head><body>Restarting site ...<a href="/">click 
      here<a></body></html>"""
import os
import sys
os.setpgid(os.getpid(), 0)
os.system(sys.executable + \
   ' /home/quentel/karrigell/Karrigell-2.2/Karrigell.py -P 8081 -S ' +\
   '/home/quentel/karrigell/Karrigell-2.2/Karrigell.ini &')

All you have to adapt is the location of python on the first line, and the path to Karrigell.py and Karrigell.ini on the last one

Start the built-in web server on port 8081 and start Apache. This should be enough to get it going. Depending on what ServerName is set to (use 'localhost' for testing), enter the URL of your server into the URL bar of a web browser and Karrigell/Apache should serve web pages like normal Karrigell.

For security reasons, on Linux Karrigell should be started on a port above 1024 and not as root

5.1.2 Virtual Hosts

Virtual hosts can be used with Apache to serve different hosts on the same machine with the same server. Since version 2.2, Karrigell has had support for virtual hosts, so that you can serve all the virtual hosts with the same instance of the built-in server

If you have configured [VirtualHost karrigell:8081] in the Karrigell configuration file (see the page on web server options) with the name karrigell and the port 8081 (on which the built-in web server runs), you add this VirtualHost section in the Apache configuration file :

NameVirtualHost 127.0.0.1:80
<VirtualHost 127.0.0.1:80>
        ServerName karrigell
        # for use with Karrigell
        RewriteEngine On
        RewriteCond  %{SCRIPT_FILENAME} !autostart\.cgi$
        RewriteRule ^(.*) http://karrigell:8081$1 [P]
        ErrorDocument 502 /cgi-bin/autostart.cgi
</VirtualHost>

Of course you change the address and port in <Virtual Host> to the appropriate values

5.2 Apache with mod_cgi

New in version 2.3.5

In case you can't use the built-in server you can use another approach to run Karrigell behind an Apache server, simply using the mod_rewrite and mod_cgi modules

All the urls requesting a page in the Karrigell directory are "rewritten" by mod_rewrite to be processed by a single cgi script, start.cgi, located in folder webapps/cgi-bin

5.2.1 Write and execute modes

You must install the Karrigell package in a folder accessible to the Apache server, and set following permissions if the server is Unix/Linux :

"write" mode on folders data and conf
"execute" on script start.cgi in folder webapps/cgi-bin

5.2.2 httpd.conf

Replace "C:/cygwin/home/Karrigell" by the path to the directory where the Karrigell package was extracted

1. in the DSO section, make sure these lines are uncommented

LoadModule cgi_module modules/mod_cgi.so
LoadModule rewrite_module modules/mod_rewrite.so

2. Replace DocumentRoot by the path to your webapps directory

DocumentRoot "C:/cygwin/home/karrigell/webapps"

3. Aliases
Rewrite all the aliases defined in Karrigell.ini :

Alias /admin "C:/cygwin/home/Karrigell/admin"

4. Uncomment the line

AddHandler cgi-script .cgi

5. Options for the root directory

Replace the section <Directory /> (...) </Directory> by:

<Directory />
    AllowOverride None
    Options -Indexes FollowSymLinks ExecCGI
    Order allow,deny
    Allow from all
    # manage urls matching folders
    ErrorDocument 403 /cgi-bin/start.cgi
    # rewrite urls to make Karrigell process the scripts 
    # with extensions py,pih,hip and ks
    RewriteEngine On
    RewriteRule ^(.*)\.(py|pih|hip|ks)$ /cgi-bin/start.cgi
    # ks scripts with function name
    RewriteRule ^(.*)\.ks/.* /cgi-bin/start.cgi
</Directory>

6. Add configuration for the cgi-bin directory

<Directory /cgi-bin>
    AllowOverride None
    Options ExecCGI
    Order allow,deny
    Allow from all
</Directory>

7. If necessary, modify the first line in start.cgi to specify the path to the Python interpreter on the server : for instance

#!/usr/local/bin/python

5.2.3 Karrigell configuration file

set [Server] persistentSession to 1 and debug to 0

Warning On cgi mode, session data cannot be stored in memory. They are stored in a file on disk, which causes some limitations :

only built-in types can be set as attributes to the session object
performance is lower because of disk access time

5.3 Apache on shared web hosting

If you want to run Karrigell on a shared web hosting provider, you will probably not be able to run the built-in server, so you will use the cgi mode described above

Upload the Karrigell package on your site and set the permissions as described in section 2.1 above with your FTP or SSH client

Suppose the directory where you can store files on the web host is /var/www/html/MySite. You will install Karrigell in the subfolder /var/www/html/MySite/karrigell (this means that the script Karrigell.py is in this folder)

You site will be configured as a Virtual Host ; the httpd.conf of the host will have a section <VirtualHost> dedicated to the site

It will look like this :

<VirtualHost 10.193.117.191:80>
    ServerAdmin john.doe@nowhere.org
    ServerName MySite
    DocumentRoot /var/www/html/MySite/karrigell/webapps
    <Directory /var/www/html/MySite/karrigell/webapps>
        AllowOverride None
        Options -Indexes FollowSymLinks ExecCGI
        Order allow,deny
        Allow from all
        # manage urls matching folders
        ErrorDocument 403 /cgi-bin/start.cgi
        # rewrite urls so that Karrigell manages scripts with
        # extensions py,pih,hip and ks
        RewriteEngine On
        RewriteRule ^(.*)\.(py|pih|hip|ks)$ /cgi-bin/start.cgi
        # and ks scripts with a function name
        RewriteRule ^(.*)\.ks/.* /cgi-bin/start.cgi
    </Directory>
    ScriptAlias /cgi-bin/ "/var/www/html/MySite/karrigell/webapps/cgi-bin/"
    AddHandler   cgi-script  .cgi
    <Directory /var/www/html/MySite/karrigell/webapps/cgi-bin>
        AllowOverride None
        Options FollowSymLinks ExecCGI
        Order allow,deny
        Allow from all
    </Directory>
</VirtualHost>

You will have to edit this template with the real IP address, port, server admin mail address, server name, and of course the path to your Karrigell installation

5.4 lighttpd

In their own words :

Security, speed, compliance, and flexibility--all of these describe LightTPD which is rapidly redefining efficiency of a webserver; as it is designed and optimized for high performance environments. With a small memory footprint compared to other web-servers, effective management of the cpu-load, and advanced feature set (FastCGI, CGI, Auth, Output-Compression, URL-Rewriting and many more) LightTPD is the perfect solution for every server that is suffering load problems. And best of all it's Open Source licensed under the revised BSD license.

Configuration for Karrigell by Laurent Pointal

Make your Karrigell site working, listening on a port (8082 for instance).

Enable mod_proxy in lighttpd

    cd /etc/lighttpd/conf-enabled
    ln -s ../conf-available/10-proxy.conf 10-proxy.conf

Use a configuration like this one:

$HTTP["host"] == "my.virtual.host.com" {
                proxy.server = ( "" =>
                                   ((
                                        "host" => "127.0.0.1",
                                        "port" => 8082
                                   ))
                                )
}

If you want to directly serve some files by lighttpd without going through Karrigell (typically static content, pictures etc), you can make a configuration like this:
```
$HTTP["host"] == "my.virtual.host.com" {
        $HTTP["url"] !~ ".*/static/.*" {
                proxy.server = ( "" =>
                                   ((
                                        "host" => "127.0.0.1",
                                        "port" => 8082
                                   ))
                                )
                }
        else $HTTP["url"] =~ ".*/static/.*" {
                server.document-root = "/path/to/my/karrigell/site"
                dir-listing.activate = "enable"
                }
}
```
5.5 Xitami
Xitami is a lightweight and fast web server, available for free. Download the latest version and follow the installation instructions
Launch the server, then open a console window, go to the Karrigell directory and enter python Karrigell_xitami.py. All the requests sent to an URL beginning with http://localhost/karrigell will be handled by Karrigell
Xitami and Karrigell are interfaced through the "Long Running Web Process", avoiding the overhead of CGI
You can replace karrigell by another name by editing the file Karrigell_xitami.py and changing the value of the variable karrigellUrl