$Id: INSTALL.txt,v 1.9 2002/12/09 14:03:03 mdruilhe Exp $
======================================================================
Installation instructions for w-agora 4.1
======================================================================
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" :
"; phpinfo(); exit ?>
PHP is not running or is not configured for this extension
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 ' 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.1.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 '' :
- forums/
- forums//default
for each forum '' in ''
- forums//
- forums///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