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