source: project/wiki/eggref/4/chickadee @ 33992

Last change on this file since 33992 was 33992, checked in by Jim Ursetto, 2 years ago

wiki/chickadee: update for 0.11.2

File size: 12.9 KB
Line 
1== chickadee
2
3''chickadee'' is a web interface to {{chicken-doc}}.
4
5=== Quickstart
6
7 # chicken-install chickadee
8 $ chickadee serve
9
10This will start a chickadee server on [[http://localhost:8080]],
11using your global chicken-doc repository.
12
13[[toc:]]
14
15=== Setting up a server
16
17Before using ''chickadee'', you need to download or create a
18[[chicken-doc]] repository.  Next, fetch ''chickadee'' using
19{{chicken-install}}:
20
21 # chicken-install chickadee
22
23This installs the chickadee library files, static web files,
24configuration files and a helper program called {{chickadee}} which
25simplifies running your own server.
26
27chickadee is usually ready to run without further configuration:
28
29 $ chickadee serve
30
31This starts a server on port 8080, using the default configuration and
32data files that were installed via {{chicken-install}}.  Access,
33debug and AJAX logs are disabled, and error logging is sent to
34''stderr''.  Therefore no special privileges are required to start the
35default config.
36
37You may sometimes need to customize the server settings -- for example
38to start on a different port.  This is explained below.
39
40==== Customization at the command-line
41
42The {{chickadee}} wrapper accepts options which override
43commonly-changed settings in the configuration file, so
44that you don't need to modify the config file for simple
45changes.
46
47 usage: chickadee serve [options] [conf-file]
48 options:
49 
50   -p --port NUM         Port number
51 
52   -A --access-log FILE  Access log file
53   -E --error-log FILE   Error log file
54   -D --debug-log FILE   Debug log file
55   -J --ajax-log FILE    AJAX access log
56     FILE is a filename relative to the directory holding [conf-file].
57     It may be "-" to log to the console or "" to suppress logging.
58
59 examples:
60   chickadee serve -p 8081
61     Start a server on port 8081.
62   chickadee serve -A - -D /tmp/debug.log -J /tmp/ajax.log -E ""
63     Log accesses to stdout, debugging information to /tmp/debug.log,
64     and AJAX accesses to /tmp/ajax.log.  Error logging is suppressed.
65
66==== Customization of the configuration file
67
68For permanent or complex configuration changes, the default
69configuration file can be modified, or the {{chickadee}} wrapper can
70be directed to use an alternate config file.  Keep in mind that
71the defaults will be overwritten whenever the egg is upgraded.
72
73You can find the location of the default chickadee config file with:
74
75 $ chickadee location
76 conf: /usr/local/chicken-4/share/chicken/chickadee/config.scm
77 base: /usr/local/chicken-4/share/chicken/chickadee
78
79{{conf}} is the configuration file and {{base}} is the base directory
80containing all chickadee's datafiles.  At startup, chickadee changes
81to the {{base}} directory, and so all paths in the config file are relative
82to that location.
83
84Actually, {{base}} is always the directory containing {{conf}}, so
85you can copy the default base directory tree anywhere, point chickadee
86to that config file, and that copy will be used.
87
88 $ cp -rp /usr/local/chicken-4/share/chicken/chickadee ~
89 $ chickadee serve ~/chickadee/config.scm
90
91You can also place multiple config files inside the same base directory,
92sharing the same datafiles with different configurations:
93
94 $ cp ~/chickadee/config.scm ~/chickadee/config-prod.scm
95 $ vi ~/chickadee/config-prod.scm
96 $ chickadee serve ~/chickadee/config-prod.scm
97
98The actual path to chickadee's datafiles is controlled by the
99configuration options {{root-path}}, {{access-log}} and so on, which
100by default use relative paths (to the location of the config file).
101You can use absolute paths instead if you like; the "base directory"
102is just a matter of convenience.
103
104Configuration [[#Configuration|syntax]] and [[#Examples|examples]] are
105described later in this document.
106
107==== Customization of look and feel
108
109The CSS and Javascript static files can be modified to customize
110the look and feel of chickadee.  The recommended way to do this
111is to [[#Customization of the configuration file|make a copy]] of
112the chickadee base directory first.  A further suggestion is to
113rename (or copy) the files you want to change and then update
114their paths in the configuration file:
115
116 $ cp ~/chickadee/root/cdoc/chickadee.css \
117      ~/chickadee/root/cdoc/chickadee-mine.css
118
119 # then in ~/chickadee/config.scm, change
120 (chickadee-css-files (list (uri "/cdoc/chickadee.css")))
121 # to
122 (chickadee-css-files (list (uri "/cdoc/chickadee-mine.css")))
123
124Finally you might even want to change the configuration file name:
125
126 $ mv ~/chickadee/config.scm ~/chickadee/config-mine.scm
127
128The rationale behind this is to allow you to copy datafile updates
129from the egg into your private copy without clobbering your changes.
130(A better solution to initialize and update a copy might be provided in
131the future.)
132
133Currently the page layout, and especially the root page, are not
134customizable without editing the source code.
135
136=== API
137
138<procedure>(chickadee-start-server)</procedure>
139
140Start the Chickadee server.  Server configuration is
141done via parameters and, as [[spiffy]] is used as the
142backend webserver, all of its configuration options also
143apply.
144
145=== Configuration
146
147<parameter>chickadee-uri</parameter>
148
149Main access URI to Chickadee for users, as a URI object.
150
151Defaults to {{(uri-reference "/chickadee")}}, so that
152the node {{foreign types}} is accessible at {{/chickadee/foreign/types}}.
153
154<parameter>cdoc-uri</parameter>
155
156Internal URI for Chickadee, used to perform path and identifier lookup
157and searches.
158
159Although you can choose to make {{cdoc-uri}} a child of
160{{chickadee-uri}}, keep in mind it may conflict with an existing node
161name.
162
163Defaults to {{(uri-reference "/cdoc")}}.
164
165<parameter>incremental-search-uri</parameter>
166
167URI used to provide incremental search capability.  This URI is
168arbitrary, but is typically a child of {{cdoc-uri}}.  Due to AJAX
169limitations it must inhabit the same domain name as {{chickadee-uri}}.
170
171Defaults to {{(uri-reference "/cdoc/ajax/prefix")}}.
172
173<parameter>chickadee-css-files</parameter>
174
175List of URIs to CSS files for Chickadee.
176
177Defaults to {{(list (uri-reference "/cdoc/chickadee.css"))}}.
178
179<parameter>chickadee-early-js-files</parameter>
180
181List of URIs (uri-reference objects) to early Javascript files for Chickadee.
182These are inserted prior to the document body; for example, scripts such as
183Modernizr must be loaded prior to the body.
184
185<parameter>chickadee-js-files</parameter>
186
187List of URIs (uri-reference objects) to Javascript files for Chickadee.
188These are inserted after the document body, as most scripts should be.
189
190Any item may be a plain string instead, in which case it is
191inserted literally in the document as a Javascript snippet between script tags.
192For example, you might use this to implement a jQuery fallback.
193
194Defaults to {{(list (uri-reference "/cdoc/chickadee.js"))}}.
195
196<parameter>maximum-match-results</parameter>
197
198Maximum number of match results to return for a match query.
199Default: 250.
200
201<parameter>maximum-match-signatures</parameter>
202
203Maximum number of signatures to return for a match query, up to
204{{maximum-match-results}}.  Default: 100.  Obtaining signatures
205may increase disk load in the current implementation.
206
207<parameter>incremental-search</parameter>
208
209Number of incremental search results to display; 0 or #f to disable.
210Defaults to 0.
211
212<parameter>incremental-search-delay</parameter>
213
214Time in milliseconds to delay incremental search requests.  Defaults
215to 50, which seems reasonable for WAN or LAN use.  20 will give even
216better interactive response on a fast network and CPU.
217
218<parameter>cache-nodes-for</parameter>
219
220Time in milliseconds to inform browsers that node pages should be
221cached for.  Defaults to 300.  If #f, no caching is done.
222
223<parameter>cache-static-content-for</parameter>
224
225Time in milliseconds to inform browsers that static content such as
226CSS and Javascript should be cached for.
227
228<parameter>last-modified</parameter>
229
230Base time used for node last-modified calculations, in seconds.
231
232Chickadee uses the overall repository modification time (updated
233whenever a reindex is done) to determine when a node was last
234modified.  Browsers with a vaild cached copy will receive a "304 Not
235Modified" response.
236
237However, the value of {{last-modified}} will also be considered; the
238modification time is taken as the maximum of the two values.  This is
239done because changes to program logic may change the rendering of the
240page even when the repository has not changed.  For example, set
241{{last-modified}} to {{(current-seconds)}} to simply invalidate all
242pages when the server is restarted.
243
244Defaults to 0.
245
246<parameter>ajax-log</parameter>
247
248AJAX access log pathname.  Separate from the usual {{access-log}}
249because this is potentially disk and CPU intensive.  Set to {{#f}} to
250disable.
251
252=== Debugging
253
254<parameter>%chickadee:debug-incremental-search-latency</parameter>
255
256Simulate network latency of N milliseconds for incremental search.
257Allows you to test estimated interactive response across the Internet
258on a local system.
259
260=== Examples
261
262==== Configuration examples
263
264An example local configuration file for the {{chickadee}} wrapper.  If
265you add {{(chickadee-start-server)}} to the end, you can run this file as
266a standalone program.
267
268Also see [[https://raw.github.com/ursetto/chickadee/master/chickadee-config.scm|config.scm]], which
269is installed as the default config file, and is more up-to-date.
270
271<enscript lang="scheme">
272(use chickadee spiffy uri-common)
273(define uri uri-reference)
274(root-path "root")
275(debug-log (current-error-port))
276(server-port 8080)
277(access-log "logs/access.log")
278(max-connections 8)
279(ajax-log "/tmp/ajax.log")
280(cdoc-uri (uri "/cdoc"))
281(chickadee-uri (uri "/chickadee"))
282(incremental-search-uri (uri "/cdoc/ajax/prefix"))
283(chickadee-css-files (list (uri "/cdoc/chickadee.css")))
284(chickadee-js-files
285 (list (uri "http://code.jquery.com/jquery-1.4.2.min.js")
286       (uri "/cdoc/jquery.metadata.2.1.min.js")
287       (uri "/cdoc/chickadee-jquery.js")))
288(maximum-match-results 250)
289(maximum-match-signatures 100)
290(incremental-search 15)
291(incremental-search-delay 50)
292(cache-nodes-for 300)
293(cache-static-content-for 1800)
294(last-modified (current-seconds))
295</enscript>
296
297Configuration of the [[http://api.call-cc.org/doc/|primary chickadee server]] behind an nginx caching proxy.
298Also see [[https://raw.github.com/ursetto/chickadee/master/chickadee-config-nginx.scm|config-nginx.scm]], which
299is installed alongside the egg, and is more up-to-date.
300
301<enscript lang="scheme">
302(use chickadee spiffy uri-common)
303(define uri uri-reference)
304(root-path "root")
305(debug-log (current-error-port))
306(access-log "logs/access.log")
307(error-log "logs/error.log")
308(server-port 8383)
309(max-connections 8)
310(ajax-log #f)
311(cdoc-uri (uri "/cdoc"))
312(chickadee-uri (uri "/chickadee"))
313(incremental-search-uri (uri "/cdoc/ajax/prefix"))
314(chickadee-css-files (list (uri "/cdoc/chickadee.css?5")))
315(chickadee-js-files
316 (list (uri "http://code.jquery.com/jquery-1.4.2.min.js")
317       (uri "/cdoc/jquery.metadata.2.1.min.js")
318       (uri "/cdoc/chickadee-jquery.js?2")))
319(maximum-match-results 250)
320(maximum-match-signatures 100)
321(incremental-search 15)
322(incremental-search-delay 50)
323(cache-nodes-for 600)
324(cache-static-content-for 1800)
325(last-modified (current-seconds))
326(chickadee-start-server)
327</enscript>
328
329==== Usage examples
330
331* [[http://conkeror.org/Webjumps#Chickadee|Webjump for Conkeror]]
332
333==== AppArmor
334
335A [[https://raw.github.com/ursetto/chickadee/master/etc/usr.local.bin.chickadee-prod.sh|sample AppArmor profile]]
336is included in the egg source.  It assumes the use of a dedicated
337[[https://raw.github.com/ursetto/chickadee/master/etc/chickadee-prod.sh|startup script]]
338for chickadee, so that the restrictions only apply when calling chickadee
339via the script.  The sample also uses the {{config-nginx.scm}} built-in config
340file to run behind an nginx proxy.
341
342Generally, you just have to update {{CHICKEN}} in both files to reflect your
343installed Chicken, {{LOGDIR}} to specify your log directory, install the
344profile in {{/etc/apparmor.d}}, place the script in {{/usr/local/bin}}, and
345tweak the script and profile if necessary.  A detailed explanation of AppArmor is beyond the scope of this document. 
346
347=== git repository
348
349The official code is part of the Chicken SVN repository, but the
350author's git repository is available at [[http://3e8.org/pub/git/chickadee.git|3e8.org]]
351and also at [[https://github.com/ursetto/chickadee|github]].
352
353=== About this egg
354
355==== Author
356
357Jim Ursetto
358
359==== Version history
360
361; 0.11.2 : Add a second parameter to the last-modified header vector to comply with stricter header checking in intarweb 1.7.
362; 0.11.1 : Correct a distribution error
363; 0.11.0 : Decluttered appearance. Link and style definition identifiers and arguments that appear in verbatim plaintext, with new chicken-doc-html.
364; 0.10.3 : Permit arbitrary JS snippets; fall back to local jQuery in production config
365; 0.10.2 : Use local jquery for default config, improving offline usage
366; 0.10.1 : Limit match result set size to prevent runaway memory usage during regexp search. Also added example AppArmor profile.
367; 0.10.0 : Current version
368; 0.9.8 : Add chickadee wrapper.
369; 0.9.0 : Initial release.
370
371==== License
372
373Copyright (c) 2010, 2011, 2012 Jim Ursetto.  License: 3-clause BSD.
Note: See TracBrowser for help on using the repository browser.