5. Configuration

The configuration is defined on three levels :
  • command line : when the built-in server is used, the directory where the server-specific configuration script is located can be specified 

    python Karrigell.py [ServerConfigDirectory]

    By default, the directory used is the same as the one where Karrigell.py stands

  • server configuration script : defines directories used by the framework, and options relevant at the server level (session storage, maximum number of threads, etc). For the built-in web server, these data are stored in the script server_config.py in the Server Configuration Directory defined above

  • host configuration scripts : defined in the script conf.py in each host data directory ; for localhost, it is located in the folder data/www

Each host can be configured by a specific configuration file. The mapping between a host name and its configuration file is defined in the plain text file hosts in the Server Configuration Directory

You can edit the host configuration script either with a text editor, or online from the Administration menu, accessible from the home page

5.1 Server configuration

This script defines the following values :

karrigell_dir
The directory where the core Karrigell framework is installed : the one where the folders core and package stand

host_conf_dir

The directory where the host-specific configuration text file hosts is located

port

The port where the server runs
persistent_sessions
In most situations, it is better to set this option to True, meaning that session data is stored on disk : storing it in memory is not safe in a multi threaded environment, either with the built-in multi-threaded server or behind Apache

This limits session data to types that can be serialized by the pickle module

In case you need to store unpicklable Python objects as session data, you can set persistent_sessions to False. As mentioned above, be aware that this will only work reliably with a mono-process, mono-thread server such as the built-in Karrigell_monoprocess.py or Karrigell_async.py

cache
Boolean to specify if HTTP caching should be used (with header If-Modified-Since). Defaults to True
ipv6
Boolean to specify if IPv6 should be used instead of IPv4. Defaults to False
max_threads
The maximum number of threads than can be run by the multi-threaded built-in web server
process_num
The number of processes launched when the multi-process built-in web server is started
silent
A boolean value to indicate if the server should write a logging info on sys.stderr for each request
modules
A dictionary mapping name of steps in request processing to a list of modules. When the specified step is reached, the function main() of each module is applied to the request handler object

5.2 Host configuration

The values that can be set are :

root_dir
Set the root_dir option to the full name of the Root Directory, the one from which you'll want to serve files. The default is the folder www in the Server Directory
data_dir
The directory where host-specific data stands : users database, translation file, session data
cache_dir
The directory where script cache stands. The cache avoids parsing scripts each time they are run ; it is updated when the source code of a script is modified
If set to None, script caching is disabled
cgi_dir
The directory where CGI scripts are located
allow_directory_listing
The list of user roles (see authentication) that can see directory listings if a url matches a directory with no index file in it. If None is in the list, all users can see the listings If value is ['admin','edit'], only users with one of the roles 'admin' or 'visit' will see a listing ; other users will get an error message
Defaults to [None]
hide_extensions
A list of file extensions that will be hidden (return error 403)
ignore
A list of regular expression patterns that will be matched to url paths ; if a match succeeds then the server will return error 403
This can be used to forbid access to a set of directories. For instance if you have a version control that creates directories named cvs you can forbid access to them with this line :
ignore = [".*/cvs/.*"]
logging_file
The path of a logging file. If not set, no logging is performed
logging_rotate
If logging_file is set, indicate when the log file should be changed. If set to None, the same log file is always used. If set to "monthly", "daily" or "hourly", the logging file changes with the month, the day or the hour ; the name of the logging file is the one set in loggin_file, with the month / day / hour appended
output_encoding
A string = the encoding to use to send data back to the client
alias
A dictionary mapping an alias to the path of a folder in the file system. For instance :
then the url htpp://localhost/scripts/index.html will serve the file
debug
indicates if you want detailed information, including the Python traceback, to be printed in case of error or exception during script execution. Defaults to True. If set to False, only a message like "Server was unable to process the request" will be printed, without any other detail
gzip
If set to True, and the user agent supports gzip encoding (most browsers do), the server compresses the data sent to the user agent for text files. This reduces network load, but slows down the server a little
global_modules
A list of paths to the modules which must be imported in every script run by Karrigell. If you have a line like 
global_modules = ["/usr/scripts/myScript.py"]
the module name myScript will be available in the namespace of all scripts
max_sessions
The maximum number of sessions that can be stored. Defaults to 500