chickadee

chickadee is a web interface to chicken-doc.

Quickstart

# chicken-install chickadee
$ chickadee serve

This will start a chickadee server on http://localhost:8080, using your global chicken-doc repository.

chickadee

Setting up a server

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.

Customization at the command-line

The chickadee wrapper accepts options which override commonly-changed settings in the configuration file, so that you don't need to modify the config file for simple changes.

usage: chickadee serve [options] [conf-file]
options:

  -p --port NUM         Port number

  -A --access-log FILE  Access log file
  -E --error-log FILE   Error log file
  -D --debug-log FILE   Debug log file
  -J --ajax-log FILE    AJAX access log
    FILE is a filename relative to the directory holding [conf-file].
    It may be "-" to log to the console or "" to suppress logging.

examples:
  chickadee serve -p 8081
    Start a server on port 8081.
  chickadee serve -A - -D /tmp/debug.log -J /tmp/ajax.log -E ""
    Log accesses to stdout, debugging information to /tmp/debug.log,
    and AJAX accesses to /tmp/ajax.log.  Error logging is suppressed.

Customization of the configuration file

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.

You can find the location of the default chickadee config file with:

$ chickadee location
conf: /usr/local/chicken-4/share/chicken/chickadee/config.scm
base: /usr/local/chicken-4/share/chicken/chickadee

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.

$ cp -rp /usr/local/chicken-4/share/chicken/chickadee ~
$ chickadee serve ~/chickadee/config.scm

You can also place multiple config files inside the same base directory, sharing the same datafiles with different configurations:

$ cp ~/chickadee/config.scm ~/chickadee/config-prod.scm
$ vi ~/chickadee/config-prod.scm
$ chickadee serve ~/chickadee/config-prod.scm

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.

Customization of look and feel

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:

$ cp ~/chickadee/root/cdoc/chickadee.css \
     ~/chickadee/root/cdoc/chickadee-mine.css

# then in ~/chickadee/config.scm, change
(chickadee-css-files (list (uri "/cdoc/chickadee.css")))
# to
(chickadee-css-files (list (uri "/cdoc/chickadee-mine.css")))

Finally you might even want to change the configuration file name:

$ mv ~/chickadee/config.scm ~/chickadee/config-mine.scm

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.

API

[procedure] (chickadee-start-server)

Start the Chickadee server. Server configuration is done via parameters and, as spiffy is used as the backend webserver, all of its configuration options also apply.

Configuration

[parameter] chickadee-uri

Main access URI to Chickadee for users, as a URI object.

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-early-js-files

List of URIs (uri-reference objects) to early Javascript files for Chickadee. These are inserted prior to the document body; for example, scripts such as Modernizr must be loaded prior to the body.

[parameter] chickadee-js-files

List of URIs (uri-reference objects) to Javascript files for Chickadee. These are inserted after the document body, as most scripts should be.

Any item may be a plain string instead, in which case it is inserted literally in the document as a Javascript snippet between script tags. For example, you might use this to implement a jQuery fallback.

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.

Debugging

[parameter] %chickadee:debug-incremental-search-latency

Simulate network latency of N milliseconds for incremental search. Allows you to test estimated interactive response across the Internet on a local system.

Examples

Configuration examples

An example local configuration file for the chickadee wrapper. If you add (chickadee-start-server) to the end, you can run this file as a standalone program.

Also see config.scm, which is installed as the default config file, and is more up-to-date.

(use chickadee spiffy uri-common)
(define uri uri-reference)
(root-path "root")
(debug-log (current-error-port))
(server-port 8080)
(access-log "logs/access.log")
(max-connections 8)
(ajax-log "/tmp/ajax.log")
(cdoc-uri (uri "/cdoc"))
(chickadee-uri (uri "/chickadee"))
(incremental-search-uri (uri "/cdoc/ajax/prefix"))
(chickadee-css-files (list (uri "/cdoc/chickadee.css")))
(chickadee-js-files
 (list (uri "http://code.jquery.com/jquery-1.4.2.min.js")
       (uri "/cdoc/jquery.metadata.2.1.min.js")
       (uri "/cdoc/chickadee-jquery.js")))
(maximum-match-results 250)
(maximum-match-signatures 100)
(incremental-search 15)
(incremental-search-delay 50)
(cache-nodes-for 300)
(cache-static-content-for 1800)
(last-modified (current-seconds))

Configuration of the primary chickadee server behind an nginx caching proxy. Also see config-nginx.scm, which is installed alongside the egg, and is more up-to-date.

(use chickadee spiffy uri-common)
(define uri uri-reference)
(root-path "root")
(debug-log (current-error-port))
(access-log "logs/access.log")
(error-log "logs/error.log")
(server-port 8383)
(max-connections 8)
(ajax-log #f)
(cdoc-uri (uri "/cdoc"))
(chickadee-uri (uri "/chickadee"))
(incremental-search-uri (uri "/cdoc/ajax/prefix"))
(chickadee-css-files (list (uri "/cdoc/chickadee.css?5")))
(chickadee-js-files
 (list (uri "http://code.jquery.com/jquery-1.4.2.min.js")
       (uri "/cdoc/jquery.metadata.2.1.min.js")
       (uri "/cdoc/chickadee-jquery.js?2")))
(maximum-match-results 250)
(maximum-match-signatures 100)
(incremental-search 15)
(incremental-search-delay 50)
(cache-nodes-for 600)
(cache-static-content-for 1800)
(last-modified (current-seconds))
(chickadee-start-server)

Usage examples

Webjump for Conkeror

AppArmor

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.

0.12.1: Port to Chicken 5. Enhance signature readability.
0.11.2: Add a second parameter to the last-modified header vector to comply with stricter header checking in intarweb 1.7.
0.11.1: Correct a distribution error
0.11.0: Decluttered appearance. Link and style definition identifiers and arguments that appear in verbatim plaintext, with new chicken-doc-html.
0.10.3: Permit arbitrary JS snippets; fall back to local jQuery in production config
0.10.2: Use local jquery for default config, improving offline usage
0.10.1: Limit match result set size to prevent runaway memory usage during regexp search. Also added example AppArmor profile.
0.10.0: Current version
0.9.8: Add chickadee wrapper.
0.9.0: Initial release.