=============================================================================
Copyright 2003 INCOGEN, Inc.

This program is distributed under the terms of the BSD License (see the
license.txt file that was distributed along with this file for details).

INCOGEN, Inc. asks that credit be given when this code is used, and if
bug fixes or other beneficial changes are made to the code, that unified
diff patches (diff -uNr original-tree new-tree) be submitted. Please
submit patches to opensource@incogen.com.

BugPort 1.X Install Documentation
Please consult the system documentation for more general information

Jason Miller (2003/12/03): 1.002 - added Notes section
Jason Miller (2003/09/03): 1.001
=============================================================================


Prerequisites
--------------------
BugPort Requires:
   - PHP ADOdb Libraries - http://php.weblogs.com/adodb
   - MySQL - mysql.com (or Oracle 8i+) -
     MySQL may need to be 4.0 or higher
   - Apache (or another PHP-capable web server) - www.apache.org
   - PHP 4.3+ - www.php.net - CLI, the Command line Interface for PHP,
     is installed with PHP 4.3+ by default and is optionally useful
     in BugPort for stats generation; CLI may be required in the future
     for an install script


Notes
--------------------
Thanks to Mr. Josh Glover, we now have a scripted installer for Gentoo linux.
Please see the install-gentoo-unsupported directory for more info.


Installation Steps
--------------------
   1)    Install the web server, database server, and PHP per their normal methods.
         INCOGEN's setup was installed by setting up MySQL first such that a MySQL
         user can be created and that user is able to make tables and data rows.
         Then apache was installed with mod_so enabled.  Then PHP was installed in
         DSO form making sure to use the --with-mysql flag during its "./configure" step.
         
         If you are using PHP 5, please see the BugPort FAQ to learn important info.

   2)    Test that each is working and that PHP can "talk" to your database server.

   3)    create a directory in your HTML document root to hold bugport
         NOTE: The bugport tar file will create a "bugport" directory for
         you so you may not need to create a directory if "bugport" is OK.

   4)    Untar BugPort
         Untar the BugPort distribution into the chosen place in your HTDOCS directory

   5)    Create database schema
         Create a MySQL user which will own all bugport database items (the username
         "bugport" is assumed for this document):

	 mysql -u root -p
	 Enter password: *****
	 CREATE DATABASE bugport;
	 GRANT ALL ON bugport.* TO bugport@localhost IDENTIFIED BY 'password';

	 If you wish, you may name the database something other than
	 "bugport" (note that if you choose to do this, you must run
	 'sed -i -e 's/USE bugport/USE dbname/' create_tables.sql', where
	 'dbname' is the database name that you have chosen). Also, you
	 probably want to change the 'password' in "IDENTIFIED BY 'password'"
	 to something a bit stronger. Execute the included BugPort SQL file
	 as that user in order to create the schema and some default database
         entries:

	 mysql -u bugport -p <create_tables.sql
	 Enter password: *****

	 If you have a user table from some other database schema which you
         would like to re-use, you may do so, but you will be required to edit the
         bugport/php_classes/Shared/User.php file to reflect the structure of that user
         database table.

         If you are using MySQL it is also recommended that you create another database
         for your "bugport" MySQL user that will store database ID counters (sequences).
         This is nice because it prevents your main bugport schema from becoming polluted
         with all of the sequence tables that are needed. If you wish to do
	 this, run:

	 mysql -u root -p
	 Enter password: *****
	 CREATE DATABASE bugport_seq;
	 GRANT ALL ON bugport_seq.* TO bugport@localhost IDENTIFIED BY 'password';


   6)    Setup the conf file
         The BugPort configuration file is: bugport/conf/config.php
           
         - Ensure that the $attachmentDirectory variable is set to a directory that exists
           and is writable by your web server user.  This directory MUST be outside of your
           web server's document root directory.

         - Setup the 5 database related variables to match your database configuration
           (server name, server port, user login, and type - note "type" is not yet in use )

         - Configure the three schema variables.  These may all be identical.  These should
           match the schema names (for oracle they typically are the same as the oracle user
           name, for MySQL they are the "database" name).  BugPort has multiple schemas
           in order to support shared tables, such as user, which may be stored separately
           from the other bugport tables.

           Of special note is the $sequenceSchema variable.  This should hold the name
           of the schema/database you defined to hold sequences in step 6 above.

         - Setup the other variables as needed.

   7)    Setup users/projects/versions/etc. tables as needed.
         There are a few tables that need "manual" management, at least until
         web based tools are created to edit these tables.  These tables are:

         - iuser
         - project
         - user_project_usertype
         - version
         - category
         - instance

         And in some case changes may be desired to these table's entries:

         - commenttype
         - frequency
         - platform
         - priority
         - severity
         - statcolumn
         - type

         Example rows are provided for all of the above tables and should be referred
         to when editing/creating rows.  Also, note that all primary key columns
         for tables are auto_increment in MySQL (they will be named "<TABLENAME>_id")

   8)    Setup the web server authentication for users
         BugPort uses the web server's authentication environment variables for login
         purposes.  In the case of apache, this means that apache needs to require
         your users to login when they attempt  to view a BugPort php file. This
         is typically done using a .htaccess file and a related "htpasswd" generated
         password database file.

         In order to tell apache to use a .htaccess file for authentication details
         you would add an entry in httpd.conf (maybe apache.conf in some installs)
         similar to this:

            <Directory /usr/local/apache/htdocs/bugport>
            AllowOverride AuthConfig
            order allow,deny
            allow from all
            </Directory>

         Where /usr/local/apache/htdocs/bugport is the directory that contains
         BugPort's "php_classes" directory.

         The next step is to create a file named .htaccess in the bugport directory.
         The .htaccess file should look similar to:

            AuthName "BugPort Access"
            AuthType Basic
            AuthUserFile /usr/local/apache/bugport.users
            require valid-user

         Once that file has been created you will need to create the password database
         file it refers to (/usr/local/apache/bugport.users) like this:

            htpasswd -c /usr/local/apache/bugport.users a_bugport_username

         Run that command for each user that will access BugPort.  The command will
         ask for a password for each user as you add them.  Use the -c flag only
         for the first user, to tell htpasswd to create the initial password file 
         for you.

         Once those steps are complete (and apache has been restarted) you should
         get a login prompt when you attempt to access your web server's bugport
         directory.  If not, please consult your web server's docs for more help.

    9)   Optional - cron the Statistics Generation script
         If you would like to use the "History" page, you will need to setup a daily cron job to save
         "count" information.  An example cron line for this to run every day at 11:54AM would be:

         54 11 * * * /usr/local/bin/php /apache/htdocs/bugport/system/bin/executor.php Bugs.SaveCountsExecutable 2>/dev/null 1>/dev/null

   10)   Optional - Changing the max upload size to allow for larger attachments
            The directions below are for allowing attachments up to 24MB.

      Modifications to php.ini
         Change max_upload_size to 24M
         Change post_max_size to 24M
         Change memory_limit to 32M (24M + 8M)

      Modifications to php.conf (Apache 2 only)
         Change LimitRequestBody to 25165824 (24MB in bytes)
         For more information, see http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=76976

      Restart Apache