Before using chickadee, you need to download or create a chicken-doc repository. Next, fetch chickadee using chicken-install:

# chicken-install chickadee

This installs the chickadee library files, static web files, configuration files and a helper program called chickadee which simplifies running your own server.

chickadee is usually ready to run without further configuration:

$ chickadee serve

This starts a server on port 8080, using the default configuration and data files that were installed via chicken-install. Access, debug and AJAX logs are disabled, and error logging is sent to stderr. Therefore no special privileges are required to start the default config.

You may sometimes need to customize the server settings -- for example to start on a different port. This is explained below.

For permanent or complex configuration changes, the default configuration file can be modified, or the chickadee wrapper can be directed to use an alternate config file. Keep in mind that the defaults will be overwritten whenever the egg is upgraded.

conf is the configuration file and base is the base directory containing all chickadee's datafiles. At startup, chickadee changes to the base directory, and so all paths in the config file are relative to that location.

Actually, base is always the directory containing conf, so you can copy the default base directory tree anywhere, point chickadee to that config file, and that copy will be used.

The actual path to chickadee's datafiles is controlled by the configuration options root-path, access-log and so on, which by default use relative paths (to the location of the config file). You can use absolute paths instead if you like; the "base directory" is just a matter of convenience.

Configuration syntax and examples are described later in this document.

The CSS and Javascript static files can be modified to customize the look and feel of chickadee. The recommended way to do this is to make a copy of the chickadee base directory first. A further suggestion is to rename (or copy) the files you want to change and then update their paths in the configuration file:

The rationale behind this is to allow you to copy datafile updates from the egg into your private copy without clobbering your changes. (A better solution to initialize and update a copy might be provided in the future.)

Currently the page layout, and especially the root page, are not customizable without editing the source code.

Defaults to (uri-reference "/chickadee"), so that the node foreign types is accessible at /chickadee/foreign/types.

[parameter]cdoc-uri

Internal URI for Chickadee, used to perform path and identifier lookup and searches.

Although you can choose to make cdoc-uri a child of chickadee-uri, keep in mind it may conflict with an existing node name.

Defaults to (uri-reference "/cdoc").

[parameter]incremental-search-uri

URI used to provide incremental search capability. This URI is arbitrary, but is typically a child of cdoc-uri. Due to AJAX limitations it must inhabit the same domain name as chickadee-uri.

Defaults to (uri-reference "/cdoc/ajax/prefix").

[parameter]chickadee-css-files

List of URIs to CSS files for Chickadee.

Defaults to (list (uri-reference "/cdoc/chickadee.css")).

[parameter]chickadee-js-files

List of URIs to Javascript files for Chickadee.

Defaults to (list (uri-reference "/cdoc/chickadee.js")).

[parameter]maximum-match-results

Maximum number of match results to return for a match query. Default: 250.

[parameter]maximum-match-signatures

Maximum number of signatures to return for a match query, up to maximum-match-results. Default: 100. Obtaining signatures may increase disk load in the current implementation.

[parameter]incremental-search

Number of incremental search results to display; 0 or #f to disable. Defaults to 0.

[parameter]incremental-search-delay

Time in milliseconds to delay incremental search requests. Defaults to 50, which seems reasonable for WAN or LAN use. 20 will give even better interactive response on a fast network and CPU.

[parameter]cache-nodes-for

Time in milliseconds to inform browsers that node pages should be cached for. Defaults to 300. If #f, no caching is done.

[parameter]cache-static-content-for

Time in milliseconds to inform browsers that static content such as CSS and Javascript should be cached for.

[parameter]last-modified

Base time used for node last-modified calculations, in seconds.

Chickadee uses the overall repository modification time (updated whenever a reindex is done) to determine when a node was last modified. Browsers with a vaild cached copy will receive a "304 Not Modified" response.

However, the value of last-modified will also be considered; the modification time is taken as the maximum of the two values. This is done because changes to program logic may change the rendering of the page even when the repository has not changed. For example, set last-modified to (current-seconds) to simply invalidate all pages when the server is restarted.

Defaults to 0.

[parameter]ajax-log

AJAX access log pathname. Separate from the usual access-log because this is potentially disk and CPU intensive. Set to #f to disable.

A sample AppArmor profile is included in the egg source. It assumes the use of a dedicated startup script for chickadee, so that the restrictions only apply when calling chickadee via the script. The sample also uses the config-nginx.scm built-in config file to run behind an nginx proxy.

Generally, you just have to update CHICKEN in both files to reflect your installed Chicken, LOGDIR to specify your log directory, install the profile in /etc/apparmor.d, place the script in /usr/local/bin, and tweak the script and profile if necessary. A detailed explanation of AppArmor is beyond the scope of this document.