Outdated egg!
This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.
If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.
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.
TOC »
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
- chickadee-start-serverprocedure
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
- chickadee-uriparameter
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.
- cdoc-uriparameter
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").
- incremental-search-uriparameter
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").
- chickadee-css-filesparameter
List of URIs to CSS files for Chickadee.
Defaults to (list (uri-reference "/cdoc/chickadee.css")).
- chickadee-early-js-filesparameter
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.
- chickadee-js-filesparameter
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")).
- maximum-match-resultsparameter
Maximum number of match results to return for a match query. Default: 250.
- maximum-match-signaturesparameter
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.
- incremental-searchparameter
Number of incremental search results to display; 0 or #f to disable. Defaults to 0.
- incremental-search-delayparameter
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.
- cache-nodes-forparameter
Time in milliseconds to inform browsers that node pages should be cached for. Defaults to 300. If #f, no caching is done.
- cache-static-content-forparameter
Time in milliseconds to inform browsers that static content such as CSS and Javascript should be cached for.
- last-modifiedparameter
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.
- ajax-logparameter
AJAX access log pathname. Separate from the usual access-log because this is potentially disk and CPU intensive. Set to #f to disable.
Debugging
- %chickadee:debug-incremental-search-latencyparameter
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
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.
About this egg
Source
https://github.com/ursetto/chickadee
Author
Jim Ursetto
Version history
- 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.
License
Copyright (c) 2010-2019 Jim Ursetto. License: 3-clause BSD.