Karrigell Documentation

Version 2.3.1 02 09 06

Français

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.

5.1 Apache

5.1.1 Introduction

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

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