Gborg GBSite Installation Instruction:
======================================

Required Software/Components:
-----------------------------
    Software     Version
    Component    (that we use)  Link/URL for more info
    ------------ -------------- -------------------------
    PostgreSQL   7.0.3          http://www.postgresql.org/
    Apache       1.3.12         http://www.apache.org/
    Php          4.0.2          http://www.php.net/
    CVS          1.10.7         http://www.cvshome.org/
    ViewCVS      0.6            http://www.lyra.org/viewcvs/
    Mailman      2.0 Beta 6     http://www.gnu.org/software/mailman/mailman.html


Installation Steps:
-------------------
STEP 1:
    Install the components that are listed above.

        A: Install PostgreSQL per the installation instruction. We did no
           specific configuration of the postgres install during the
           configure/make/make install process.

           NOTE: If you plan on running the database on a seperate system you
                 must still install postgres onto the system running apache/php
                 so php can use the library files provided by the PostgreSQL
                 install. In this case it is not neccessary to initdb the
                 database on the system with apache/php

           The rest of this document refers the the location that PostgreSQL
           was installed as $PGSQL.

           After you finish installing PostgreSQL it is recommended to that
           change the the pg_hba.conf file to require passwords from internet
           connections and then you setup a username/password for the account
           that will be accessing the database from the web. This will prevent
           developers from accidentally loggin into the database as the
           postgres superuser. For more Information see the PostgreSQL
           documentation.

        B: Install Apache per the apache installtion instructions.
           When we installed apache we used the following config options
           Note: The --enable-module=so is required to install php in the
                 manner we did

               $ configure --enable-module=so

           The rest of documentation assumes that $APACHE is the directory
           that apache was installed into (the default path is
           /usr/local/apache)

           NOTE: In order for the project scripts to work properly you must
                 have the MultiViews option turned on for your document root.

        C: Install Php per the Php Installation instructions.
           When we installed php we used the following config options.

               $ configure --without-mysql --with-pgsql \
                           --with-apxs=$APACHE/bin/apxs

           NOTE: After the compilation and installation of php we re-installed
                 php without the --with-apxs option so we had the php cgi
                 command available to run php scripts from the command
                 line/crontab

           The rest of this document assumes that $PHPINI is the php.ini file
           installed into /use/local/lib by default. NOTE: make sure you copy
           the php.ini-dist file from the php source directory to the proper
           location $PHPINI.

        D: Install CVS onto the same system that has apache/php. At this time
           we don't have a way of installing cvs onto a seperate system however
           using something like NFS this can be done, however, I'll leave this
           up to the installer to figure out as this strays far from the scope
           of this document.

           After installing CVS it is neccessary to setup all the components
           to work properly with the site. For more information on this please
           read the INSTALL.CVS file. the INSTALL.CVS file covers setting up
           the CVS Structure in more detail to work with the Gborg GBSite
           installation.

           The rest of the document refers to the root of the CVS installation
           structure as $CVS. Note that is not the actuall CVSROOT director as
           per a normall install but the top level directory of the CVS setup
           as described in the INSTALL.CVS file.

        E: Install viewcvs per the installation instructions and then follow
           the INSTALL.VIEWCVS guide to make the modifications to viewcvs

           The rest of this document refers the directory where viewcvs is
           installed as $VIEWCVS.

        F: Install mailman onto the server where apache/php is installed. It
           is possible to install it onto a seperate server using something
           like NFS, however, this is beyond the scope of this document. The
           Mailman documentation covers this a little. This is left up to the
           installer to figure out.

           After installing Mailman read the INSTALL.MAILMAN for the
           modifications to Mailman to get it to work with the Gborg GBSite
           installation.

           The rest of this document refers to the installation directory of
           Mailman as $MAILMAN.

Step 2:
    Install the Gborg GBSite program onto the server in a directory of your
    choosing (we used /usr/local/gbsite). The easiest way to do this is cd to
    /usr/local and extract the tarball. This will create the entire directory
    structure.

    Once you have the files extraced into the install directory, $GBSITE from
    this point on, you need to setup the database, configure Apache and Php to
    start using the setup.

    Setting up the database:
        To setup the database you need to first create a database. The default
        name is dotorg, you can use any name that PostgreSQL allows just
        remember to change the config.php file, located in $GBSITE/include, to
        match the name you choose.

        To create a database, we used dotorg as the database name, you issue
        the following command as the postgres superuser or another user that
        is capable of creating databases:

            $ createdb $DBNAME

        Before you continue you need to make sure that the pl/pgsql language
        is installed on the database you are planning on using. If you connect
        to the database and issue the following command:

            $ psql $DBNAME
            > select lanname from pg_language

        You should see something like this:

             lanname  
             ----------
              internal
              C
              sql
              plpgsql   <====== this is what you are looking for
             (4 rows)

        If you don't see an entry called "plpgsql" then you need to tell
        the database to add it to $DBNAME. To do this follow the commands
        below:

            $ createlang -L $PGSQL/lib plpgsql $DBNAME

        When you installed PostgreSQL you should have created a user to access
        the database. The username we used was greatbridge. If you use a
        different username/password please make sure you change the config.php
        file as with all the other options.

        Once the database is created you will want to create the schema for
        the database. The easiest way to do this is to run the following
        command from $GBSITE/sql directory:

            $ psql -U $DBUSER -f create_schema.sql $DBNAME

        IMPORTANT: For database user permissions you will want to create the
                   schema as the user that will be connecting to the database
                   for your site. If you would like you can create permissions
                   for each of the tables to allow additional access to other
                   users. Please see the PostgreSQL documentation on how to
                   do this. If you do that just remember that you must grant
                   the permissions explicitly for all users on the database.

        NOTE: $DBUSER is the name of the user you setup for apache/php to
              access the database.
        NOTE: $DBNAME is the name of the database you created

        Now that we have a schema in place we will need to create the data
        to run the site. To make this easier though we will do this later
        after we finish setting up apache/php. You may notice that a good deal
        of the data was inerted into the database during the schema creation
        process. This is because this data is not site dependendant.

    Configuring apache:
        A: Edit the $APACHE/conf/httpd.conf file and change the references to
           the $APACHE/htdocs to $GBSITE/htdocs. Once this is done you will
           need to restart the web server for the changes to take effect. You
           may want to wait until after you complete the rest of the
           installation as there are other changes that will require the
           restart of the server.

        B: For security reason you will also want to change the root htdocs
           directory from "AllowOverride None" to "AllowOverride AuthConfig"
           then you can create .htaccess files in the $GBSITE/htdocs/admin
           and the $GBSITE/htdocs/tools/admin directories to require passwords
           so unathorized users can't use the admin tools to modify your site.
           See the apache documentation for more information on this security
           feature.

    Configuring Php:
        A: In the $PHPINI file change the following options:
            auto_prepend_file = $GBSITE/include/pre.php
            include_path      = $GBSITE/include:.

    Configuring GBSite:
        The central config file for the Gborg GBSite project is located in
        $GBSITE/include/config.php.

        You should change the options in this file to match your setup. Most
        importantly are the database connection parameters.

Step 3:
    Now that we have all the components configured and working properly that 
    last thing we need to do is install the data to into the database to run
    the site.

    To create the site_info and page_info data to actually run the site we
    have provided a tool to install the data.

    To run the tool requires that when you installed php you installed the
    cgi version as well as the apache module and have the rest of the Gborg
    GBSite configured properly to connect to your database.

    $ cd $GBSITE/bin
    $ ./create_site

    Following the instructions will ask for the appropiate data so it can
    create the information for your site.

    If you have problems running the program you may want to check that the
    php executable is located in /usr/local/bin/php. If it is not you will
    want to change the first line in create_site to point to the correct
    location.

Step 4:
    Start Hosting :)


Additional Information:
-----------------------
You should now have a fully functional site waiting to to host and manage
project from the web. If you have any questions or need help you can post
a message to the gborg-general@greatbridge.org or gborg-dev@greatbridge.org
mailing lists. You can also check the archives also to see if the problem has
been discussed before. The archives can be located at:

    http://www.greatbridge.org/pipermail/gborg-dev or
    http://www.greatbridge.org/pipermail/gborg-general

We have several mailing lists you can check out. To get a list please visit:

    http://www.greatbridge.org/mailman/listinfo/gborg

In Addition if you would like to find the lastest releases/news, post bugs or
contribute to the Gborg project please visit:

    http://www.greatbridge.org/project/gborg/

Don't forget to check out http://www.greatbridge.org/ for other projects that
Great Bridge, LLC is hosting.

