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