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

Last change on this file since 26890 was 26890, checked in by Jim Ursetto, 9 years ago

wiki/chickadee: Add information on using chickadee with AppArmor?.

File size: 11.8 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-js-files</parameter>
180
181List of URIs to Javascript files for Chickadee.
182
183Defaults to {{(list (uri-reference "/cdoc/chickadee.js"))}}.
184
185<parameter>maximum-match-results</parameter>
186
187Maximum number of match results to return for a match query.
188Default: 250.
189
190<parameter>maximum-match-signatures</parameter>
191
192Maximum number of signatures to return for a match query, up to
193{{maximum-match-results}}.  Default: 100.  Obtaining signatures
194may increase disk load in the current implementation.
195
196<parameter>incremental-search</parameter>
197
198Number of incremental search results to display; 0 or #f to disable.
199Defaults to 0.
200
201<parameter>incremental-search-delay</parameter>
202
203Time in milliseconds to delay incremental search requests.  Defaults
204to 50, which seems reasonable for WAN or LAN use.  20 will give even
205better interactive response on a fast network and CPU.
206
207<parameter>cache-nodes-for</parameter>
208
209Time in milliseconds to inform browsers that node pages should be
210cached for.  Defaults to 300.  If #f, no caching is done.
211
212<parameter>cache-static-content-for</parameter>
213
214Time in milliseconds to inform browsers that static content such as
215CSS and Javascript should be cached for.
216
217<parameter>last-modified</parameter>
218
219Base time used for node last-modified calculations, in seconds.
220
221Chickadee uses the overall repository modification time (updated
222whenever a reindex is done) to determine when a node was last
223modified.  Browsers with a vaild cached copy will receive a "304 Not
224Modified" response.
225
226However, the value of {{last-modified}} will also be considered; the
227modification time is taken as the maximum of the two values.  This is
228done because changes to program logic may change the rendering of the
229page even when the repository has not changed.  For example, set
230{{last-modified}} to {{(current-seconds)}} to simply invalidate all
231pages when the server is restarted.
232
233Defaults to 0.
234
235<parameter>ajax-log</parameter>
236
237AJAX access log pathname.  Separate from the usual {{access-log}}
238because this is potentially disk and CPU intensive.  Set to {{#f}} to
239disable.
240
241=== Debugging
242
243<parameter>%chickadee:debug-incremental-search-latency</parameter>
244
245Simulate network latency of N milliseconds for incremental search.
246Allows you to test estimated interactive response across the Internet
247on a local system.
248
249=== Examples
250
251==== Configuration examples
252
253An example local configuration file for the {{chickadee}} wrapper.  If
254you add {{(chickadee-start-server)}} to the end, you can run this file as
255a standalone program.
256
257Also see [[https://raw.github.com/ursetto/chickadee/master/chickadee-config.scm|config.scm]], which
258is installed as the default config file, and is more up-to-date.
259
260<enscript lang="scheme">
261(use chickadee spiffy uri-common)
262(define uri uri-reference)
263(root-path "root")
264(debug-log (current-error-port))
265(server-port 8080)
266(access-log "logs/access.log")
267(max-connections 8)
268(ajax-log "/tmp/ajax.log")
269(cdoc-uri (uri "/cdoc"))
270(chickadee-uri (uri "/chickadee"))
271(incremental-search-uri (uri "/cdoc/ajax/prefix"))
272(chickadee-css-files (list (uri "/cdoc/chickadee.css")))
273(chickadee-js-files
274 (list (uri "http://code.jquery.com/jquery-1.4.2.min.js")
275       (uri "/cdoc/jquery.metadata.2.1.min.js")
276       (uri "/cdoc/chickadee-jquery.js")))
277(maximum-match-results 250)
278(maximum-match-signatures 100)
279(incremental-search 15)
280(incremental-search-delay 50)
281(cache-nodes-for 300)
282(cache-static-content-for 1800)
283(last-modified (current-seconds))
284</enscript>
285
286Configuration of the [[http://api.call-cc.org/doc/|primary chickadee server]] behind an nginx caching proxy.
287Also see [[https://raw.github.com/ursetto/chickadee/master/chickadee-config-nginx.scm|config-nginx.scm]], which
288is installed alongside the egg, and is more up-to-date.
289
290<enscript lang="scheme">
291(use chickadee spiffy uri-common)
292(define uri uri-reference)
293(root-path "root")
294(debug-log (current-error-port))
295(access-log "logs/access.log")
296(error-log "logs/error.log")
297(server-port 8383)
298(max-connections 8)
299(ajax-log #f)
300(cdoc-uri (uri "/cdoc"))
301(chickadee-uri (uri "/chickadee"))
302(incremental-search-uri (uri "/cdoc/ajax/prefix"))
303(chickadee-css-files (list (uri "/cdoc/chickadee.css?5")))
304(chickadee-js-files
305 (list (uri "http://code.jquery.com/jquery-1.4.2.min.js")
306       (uri "/cdoc/jquery.metadata.2.1.min.js")
307       (uri "/cdoc/chickadee-jquery.js?2")))
308(maximum-match-results 250)
309(maximum-match-signatures 100)
310(incremental-search 15)
311(incremental-search-delay 50)
312(cache-nodes-for 600)
313(cache-static-content-for 1800)
314(last-modified (current-seconds))
315(chickadee-start-server)
316</enscript>
317
318==== Usage examples
319
320* [[http://conkeror.org/Webjumps#Chickadee|Webjump for Conkeror]]
321
322==== AppArmor
323
324A [[https://raw.github.com/ursetto/chickadee/master/etc/usr.local.bin.chickadee-prod.sh|sample AppArmor profile]]
325is included in the egg source.  It assumes the use of a dedicated
326[[https://raw.github.com/ursetto/chickadee/master/etc/chickadee-prod.sh|startup script]]
327for chickadee, so that the restrictions only apply when calling chickadee
328via the script.  The sample also uses the {{config-nginx.scm}} built-in config
329file to run behind an nginx proxy.
330
331Generally, you just have to update {{CHICKEN}} in both files to reflect your
332installed Chicken, {{LOGDIR}} to specify your log directory, install the
333profile in {{/etc/apparmor.d}}, place the script in {{/usr/local/bin}}, and
334tweak the script and profile if necessary.  A detailed explanation of AppArmor is beyond the scope of this document. 
335
336=== git repository
337
338The official code is part of the Chicken SVN repository, but the
339author's git repository is available at [[http://3e8.org/pub/git/chickadee.git|3e8.org]]
340and also at [[https://github.com/ursetto/chickadee|github]].
341
342=== About this egg
343
344==== Author
345
346Jim Ursetto
347
348==== Version history
349
350; 0.10.0 : Current version
351; 0.9.8 : Add chickadee wrapper.
352; 0.9.0 : Initial release.
353
354==== License
355
356Copyright (c) 2010, 2011, 2012 Jim Ursetto.  License: 3-clause BSD.
Note: See TracBrowser for help on using the repository browser.