0.14_08 commit
[bse.git] / INSTALL.pod
1 =head1 NAME
2
3    BSE installation guide.
4
5
6 =head1 SYSTEM REQUIREMENTS
7
8 =over 4
9
10 =item *
11
12 perl 5.005_03 or later
13
14 =item *
15
16 mysql 3.22. or later
17
18 =item *
19
20 GnuPG or PGP 5 or 6
21
22 =item *
23
24 a web host:
25
26 =over 4
27
28 =item *
29
30 with telnet or ssh access
31
32 =item *
33
34 that runs your CGI scripts as your user
35
36 =item *
37
38 that runs your CGI scripts with the current working directory
39 set to the directory that contains the CGI script.
40
41 =back
42
43 =back
44
45 You will need at least the following Perl modules installed:
46
47 =over 4
48
49 =item *
50
51 DBI
52
53 =item *
54
55 DBD::mysql
56
57 =item *
58
59 Digest::MD5
60
61 =item *
62
63 Apache::Session
64
65 =item *
66
67 Storable (and this requires Log::Agent sometimes)
68
69 =item *
70
71 HTML::Parser
72
73 =item *
74
75 URI::Escape
76
77 =item *
78
79 HTML::Entities
80
81 =back
82
83 and their dependants.  If you use the CPAN shell to install these then
84 the dependants will be installed automatically.
85
86 All other modules are either supplied or standard with perl.
87
88 I assume you know how to use a text editor, and have a basic knowledge
89 of how directories work, and know enough perl to be able to edit
90 constants.
91
92 =head1 PLANNING
93
94 You need to know:
95
96 =over 4
97
98 =item *
99
100 the layout of directories on your web host: where CGI programs go
101 (cgi-bin), where's the root of the document tree (htdocs), and where
102 can you safely keep static data (datapath).  The names in parentheses
103 () will be used in this documentation.
104
105 =item *
106
107 how you want your site to look, presumably as one or more HTML files
108 and associated style sheets.
109
110 =item *
111
112 order processing information: the email address and public key of
113 the user who will be receiving the order emails.  The email address
114 and private key of the sender of the order emails (though this can be
115 generated during installation.
116
117 =back
118
119 =head1 EXTRACT FILES
120
121 Telnet or ssh to the web host.
122
123 Extract the archive into a working directory:
124
125   mkdir work
126   cd work
127   tar xzf workpath/bse-0.04.tar.gz
128
129 The directories in the archive are:
130
131   bse/                     Base directory
132   bse/schema               Database schema definitions (and some test data)
133   bse/site                 Laid out site
134   bse/site/htdocs          Document root
135   bse/site/cgi-bin         CGI programs
136   bse/site/templates       Sample page templates
137   bse/site/data            Static site data (currently just the stopwords list)
138   bse/site/docs            Documentation
139   bse/site/util            Utilities (currently just initial.pl)
140
141 If you are running your own host, or have sufficient control over
142 Apache, you may want to extract the archive in it's final directory
143 and simply create a new <VirtualHost..> that uses the extracted
144 directories.  If so, skip Copy Files.
145
146
147 =head1 COPY FILES
148
149 Replacing the names as decribed in L<PLANNING>
150
151   # the base documents
152   mkdir htdocs/admin
153   cp -R workpath/site/htdocs htdocs/
154   # page templates (you will need to modify these) and static data
155   mkdir datadir/templates
156   cp -R workpath/site/templates datadir/templates/
157   cp -R workpath/site/data datadir/
158   # cgi
159   cp -R workpath/site/cgi-bin cgi-bin/
160
161
162 =head1 CONFIGURATION
163
164 Most configuration information is kept in Constants.pm, which is in
165 the cgi-bin/modules directory:
166
167   vi cgi-bin/modules/Constants.pm
168
169 =head2 Database
170
171 $DB should be the name of your mysql database.
172
173 $UN and $PW should be your mysql login name and password.
174
175 =head2 Directory structure
176
177 If your directory structure matches that of the archive, this is
178 simple, set $BASEDIR to point to the site directory.  The other
179 variables are set based on that layout.
180
181 Otherwise, set:
182
183 =over 4
184
185 =item $TMPLDIR
186
187 to the directory you are keeping document templates in,
188 'datapath/templates/' if you followed L<COPY FILES>
189
190 =item $CONTENTBASE
191
192 to the directory you are keeping the site document files in, 'htdocs/'
193 if you followed L<COPY FILES>.
194
195 =item $IMAGEDIR
196
197 to the directory that image files are kept in.  This should be left as
198 $CONTENTBASE . 'images/'
199
200 =item $DATADIR
201
202 to the directory containing F<stopwords.txt>
203
204 =back
205
206 B<Warning:> these paths I<must> be kept as absolute directories.  They
207 must the directories as seen by the running CGI scripts.
208
209
210 =head2 Site name
211
212 You should set $URLBASE and $SECURLBASE to the URLs used to access
213 your site in normal and SSL (https).  If you currently don't have secure access setup, you can use the same non-secure URL for both.
214
215 B<Warning:> You I<must> set the $SECURLBASE to a secure URL and
216 regenerate the site before accepting orders on the site.
217
218 =head2 Level defaults
219
220 This is probably the most complex item to configure.
221
222 The %LEVEL_DEFAULTS hash describes how your site will look from the
223 administration interface.  It has little effect on how the site looks
224 from a user's perspective, except of course, that it sets defaults for
225 some items.
226
227 Each level of your site needs an entry in the hash, with the top level
228 being 0 to indicate the whole site.  This top-level should only have
229 the C<display> keyword defined.
230
231 Each level except for level 0 should have the following keywords defined:
232
233 =over 4
234
235 =item *
236
237 C<display> defines how the articles at this level is described when
238 adding new articles.
239
240 =item *
241
242 C<template> is the default template name used for that level.  It
243 should exist in the levels directory under your template directory.
244
245 =item *
246
247 C<threshold> is the default threshold used when a new article is
248 created at that level.  Thresholds are used to control whether child
249 article are rendered inline, or as summaries.
250
251 =back
252
253 =head2 Link Titles
254
255 If you set $LINK_TITLES to non-zero, then the links created for the
256 C<article link> and C<url article> tags will include the title as a
257 translated suffix.  This allows some search engines to index on the
258 URL as well as the content of the document. Without this suffix the
259 url contains no useful indexable information.
260
261 For this to work under Apache you will need the following in a
262 .htaccess file in the htdocs/a directory:
263
264    RewriteEngine On
265    RewriteRule ^([0-9]+\.html)/[0-9a-zA-Z_]*$ ./$1 [T=text/html]
266
267 =head2 Search options
268
269 In geneal the search engine will generate a search index for all
270 listed articles, and exclude unlisted articles.
271
272 You have some control over the indexing.  Set @SEARCH_INCLUDE to the
273 ids of sections that should be indexed, even if not listed.  Set
274 @SEARCH_EXCLUDE to the ids of sections that should not be indexed.
275
276 @SEARCH_EXCLUDE overrides @SEARCH_INCLUDE.
277
278 Set $SEARCH_LEVEL to the lowest-level (highest number) of the articles
279 to be indexed.  Lower level articles will still be indexed, but
280 searches for them will find their parent article (or I<their> parent
281 article, if it still isn't a low enough level.)
282
283 $SEARCH_ALL is used as the name of the entry in the drop-down list of
284 sections generated by the <:list:> tag on the search template.
285
286 =head2 Deletion control
287
288 Some articles are critical to the operation of your site.  If the
289 article's id is in @NO_DELETE it cannot be deleted.
290
291 =head2 The Shop
292
293 This is probably the second hardest item to configure.
294
295 It isn't necessary to configure this section until you need to use the
296 shop.
297
298 $SHOP_CRYPTO should be set to the supplied class that uses your
299 installed encryption software.  Note that currently only Squirrel::GPG
300 has been tested in production.  (Patches welcome on the other modules.)
301
302 $SHOP_SIGNING_ID should be the user id of the key to use for signing
303 orders.
304
305 $SHOP_GPG, $SHOP_PGPE and $SHOP_PGP are the locations of the specified
306 executables, for GunPG, PGP5 and PGP6 respectively.  They only need to
307 be set if the executable isn't in the PATH when the shop.pl runs.
308
309 $SHOP_SENDMAIL needs to be set to the name of sendmail or a compatible
310 program.
311
312 $SHOP_FROM will be used as the sender of the order emails.
313
314 Processed, encrypted orders will be $SHOP_TO_NAME and $SHOP_TO_EMAIL.
315 There must be a public key in the keyring, which has been signed by
316 the private key $SHOP_SIGNING_ID (or whatever your default private
317 signing key is.)
318
319 You can set $SHOP_EMAIL_ORDER to 0 to prevent the order being emailed
320 as above.  A confirmation email is still sent to the person who made
321 the order.  This is only really for testing, since only the encrypted
322 email contains the credit card number and expiry date.
323
324 =head2 Maintenance Tools
325
326 $DATA_EMAIL is the email address of a person that the 
327 I<Dump database to email> page will send the MySQL database dump to.
328
329 $MYSQLDUMP is the location of the MySQL C<mysqldump> tool.  If this
330 isn't in the PATH you will need to add this here.
331
332 =head1 DATABASE SETUP
333
334 =head2 Schema load
335
336 You need to install the database schema.  Presumably you have already
337 created a user and database for the new site (or your host has.)
338
339 To install the schema and the base data:
340
341   mysql -u youruserl -p yourdatabase <bse.sql
342
343 You will be asked for your password.
344
345 =head2 Base data load
346
347 Change directory to the util directory in your workpath.
348
349 If you moved the files you will need to edit initial.pl to change the line:
350
351   use lib '../cgi-bin/modules';
352
353 so that it will specify the correct modules directory.
354
355 You may want to simply set PERL5LIB to your new modules director instead:
356
357   PERL5LIB=cgi-bin/modules
358   export PERL5LIB
359
360 Once you've done that, you can run initial.pl:
361
362   perl initial.pl
363
364 B<Warning:> Do not run this after your site is up and has articles you
365 want to keep.  This will delete all existing articles from your site.
366
367
368 =head1 TEMPLATE SETUP
369
370 See the site/docs/templates.pod (or .html).
371
372
373 =head1 SECURITY
374
375 Since your web host runs your CGI programs as you, you can make
376 Constants.pm readble only by you.
377
378 You will need to protect the htdocs/admin and cgi-bin/admin
379 directories with .htaccess files.  For example:
380
381   AuthType Basic
382   AuthName "Administrator Only"
383   AuthUserFile "somepath/users.dat"
384   require valid-user
385
386 The AuthUserFile needs to point to a file accessible by the user that
387 the web server runs as.  So it won't work if you use your home
388 directory.