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