INSTALL.pod

   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.