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