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