chickadee is a web interface to chicken-doc.
# chicken-install chickadee $ chickadee serve
This will start a chickadee server on http://localhost:8080, using your global chicken-doc repository.
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.
Customization of look and feel
$ 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.
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.
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
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
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.
Simulate network latency of N milliseconds for incremental search. Allows you to test estimated interactive response across the Internet on a local system.
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))
(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)
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
- Permit arbitrary JS snippets; fall back to local jQuery in production config
- Use local jquery for default config, improving offline usage
- Limit match result set size to prevent runaway memory usage during regexp search. Also added example AppArmor profile.
- Current version
- Add chickadee wrapper.
- Initial release.
Copyright (c) 2010, 2011, 2012 Jim Ursetto. License: 3-clause BSD.