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