5. Karrigell with Apache, lighttpd and Xitami

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

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

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

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, apache_handler.cgi, located in folder webapps/cgi-bin

5.2.1 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 /doc/ "C:/cygwin/home/Karrigell/doc/"
Alias /debugger/ "C:/cygwin/home/Karrigell/debugger/"
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
    # list the files to search if a url matches a directory name
    DirectoryIndex index.html index.htm index.py index.pih index.hip index.ks
    # 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>

5.2.3 Karrigell configuration file

set [Server] persistentSession to 1 and debug to 0

WarningOn 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 lighttpd

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