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