1.2. Apache integration

There are several ways to run Karrigell with Apache :

modedescriptionproscons
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
WSGI mode Communication between Apache and Karrigell uses the WSGI standard and relies on the Apache module mod_wsgi
  • good performance
  • WSGI is the de facto standard for framework integration
  • requires the mod_wsgi module (not available on many shared hosting services)
mod_python mode mod_python embeds a Python interpreter in the Apache server
  • good performance (no CGI overhead)
  • requires installation of the mod_python module (not available on all shared web hosting solutions)
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
  • good performance
  • session object can be managed in memory (more flexible)
  • requires permission to run a long-running process on the server

1.2.1 Overview

To run Karrigell behind Apache, some options will be defined in the httpd.conf configuration file : the server port, the Document Root for the host, and directives that apply to the Document Root content. To simplify installation, the only required directive is AllowOverride All, which tells the server to apply the directives in .htaccess files : a model of these files is provided in the Karrigell distribution

This means that the section <Directory> relative to your Document Root in httpd.conf should be like this : 

<Directory [[document_root]]>
    AllowOverride All
    Order allow,deny
    Allow from all
</Directory >

Karrigell will only manage one host (virtual hosts are managed by Apache), which simplifies the configuration options

1.2.2 CGI mode

This mode uses the Apache modules mod_rewrite and mod_cgi ; all the urls that must be managed by Karrigell (everything except one of the static file extensions html, htm, css, js, jpg, jpeg, gif, png) are "rewritten" by mod_rewrite to be processed by a single cgi script, k_handler.cgi, located by default in the folder karrigell/apache/cgi-bin. This script takes Karrigell configuration options from the configuration script conf.py

These modules must be loaded at Apache startup, so make sure that these lines are uncommented in your httpd.conf file : 

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

The next step is to install or upload the content of Karrigell-Apache-3.1.1.tar.gz in the Document Root of your Apache space

Then rename the file .htaccess_cgi in this Document Root to .htaccess

You must also edit the first line of the CGI script k_handler.cgi with the appropriate command to start the Python interpreter. On Unix/Linux it is usually #!/usr/bin/python and on Windows #!python, but this might depend on the server configuration

In the best case, this is enough to get Karrigell running ! You will have to set write and execution mode in some folders : write for apache/data, execution for apache/cgi-bin. The exact mode will slightly depend on the server

In other cases (for instance in a shared web hosting situation) you will not be able to run CGI scripts outside of a specific folder. In this case :

  • put all the files in the apache/cgi-bin directory in this CGI folder
  • edit the script conf.py and replace theses values :
    • root_dir = (the Document Root full path)
    • karrigell_dir = os.path.join(root_dir,"karrigell")
    • server_dir = (the full path of the directory where you put cgi-bin)
    • data_dir = the full path of a directory with WRITE mode enabled, if possible outside of the Document Root for security reasons
    • cache_dir = os.path.join(data_dir, "cache")
  • in the .htaccess file in the Document Root, edit the url of the script k_handler.cgi with the correct value. Usually Apache is configured with a ScriptAlias directive saying that scripts that reside in the CGI folder are called with the url cgi-bin ; in this case you would set the value /cgi-bin/k_handler.cgi in .htaccess

If you don't know the full paths, you can run the CGI script cgi_dir.cgi which will give you the full path of the CGI folder ; you should be able to deduce the other paths from it

1.2.3 Integration with mod_wsgi

mod_wsgi is a module which enables Apache to host any Python application which supports the Python WSGI interface

The script wsgi.py in folder apache/mod_wsgi handles all the urls that must be managed by Karrigell

mod_wsgi must be enabled by the Apache server. To do this, the first thing to do is download and install mod_python from the website, and follow the instructions to enable it in the Apache configuration file. In the "Dynamic Shared Object (DSO) Support" section of httpd.conf, add the line : 

LoadModule wsgi_module modules/mod_wsgi.so

Install or upload the content of Karrigell-Apache-3.1.1.tar.gz in the Document Root of your Apache space

If you have a file .htaccess in this Document Root, delete it or give it another name

Then in httpd.conf, add this line : 

WSGIScriptAlias / /path-to-Karrigell-root/karrigell/apache/mod_wsgi/wsgi.py

This will direct all the requests to the script wsgi.py, which manages all requests using Karrigell and returns the result to the Apache server

1.2.4 Integration with mod_python

Mod_python is an Apache module that embeds the Python interpreter within the server. It avoids the CGI overhead of starting the interpreter for each requests and thus provides much better performance

The script mod_python_handler.py in folder apache/mod_python handles all the urls that must be managed by Karrigell

Of course mod_python must be enabled by the Apache server. To do this, the first thing to do is download and install mod_python from the website, and follow the instructions to enable it in the Apache configuration file. In the "Dynamic Shared Object (DSO) Support" section of httpd.conf, add the line : 

LoadModule python_module modules/mod_python.so

Install or upload the content of Karrigell-Apache-3.1.1.tar.gz in the Document Root of your Apache space

Then rename the file .htaccess_mod_python in this Document Root to .htaccess

This is enough to get Karrigell running. For security reasons, it is better to edit the configuration script conf.py and replace the value data_dir by the full path of a directory with WRITE mode enabled, outside of the Document Root