  $Id: INSTALL.txt,v 1.10 2005/04/18 16:38:44 mdruilhe Exp $
 
  ======================================================================
                      
	Installation instructions for w-agora 4.2

  ======================================================================


                             PRE-INSTALLATION
                             ================


You should verify the above pre-requisites in order to install w-agora :

I. PHP properly configured
--------------------------

  1. Make sure you have PHP installed and properly running at your site.
In order to verify that PHP is properly running, you can just copy & paste the
following lines into a file named "info.php" or "info.php3" :

<html>
<?echo "It works !!<br>"; phpinfo(); exit ?>
<STRONG>PHP is not running or is not configured for this extension </STRONG>
</html>

Then load this page into your browser. If everything is OK, it should 
display a page with all the PHP configuration, and you should not see the message : 
"PHP is not running or is not configured for this extension"

  2. w-agora is supposed to run with PHP version 3.0.7 and greater. PHP 4 is even better.

  3. If you are running PHP in SAFE MODE then read the SAFE MODE section at the 
end of part II. If you do not administrate your webserver yourself, ask your internet 
service provider if PHP is running in SAFE MODE or not. You can also get this 
information by running the "info.php" script indicated above.

  4. Notice that this release of w-agora needs the "short_open_tag" option to be 
enabled in the PHP configuration. If it has not been enabled by your ISP, you can 
force this option for w-agora by creating the following .htaccess file:

# .htaccess example
# Enable '<?' tags in PHP configuration
php_flag short_open_tag on


II. A database access
---------------------

--> If you administrate your webserver yourself:

  1. Make sure you have one of the supported database engines installed :
     - mysql
     - postgres (6 and 7)
     - Oracle 8
     - Microsoft SQL server 7

  2. If you do not have a database already, create a database. 
     Eg: with MySQL you can use a command like this:

    mysqladmin -uuser -ppaswword create agora
    (you can use the database you want, 'agora' is just an example. Replace user & 
    password with the user/password of your mysql user)
  
  3. Be sure that you have a user for that database which has the rights to
    select, insert, update, delete, create, alter and drop.  A grant
    statement for this user would look like this:

    GRANT select, insert, update, create, alter, delete, drop
    ON agora.* TO user@localhost
    IDENTIFIED BY 'password';

    (Replace 'agora' with the name of the database created in step 2, and user with 
    the mysql user)


--> If you do not administrate your webserver / your virtual webserver yourself:
    then you need a database access to a database engine on the webserver. (See 
    also 1. - requested engines.)

    In this case, you get the name of your database  (e. g. "my_own_db") and the 
    name of the database user (e. g. "db_user_1") from your internet service 
    provider. You cannot run the grant statement, only database administrator 
    may do it. Your provider performed this service for you having declared 
    "db_user_1" as your own identification to access the database on the 
    webserver.


                             INSTALLATION
                             ============


  Installation of w-agora will vary according to your server and database.


                      Quick Installation Instructions
                      ===============================

   1. gunzip/Untar the package inside your document root
   2. set execute/write permissions to the conf/ and forums/ folders 
   3. Point your browser at setup.php[3] and fill out the required fields



I. EXTRACT /UPLOAD
------------------

  1. If you have shell access to your account you may want to upload the entire 
     w-agora archive (in binary mode!) to a directory on your host and unzip (or
     gunzip/untar) it there.
  
     o Under Linux untar the package in some useful place such as your 
     document_root directory
     eg. (assuming the archive was uploaded to /tmp)
          $ cd /var/www/html/
          $ tar -xzvf /tmp/w-agora-4.2.x.tar.gz

     This will install the package under the directory "w-agora"

     o On windows, simply extract the package using winzip or whatever.

  2. If you do not have shell access or do not wish to use it you will need to  
     decompress the w-agora archive to a local directory on your system. From
     there you must FTP all the files it contains (being sure to retain the
     directory structure) to your host. 

     If you downloaded W-Agora from the web to your PC under Windows, then
     store the downloaded program on your harddisk and unzip it into a 
     temporary subdirectory (eg. c:\w-agora or c:\temp). Expanding the zipped 
     file, the unzip program creates another subdirectory: w-agora. 

     The next step is the uploading of the subdirectory "w-agora" with 
     all created subdirectories to your webserver via ftp client or a WEB ftp 
service of your provider.  Copy the tree created to the appropriate 
directory on the server, e. g. "html/w-agora". You must upload ALL the 
files it contains (being sure to retain the directory structure) to your 
host. 

     All .php, .inc and .htm files should be  uploaded in ascii mode, while all 
graphics should use binary mode. If you are unfamiliar with what this means 
please refer to your FTP client documentation. In most cases this need not 
concern you since many FTP clients will automatically guess the correct 
mode to use.

II. CHECK FILES PERMISSIONS
--------------------------
  
  w-agora comes with 3 empty sub-directories :

      "w-agora/conf"
      "w-agora/forums"
      "w-agora/forums/agora"
 
  (these directories should contain only one file named ".htaccess". These file 
is used by some WEB servers (ie. apache) to protect the directory from 
unauthorized access).

  w-agora will use these directories to store various files (configuration, 
templates). If the directories were not created in the previous step, then you 
should have to create them in the directory "w-agora" on the webserver using a 
ftp client or a WEB ftp service and change the access properties of these 
subdirectories to "707" (see next)

  You must ensure that the above directories are writeable by the user-id 
  that the WEB server runs as.

  To do this :
  o  on a linux/unix system) issue a command like :
     (assuming nobody is the user that the WEB server runs as)
             "chown -R nobody ./w-agora"
              or 
             "chgrp -R nobody w-agora; chmod -R g+w w-agora"
     
     or (if you don't have root access)
              chmod -R a+w conf forums forums/agora
   
  o If you do not have a shell access to your server, you can use a FTP client :

     $ ftp your.ftp.site.name
     ftp> cd w-agora
     ftp> mkdir conf
     ftp> quote site chmod 707 conf
     ftp> mkdir forums
     ftp> quote site chmod 707 forums
     ftp> cd forums
     ftp> mkdir agora
     ftp> quote site chmod 707 agora

  o On a Windows/IIS platform, set the READ/write permissions

  o !!! If you are running PHP in SAFE MODE then read the following SAFE MODE 
section !!!


SAFE MODE SECTION
-----------------

The safe mode allows the access via php to those directories only, which have 
been created by the same client as the runner of the application is.

If your user identification at the webserver is (e. g.) "donald_duck", so you 
are the owner of all the directories which have been created via ftp. W-Agora 
needs some new directories to manage sites, forums and threads. These 
directories can be created by W-Agora during the installation procedure. If you 
invoke the W-Agora script "setup.php", the PHP-runner performs this script.  
This runner is a task with its own name, e. g. "phprunner". In this case, the 
owner of the directories needed to manage sites, forums and threads, is 
"phprunner". If you try to access (your name is "donald_duck - see example), 
your access will be denied in safe mode.

Therefore, you have to create all the forums directories manually via ftp. These 
directories are:

  - forums/agora
    
    for each site '<sitename>' :
    - forums/<sitename>
    - forums/<sitename>/default

    for each forum '<forumname>' in '<sitename>'
    - forums/<sitename>/<forumname>
    - forums/<sitename>/<forumname>/notes

The access properties of these directories should be set to "707".


III. SETUP
----------

Point your browser at the setup.php3 (or setup.php) script location to install 
and configure the program. eg.

    http://localhost/w-agora/setup.php3
or
    http://www.My_Domain.net/w-agora/setup.php

Configure the following parameters in the Installation form :

  1. The database informations
  ----------------------------  
  (backend, username, password, hostname and port).
     currently mySQL, Oracle8, PosgreSQL and MSSQL are supported.

     This database must first be created, you can give whatever name you want.

--> Using ISP services, your database name is (e. g. - see above) "my_own_db"   
 Ask your ISP if you don't know how to access your database

  2. optionally, you can specify some database access parameters :
  ----------------------------------------------------------------
        username
        password
        hostname and port number

  - The hostname is the name (or ip address) of the server on which the database 
server is running, usually "localhost".

  - The port number is generally not used and is only meaningful for mysql and 
postgreSQL. Usually, you must le but can be useful on some "non standard" 
installation 

  - The username is the name of the database user (e. g. "db_user_1" - see 
above) The password is the password associated with the database user (usually 
your own password) which has been set creating "my_own_db" via phpMyAdmin or a 
similar service.

  3. The directory where w-agora will create all the forums. w-agora will 
     then create a directory for each forum you'll later create: 
        o If the directory doesn't exist, w-agora will try to create it
        o If the directory already exists, you must give it write access to the
          user-id that the WEB server runs as.
        o NB: You CAN put this directory outside the web tree (document_root)
          so that users cannot access these files outside the w-agora scripts.

  4. The default search engine used by w-agora to search in the notes.
     If you set it to NONE, then the search will be done into the database.

  5. The name and email of the main (system) administrator: His reserved user-id 
is 'admin'

--> The main system administrator is the super user of the W-Agora system, not 
the "root" of the OS !!

  6. The password of the main administrator.

     Once the setup is done, w-agora lets you create your first site (see next 
section)


IV. CREATE SITE :
-----------------

  A site is a set of forums that can be accessed by a set of users.
  Each set of forum has his own database access and his own set of users
  The creation is done by the script : http://localhost/w-agora/create_site.php3

  Configure the following parameters. If you want to install the site in the 
same database than the setup installation, you just have to use the same 
parameters than the above setup form.

  1. The name, title and description that you want to give to this site.

  2. The database informations (username, password, hostname and port).
     This database must first be created.

  3. The directory where w-agora will create all the forums. w-agora will 
     then create a directory for each forum you'll later create: 
        o If the directory doesn't exist, w-agora will try to create it
        o If the directory already exists, you must give it write access to the
          user-id that the WEB server runs as.
        o NB: You CAN put this directory outside the web tree (document_root)
          so that users cannot access these files outside the w-agora scripts.

  4. The default search engine used by w-agora to search in the notes.
     If you set it to NONE, then the search will be done into the database.
 
  5. The default template that will be used for the forums that you'll later 
create

  Once the site is created, w-agora will propose you a menu that allow you to 
create a forum, administrate the site or create another site.


V. CREATE A FORUM :
-------------------

  The creation of a forum is done by the script : 
     http://localhost/w-agora/create_forum.php3?site=sitename

  Follows the instructions in the page.

  You will have to choose :

     1. The name, title and description of your forum.
     2. The template/theme : You can choose the default theme that you choosen 
        at the site creation (step IV) or a new specific theme.

  Once the site is created, w-agora will propose you a menu that allow you to 
edit or administrate the forum, create another forum, or access it as a user.


VI. THAT'S ALL FOLKS
--------------------
  
  At this point you should now be able to post your first message in the forum.
  
  You'll can later create other sites, create categories, forums , edit the 
graphic layout, and so on.

  to access the adminitration of your forums again, use "admin.php", ie. point 
your browser at :
  http://you.forum.site.domain/w-agora/admin.php

  