
  WebCollab Setup
  ===============

      WEBCOLLAB SETUP PROGRAM
      -----------------------
      
Note: To enable the setup program to write to your configuration file,
the file '/config/config.php' _must_ be made writable by the web server.
If the file is not writable, then only the databases can be created.


        1. First Time Setup
        -------------------
        
   1. For UNIX and other *nix OS:
          * Navigate to your main WebCollab directory.
          * Make [webcollab_directory]/config/config.php file writable
            by everyone.

        #chmod 666 config.php

   2. Point your web browser at
      http://your_site/webcollab_directory/setup.php (Replace
      'your_site' and 'webcollab_directory' with the relevant values for
      your site.
   3. Follow the on-screen instructions to setup WebCollab.
   4. For UNIX and other *nix OS:
          * Make config.php protected again.

      #chmod 664 config.php


        2. Getting Online:
        ------------------
        
    * Point your browser to http://your_site/webcollab_path/index.php.
      If all is well, you should see a login page.
      Username: *admin*
      Password: *admin123*


        3. Change Admin Password and Email Address
        ------------------------------------------
        
    * Click on the 'Edit user details' button and change the admin
      password (and email address) as soon as possible.


        4. Admin Config Setup
        ---------------------

   1. From the main screen, click on the 'Admin config' link in the menu
      boxes, left hand side of page. Depending on your screen
      resolution, you may have to scroll down to see it.
   2. Enter the requisite email addresses for your site into the boxes.
      Click on the descriptions for more help.
   3. The default check box settings in the lower part of the form can
      be left for now.
   4. Press the update button.


        5. Altering Setup (if required)
        -------------------------------

   1. For UNIX: Make [webcollab_directory]/config/config.php writable by
      everyone.
   2. Edit config.php, and change $WEB_CONFIG = "Y" (it should have
      defaulted to "N").
   3. Point your web browser at
      http://your_site/webcollab_directory/setup/index.php
   4. Enter an admin login and password
   5. Follow the on-screen instructions to setup WebCollab.
   6. For UNIX: Make config.php protected again.

      Note: The config.php can also be edited directly with a text editor. The
      comments in the file explain most of the various configuration items.


      UPGRADING WEBCOLLAB TO A NEWER VERSION
      --------------------------------------

   1. Install the new files in a new directory (You can install over the
      existing directory, but this method is safer).
   2. For UNIX: Make sure [webcollab_directory]/config/config.php file
      is writable by everyone.
   3. Point your web browser at
      http://your_site/webcollab_directory/setup.php (Replace
      'your_site'and 'webcollab_directory' with the relevant values for
      your site.
   4. At the first screen prompt, choose to use an *existing database*.
      Do not create a new database.
   5. Enter your current database details at the screen prompt that follows.
   6. Let the setup program continue to the conclusion, but do not
      attempt to login.
   7. Point your browser at
      http://your_site/webcollab_directory/update.php (Replace
      'your_site' and 'webcollab_directory' with the relevant values for
      the new files on your site).
   8. Login as requested...
   9. Database upgrade is done automatically (If database upgrades are
      in fact not required, no harm will be done).
  10. If you are storing uploaded files in the default upload directory
      of /files/filebase, you need to copy/move the existing uploaded
      files across to the same directory in the new WebCollab.
  11. You can now delete your old WebCollab directory, and rename the
      new WebCollab directory to match the old. Note that you *must*
      change the BASE_URL parameter in /config/config.php to match the
      correct directory. You will also need to the same for the
      FILE_BASE parameter, if you use the default directory. To do this:
          * Open config.php with your favourite text editor
          * Find the line with *BASE_URL*. It is near the top of the file.

            define('BASE_URL', "http//your_domain.com/old_webcollab_directory/" );

          * Change this line to match the new directory (Don't forget
            the trailing slash...)

            define('BASE_URL', "http//your_domain.com//new_webcollab_directory//" );

          * Now make sure that FILE_BASE is pointing to the right upload
            directory. The entry needs to be a full path to the new
            upload directory:

            define('FILE_BASE', "/var/www/html/webcollab/files/filebase" );

          * Save the edited file.
          
  12. For UNIX: Make config.php protected again.

      The database upgrades (if required) are backwardly compatible and do not
      affect stored data. However, as with all upgrades, backing up your data
      is a sensible precaution.
      Database upgrades are required on pre-1.40, pre-1.60 and pre-1.70 databases.
      

      MANUAL SETUP FOR MYSQL
      ----------------------


        1. Database Setup and Customisation:

*Note*: If you are using Linux, you can automate database creation and
populating with tables. See below <#linux>.

   1. Make sure you have a valid user account and password for MySQL.
      (We'll call them 'user_name' and 'your_password' in this example).
   2. Choose a new MySQL database name with a convenient name of your
      choice. (We'll call the database 'webcollab' in this example).
   3. Enter the MySQL database command mode. Make sure that your
      user_name has enough rights to make new databases. Enter your
      password when prompted.

        # mysql -u user_name -p
        Enter password:
        Welcome to the MySQL monitor.  Commands end with ; or \g.
        Your MySQL connection id is 114 to server version: 3.23.54
        Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
        
        mysql>

   4. Create the database 'webcollab', and then quit the command mode.
      Don't forget the semi-colon at the end of the first line!

        mysql> CREATE DATABASE webcollab;
        Query OK, 1 row affected (0.05 sec)
        
        mysql> \q
        Bye
        #


        2. Populate Database:

   1. Use the provided "webcollab-*.**/db/mysql.sql" script to populate
      the webcollab database.
   2. For a *nix system navigate to your web server root directory.
      Enter your password again when prompted.

        #mysql -u user_name -p webcollab<./webcollab-*.**/db/schema_mysql.sql

   3. If you are installing to a Windows system, then from the command
      prompt, work your way into the "webcollab/db" folder. Then, run
      the following command:

        mysql -uuser_name -pyour_password webcollab>schema_mysql.sql


        3. Configuration File Customization:

   1. Open the file webcollab/config/config.php with your favourite text
      editor.
   2. Fill in the line *define('BASE_URL', "");* with the address of
      your site:

        define('BASE_URL', "http//your_domain.com/webcollab-*.**/" );

   3. Fill in the lines with *DATABASE_NAME*, *DATABASE_USER* and
      *DATABASE_PASSWORD*:

        define('DATABASE_NAME', "webcollab" );
        define('DATABASE_USER', "user_name" );
        define('DATABASE_PASSWORD', "your_password" );

   4. If you are using a database on a remote machine, then change the
      default value of *DATABASE_HOST* too.
   5. Save and close the file.


        4. Getting Online:

    * Point your browser to
      http://yourdomain.com/webcollab-*.**/index.php. If all is well,
      you should see a login page.
      Username: *admin*
      Password: *admin123*


        5. Change Admin Password and Email Address

    * Click on the 'Edit user details' button and change the admin
      password (and email address) as soon as possible.


        6. Admin Config Setup

   1. From the main screen, click on the 'Admin config' link in the menu
      boxes, left hand side of page. Depending on your screen
      resolution, you may have to scroll down to see it.
   2. Enter the requisite email addresses for your site into the boxes.
      Click on the descriptions for more help.
   3. The default check box settings in the lower part of the form can
      be left for now.
   4. Press the update button.


      AUTOMATED MYSQL INSTALLATION FOR LINUX
      --------------------------------------

   1. Proceed through steps 1 and 2 as above.
   2. Create and Populate the Database
          * Make sure you have a valid user account and password for
            MySQL. (We'll call them 'user_name' and 'your_password' in
            this example).
          * Choose a new MySQL database name with a convenient name of
            your choice. (We'll call the database 'webcollab' in this
            example).
          * Navigate to your web server root directory.
          * Run the command db_create_mysql.sh with the required options

              #./webcollab-*.**/db/db_create_mysql.sh user_name webcollab your_password

          * All done!
          * Carry on from step 4 above.


      MANUAL SETUP FOR POSTGRESQL
      ---------------------------


        1. PostgreSQL Database Setup and Customisation:

    *Note*: If you are using Linux, you can automate database creation and
    populating with tables. See below <#linux_postgres>.

    * Make sure you have a valid user account and password for
      PostgreSQL. (We'll call them 'user_name'and'your_password' in this
      example).
    * Choose a new PostgreSQL database name with a convenient name of
      your choice. (We'll call the database'webcollab' in this example).
    * Enter the MySQL database command mode. Make sure that your
      user_name has enough rights to make new databases. Enter your
      password when prompted.

        # createdb -W -U user_name webcollab
        Enter password:
        =# CREATE DATABASE 'database name';
        =# \q


        2. Populate Database:

   1. Use the provided "webcollab-*.**/db/pgsql.sql" script to populate
      the webcollab database.
   2. For a *nix system navigate to your web server root directory.
      Enter your password again when prompted.

        # psql -U 'database_user' -e 'database_name' < schema-pgsql.sql


        3. Configuration File Customization:

   1. Open the file webcollab/config.php with your favourite text editor.
   2. Fill in the line *define('BASE_URL', "");* with the address of
      your site:

        define('BASE_URL', "http//your_domain.com/webcollab-*.**/" );

   3. Fill in the lines with *DATABASE_NAME*, *DATABASE_USER*,
      *DATABASE_PASSWORD* and *DATABASE_TYPE*:

        define('DATABASE_NAME', "webcollab" );
        define('DATABASE_USER', "user_name" );
        define('DATABASE_PASSWORD', "your_password" );
        define('DATABASE_TYPE', "postgresql" );

   4. Do not change the default value of *DATABASE_HOST* unless you have
      re-configured PostgreSQL to accept TCP/IP connections
   5. Save and close the file.


        4. Getting Online:

    * Point your browser to
      http://yourdomain.com/webcollab-*.**/index.php. If all is well,
      you should see a login page.
      Username: *admin*
      Password: *admin123*


        5. Change Admin Password and Email Address

    * Click on the 'Edit user details' button and change the admin
      password (and email address) as soon as possible.


        6. Admin Config Setup

   1. From the main screen, click on the 'Admin config' link in the menu
      boxes, left hand side of page. Depending on your screen
      resolution, you may have to scroll down to see it.
   2. Enter the requisite email addresses for your site into the boxes.
      Click on the descriptions for more help.
   3. The default check box settings in the lower part of the form can
      be left for now.
   4. Press the update button.


      AUTOMATED POSTGRESQL INSTALLATION FOR LINUX

   1. Create and Populate the Database
          * Make sure you have a valid user account and password for
            PostgreSQL. (We'll call them 'user_name'and 'your_password'
            in this example).
          * Choose a new PostgreSQL database name with a convenient name
            of your choice. (We'll call the database 'webcollab' in this
            example).
          * Navigate to your web server root directory.
          * Run the command db_create_mysql.sh with the required options

              # ./db_create_pgsql.sh user_name webcollab

          * All done!
          * Carry on from step 3 above.

