Initial revision
[bse.git] / INSTALL.pod
CommitLineData
41b9d8ec
TC
1=head1 NAME
2
3 BSE installation guide.
4
5
6=head1 SYSTEM REQUIREMENTS
7
8=over 4
9
10=item *
11
12perl 5.005_03 or later
13
14=item *
15
16mysql 3.22. or later
17
18=item *
19
20GnuPG or PGP 5 or 6
21
22=item *
23
24a web host:
25
26=over 4
27
28=item *
29
30with telnet or ssh access
31
32=item *
33
34that runs your CGI scripts as your user
35
36=item *
37
38that runs your CGI scripts with the current working directory
39set to the directory that contains the CGI script.
40
41=back
42
43=back
44
45You will need at least the following Perl modules installed:
46
47=over 4
48
49=item *
50
51DBI
52
53=item *
54
55DBD::mysql
56
57=item *
58
59Digest::MD5
60
61=item *
62
63Apache::Session
64
65=back
66
67and their dependants. If you use the CPAN shell to install these then
68the dependants will be installed automatically.
69
70All other modules are either supplied or standard with perl.
71
72I assume you know how to use a text editor, and have a basic knowledge
73of how directories work, and know enough perl to be able to edit
74constants.
75
76=head1 PLANNING
77
78You need to know:
79
80=over 4
81
82=item *
83
84the 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
86can you safely keep static data (datapath). The names in parentheses
87() will be used in this documentation.
88
89=item *
90
91how you want your site to look, presumably as one or more HTML files
92and associated style sheets.
93
94=item *
95
96order processing information: the email address and public key of
97the user who will be receiving the order emails. The email address
98and private key of the sender of the order emails (though this can be
99generated during installation.
100
101=back
102
103=head1 EXTRACT FILES
104
105Telnet or ssh to the web host.
106
107Extract the archive into a working directory:
108
109 mkdir work
110 cd work
111 tar xzf workpath/bse-0.04.tar.gz
112
113The 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
125If you are running your own host, or have sufficient control over
126Apache, you may want to extract the archive in it's final directory
127and simply create a new <VirtualHost..> that uses the extracted
128directories. If so, skip Copy Files.
129
130
131=head1 COPY FILES
132
133Replacing 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
148Most configuration information is kept in Constants.pm, which is in
149the 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
161If your directory structure matches that of the archive, this is
162simple, set $BASEDIR to point to the site directory. The other
163variables are set based on that layout.
164
165Otherwise, set:
166
167=over 4
168
169=item $TMPLDIR
170
171to the directory you are keeping document templates in,
172'datapath/templates/' if you followed L<COPY FILES>
173
174=item $CONTENTBASE
175
176to the directory you are keeping the site document files in, 'htdocs/'
177if you followed L<COPY FILES>.
178
179=item $IMAGEDIR
180
181to the directory that image files are kept in. This should be left as
182$CONTENTBASE . 'images/'
183
184=item $DATADIR
185
186to the directory containing F<stopwords.txt>
187
188=back
189
190B<Warning:> these paths I<must> be kept as absolute directories. They
191must the directories as seen by the running CGI scripts.
192
193
194=head2 Site name
195
196You should set $URLBASE and $SECURLBASE to the URLs used to access
197your 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
199B<Warning:> You I<must> set the $SECURLBASE to a secure URL and
200regenerate the site before accepting orders on the site.
201
202=head2 Level defaults
203
204This is probably the most complex item to configure.
205
206The %LEVEL_DEFAULTS hash describes how your site will look from the
207administration interface. It has little effect on how the site looks
208from a user's perspective, except of course, that it sets defaults for
209some items.
210
211Each level of your site needs an entry in the hash, with the top level
212being 0 to indicate the whole site. This top-level should only have
213the C<display> keyword defined.
214
215Each level except for level 0 should have the following keywords defined:
216
217=over 4
218
219=item *
220
221C<display> defines how the articles at this level is described when
222adding new articles.
223
224=item *
225
226C<template> is the default template name used for that level. It
227should exist in the levels directory under your template directory.
228
229=item *
230
231C<threshold> is the default threshold used when a new article is
232created at that level. Thresholds are used to control whether child
233article are rendered inline, or as summaries.
234
235=back
236
237=head2 Link Titles
238
239If you set $LINK_TITLES to non-zero, then the links created for the
240C<article link> and C<url article> tags will include the title as a
241translated suffix. This allows some search engines to index on the
242URL as well as the content of the document. Without this suffix the
243url contains no useful indexable information.
244
245For 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
253In geneal the search engine will generate a search index for all
254listed articles, and exclude unlisted articles.
255
256You have some control over the indexing. Set @SEARCH_INCLUDE to the
257ids 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
262Set $SEARCH_LEVEL to the lowest-level (highest number) of the articles
263to be indexed. Lower level articles will still be indexed, but
264searches for them will find their parent article (or I<their> parent
265article, 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
268sections generated by the <:list:> tag on the search template.
269
270=head2 Deletion control
271
272Some articles are critical to the operation of your site. If the
273article's id is in @NO_DELETE it cannot be deleted.
274
275=head2 The Shop
276
277This is probably the second hardest item to configure.
278
279It isn't necessary to configure this section until you need to use the
280shop.
281
282$SHOP_CRYPTO should be set to the supplied class that uses your
283installed encryption software. Note that currently only Squirrel::GPG
284has 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
287orders.
288
289$SHOP_GPG, $SHOP_PGPE and $SHOP_PGP are the locations of the specified
290executables, for GunPG, PGP5 and PGP6 respectively. They only need to
291be 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
294program.
295
296$SHOP_FROM will be used as the sender of the order emails.
297
298Processed, encrypted orders will be $SHOP_TO_NAME and $SHOP_TO_EMAIL.
299There must be a public key in the keyring, which has been signed by
300the private key $SHOP_SIGNING_ID (or whatever your default private
301signing key is.)
302
303You can set $SHOP_EMAIL_ORDER to 0 to prevent the order being emailed
304as above. A confirmation email is still sent to the person who made
305the order. This is only really for testing, since only the encrypted
306email 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
311I<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
314isn't in the PATH you will need to add this here.
315
316=head1 DATABASE SETUP
317
318=head2 Schema load
319
320You need to install the database schema. Presumably you have already
321created a user and database for the new site (or your host has.)
322
323To install the schema and the base data:
324
325 mysql -u youruserl -p yourdatabase <bse.sql
326
327You will be asked for your password.
328
329=head2 Base data load
330
331Change directory to the util directory in your workpath.
332
333If you moved the files you will need to edit initial.pl to change the line:
334
335 use lib '../cgi-bin/modules';
336
337so that it will specify the correct modules directory.
338
339You may want to simply set PERL5LIB to your new modules director instead:
340
341 PERL5LIB=cgi-bin/modules
342 export PERL5LIB
343
344Once you've done that, you can run initial.pl:
345
346 perl initial.pl
347
348B<Warning:> Do not run this after your site is up and has articles you
349want to keep. This will delete all existing articles from your site.
350
351
352=head1 TEMPLATE SETUP
353
354See the site/docs/templates.pod (or .html).
355
356
357=head1 SECURITY
358
359Since your web host runs your CGI programs as you, you can make
360Constants.pm readble only by you.
361
362You will need to protect the htdocs/admin and cgi-bin/admin
363directories with .htaccess files. For example:
364
365 AuthType Basic
366 AuthName "Administrator Only"
367 AuthUserFile "somepath/users.dat"
368 require valid-user
369
370The AuthUserFile needs to point to a file accessible by the user that
371the web server runs as. So it won't work if you use your home
372directory.