Karrigell Documentation

Version 2.2.1 13 12 05

Français

3. The Web server

The default built-in web server is asynchronous, like in the modules asyncore and asynchat in the standard Python distribution. As far as I could test it, it is very efficient, with very good response time (1)

3.1 The Root Directory

The Root Directory is the place where you place the files that will be reached on top of the url hierarchy ; if you place myfile.htm in this directory, it will be called by http://myhost/myfile.htm where myhost is your host name (try localhost)

On installation, the Root Directory is the same as the Server Directory. You can change this in the configuration file (see 3.4)

3.2 Serving static files

To serve "static" files (HTML files, GIF or JPEG Images, etc) all you have to do is to create them using you favorite tool and save them to the Root Directory

Suppose you create an HTML document called myFile.htm and put it in the Root Directory. Launch your favorite Web Browser and type in the URL http://myhost/myFile.htm; you should see the file displayed in the browser

If you save the file in a subdirectory, you must prepend its name : for file myImage.gif in subdirectory Images, the url will be http://myhost/Images/myImage.gif

To reach files out of the Root Directory, use aliases (see 3.4)

If no file name is specified and the url matches a directory, the server looks for a file with the name index.html, index.htm, index.py, index.pih, index.hip or index.ks. If it doesn't find one, it prints a list of the subfolders and files in the directory; if it finds more than one, it raises an exception

If the extension of a file is not specified, the server will look for a file with one of the extensions html, htm, py, pih, hip or ks. If it finds one, this file is used ; if it finds more than one, an exception is raised ; if no file is found, an exception is raised too

3.3 Command line options


The command line is :

python Karrigell.py [-P port] [-S] [-D] [initFile]

where

  • port is the HTTP port number (default 80)
  • S specifies "silent" mode : by default, Karrigell prints a trace for each request it receives. With the -S option, nothing is printed
  • D sets debug level to 1 (see below in 3.4 Configuration file)
  • initFile is the configuration file (see below). Default is Karrigell.ini in the server directory

3.4 Configuration file

Configuration options are set in a configuration file. By default it is the Karrigell.ini file in the server directory. You can set it to a different file in the command line

The configuration file is split into several sections :

[Directories]

root
Set the root option to the full name of the Root Directory, the one from which you'll want to serve files. On installation it is not set, the default is the Server Directory
protected
a list of protected directories ; for each script in these directories a script called AuthentScript.py will be automatically executed first. This script AuthentScript.py must be written by the administrator and put in the directory
By default, only the directory admin is protected. Use ";" to add other ones
allow_directory_listing
If a url matches a directory with no index file in it, determine who can read the directory content :
  • all = all users
  • none = no user

Defaults to "none"
[Applications]
Maps file extensions to MIME types ; as far as I know this works with Netscape, but Internet Explorer overrides these settings
[Alias]
You can associate an alias to a path on the file system. For instance, if you create this alias : scripts=c:\My Documents\Karrigell scripts, then the url htpp://localhost/scripts/index.htm will serve the file c:\My Documents\Karrigell scripts\index.htm
[Server]
port
Set the port option to change the HTTP port (default 80)
debug
The debug option specifies the debug level. If set to 1, all imported modules are reset at every import, so you don't have to restart the server when you change something in an imported script
silent
If the silent option is set to 1, nothing is printed on the console window
gzip
If the gzip option is set to 1, and the user agent supports gzip encoding (most browsers do), the server compresses the data sent to the user agent. This reduces the use of the network, but slows down the server a little
global
In the global option, specify the path to the modules which must be imported in every script run by Karrigell. If you have a line like
global=%(base)s/myScript.py;%(base)s/myScript1.py
both modules myScript and myScript1 will be available in the namespace of all scripts
ignore
A list of urls to ignore if not found (return the HTTP code 204 instead of 404). Used by default to ignore the url /favicon.ico, searched by many browsers
[Translation]
Specifies the language used in the application, regardless of the options defined in the web browser. Set lang=default if you don't want any translation, lang=en if you want to use translations in English, etc

A variable base is set by Karrigell before loading the configuration file, its value is the server directory. See example of use with %(base)s/ in the default Karrigell.ini file

[VirtualHost name:port]

Karrigell supports the notion of virtual hosts, allowing to serve different hosts with different names on the same server

To specify a virtual host you add a line like this in the configuration file :

[VirtualHost name[:port]]

where name is the host name (like www.test.org) and port is the port number (defaults to 80)

You have to specify a directory from which the serve will serve the requests to this specific host :

root = /web/mydir

(1) you can also use an alternative built-in web server based on the modules SocketServer, BaseHTTPServer and SimpleHTTPServer module in the standard Python distribution : run python Karrigell_SocketServer.py

If you prefer a threaded server use python Karrigell_ThreadedSocketServer.py