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