file: INSTALL

- [bbsengine.org](http://bbsengine.org/ "official home page")
- install operating system distribution: fedora/debian/etc..  not tested on
  non-posix platforms (like windows).  politics: microsoft has no place in
  the server room.
- install webserver
  * apache httpd 2.4.x or above. tested with earlier versions. 
  * configure to taste, being sure to enable mod_php.
- install scripting language: php 5.4.x or above due to use of 'short array
  syntax'
  * strongly recomment using distro package rather than building manually.
  * see [Securing PHP: Step-by-Step](http://www.securityfocus.com/infocus/1706)
- install postgresql:
  * [postgresql](http://www.postgresql.org/) 9.2.13+
- install php pgsql module:
  * sudo yum install php-pgsql
- configure php.ini
  * has been tested and is known to work with register_globals off, which is
    a recommended thing to do.
  * safe_mode *might* work, but has not been tested-- if you test, and it
    works, please send me an email!
  * add the *full filesystem path* you installed the engine "lib" directory into
    (e.g. /usr/share/php5/bbsengine/) to the include_path.
  * restart apache2 if you have modified php.ini.
  * recommend changing error_level in php.ini to E_ALL for production
    *and* dev, as well as changing error_reporting to "syslog". throughout
    development *properly fix* errors and warnings, instead of squelching
    them.
  * add the smarty3 'libs' folder to your include_path
- note that there are a number of mod_rewrite rules in the shipped copy of
  htaccess which will need to be installed and operational for all of the
  modules to work.
- get pear working
  * [home page](http://pear.php.net/)
  * pear install HTML_Page2 HTML_QuickForm Pager MDB2
  * if you need to install pear in a hosting environment but you do not
    have shell access:
     - save output from http://go-pear.org/ as go-pear.php and upload it to
       your account via ftp. 
     - point your browser to it and follow the instructions
     - be sure to either remove go-pear.php after installation or protect the
       directory in which it is stored for security reasons
     - I have had a report that it was necesary to add "?>" to the end of
       the go-pear.org script (thanks asylum)
     - set include_path appopriately. you can do this in php.ini or with an
       .htaccess file using the "php_value" directive.
- note use of html_page2 version 0.6.4-beta. this version (or above) has the
  method "getBodyContent()" which is required by bbsengin3's "enhanced
  pages". to install, use 'sudo pear install html_page2-beta'

Installed packages, channel pear.php.net:
=========================================

    Package                 Version State
    Archive_Tar             1.4.0   stable
    Console_Getopt          1.4.1   stable
    HTML_Common             1.2.5   stable
    HTML_Common2            2.1.1   stable
    HTML_Page2              0.6.4   beta
    HTML_QuickForm2         2.0.2   stable
    HTML_QuickForm2_Captcha 0.1.2   alpha
    HTTP                    1.4.1   stable
    HTTP_Header             1.2.1   stable
    Image_Text              0.7.0   beta
    MDB2                    2.4.1   stable
    MDB2_Driver_pgsql       1.4.1   stable
    MIME_Type               1.4.0   stable
    PEAR                    1.10.1  stable
    Pager                   2.4.9   stable
    Text_CAPTCHA            1.0.2   stable
    Text_CAPTCHA_Numeral    1.3.2   stable
    Text_Password           1.1.1   stable
    XML_Util                1.3.0   stable

- if you are configuring a VM for the first time, run:
  % sudo pear upgrade-all
- get smarty3 working
  * instructions: http://www.smarty.net/quick_install
  * be sure to adjust the include_path in php.ini or .htaccess to include
    the directory into which the file Smarty.lib.php is installed.
- create postgres database: normally I use the domain name without dots, for
  example "zoidtechnologiescom". this will need to be done from an account
  that has permission to create users and databases. on a default rpm
  install, you should su to the "postgres" account to perform the following:

  % createdb zoidtechnologiescom

- determine which unix user the distro uses to run apache2. sometimes this
  is "apache" other times "www-data", etc.
- install postgresql-contrib which has the "ltree" module so that the sigs
  will work.
- create language "pl/pythonu" so the teosurl() function will work (sigs)
- create postgres user

  % createuser --no-createdb --no-createuser apache

- if the machine running postgres is different from the one running httpd,
  you will need to make sure that the postgres service is configured to
  accept TCP/IP connections and that there isn't a firewall in the way. this
  is done via the postgresql.conf file.
- NOTE OF CAUTION: you *will* need to modify the Makefiles to install to an
  appropriate path. change the PROD variable towards the top of the root
  Makefile.
- 2nd NOTE OF CAUTION: you will need to modify the sql files so that it
  correctly replaces 'jam' and 'apache' if you are not using those
  usernames. in some cases 'apache' is replaced with 'www-data' or 'www', and
  obviously unless you are logged in as 'jam' you will need to change that
  too. you need to make this change before running the 'psql -f all.sql
  zoidtechnologiescom' command noted below. you can set up a user map within
  pg such that 'apache' maps to whatever uid your webserver actually uses
  that way you will only need to change the 'jam' reference in the schema
  file.
- create database schema
  * cd to "db" directory
  * psql -f all.sql zoidtechnologiescom
- previously you should have defined the uid (username) and password in
  common_db.php that is used to connect to the postgresql database. below is
  a simple script that will grant privs for your uid to each table:

   $ grep grant *.sql | awk '{print $4}' | awk '{print "grant select, insert, update, delete on " $1 " to your_uid;"}'

  >> thanks to lgm for the bash snippet above <<
   
- edit config.php so it has the right SYSTEMDSN value. you can read about
  that on the
  [http://pear.php.net/manual/en/package.database.mdb2.intro-dsn.php](pear
  mdb2 dsn) page.

- create member:
  http://[hostname]/member.php?mode=newuser

- modify smarty templates and css files to suit tastes

- install and/or modify the ".htaccess" file shipped with the release as
  needed.

- be certain that, if running "pear install", the directory permissions are
  correct. in my setup, I needed to run 'chmod a+rx' to get things to work
  properly.

- alter config.php so it has the proper VHOSTDIR and SYSTEMDSN defined.

- if you have suggestions for improvement (and especially patches) to either
  the code or the documentation, if you need a custom module, or if you need
  assistance with setup and administration of a website using this software,
  please email: jam at zoid technologies dot com