W-Agora

Version: 4.2


What is it? | Requirements | Pre-Installation | Installation | Documentation | Support


What is it?

w-agora is a a set of scripts written in PHP (version 3 or 4) that comprise a forum program. This package is intended to allow users to share, exchange and publish information, files and discussions over the Web.

Most of the enhancements in w-agora 4.0 were developed for the educational servers in Germany (BLK-Modellversuch MoKK@)

Main features

Administrator side

  • You can install several forums (all forums can be managed via your web browser);
  • Full centralized and Web-based administration (to create/ configure sites, forums, customize look-and-feel, delete notes, ...);
  • Customization : all messages (including buttons, texts, titles), frames, forms are customizable;
  • Frames or no frames option;
  • Post/reply in a new window (optional);
  • Notes (posted messages) can be stored either in a HTML file or generated on-the-fly. In both cases, the notes are generated from a customizable template;
  • Message highlighting: The messages can be displayed in different colors depending on their date (this option is available for each forum)
  • 3 levels of administration :
    • root (system administrator) who has all rights to everything
    • administrator : can administer sites and manage forums and users in a site
    • moderator : is responsible for some forums in a site.
  • 4 forum access types:
    • public : free for reading & posting
    • registered : can be read by everyone but only registered users can post
    • restricted : can be read by everyone but only validated users (eg. accepted by the moderator) can post in it.
    • private : can be accessed only by users created through the administrative interface
  • Moderation option: Each forum (regardless of his type) can be moderated: i.e.: messages posted by end users are hidden until the moderators decide to validate them.
  • Online User registration: Users can register online in a site. They can choose a user ID then a password is generated and sent to their e-mail address. The user can later change his password at any time
  • Forum activation/deactivation: For maintenance purposes, a forum can be :
    • locked: Users can still access information but can not post to it
    • offline: The forum is not accessible

End User side

  • Threaded messages (users can reply to messages)
  • File upload support (optional), users can attach documents to their notes;
  • possibility to browse the file system on which the HTTP server runs to publish on the WEB (optional);
  • posts sent to the administrator and replies sent to users by email;
  • users can edit/delete notes
  • Search in forum (via swish, Namazu search engines or search into database )
  • wysiwyg editor
  • emoticons and smileys
  • auto conversion to links of embedded URLs
  • ability to receive replies by email (thread subscription)
  • forum email subscription (mailing list)
  • Forum download: A user can download a complete forum in one big HTML file, This can be useful to read the messages off-line.
  • and much more ...

Requirements

PHP:

w-Agora needs PHP 4.1.0 or greater. You need a Web server properly configured to run PHP scripts. You will find more information about PHP at http://www.php.net/

A relational database :

Your PHP installation needs to be configured to access one of the following databases.

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 runs 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 administer your web server 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 administer your web server yourself:

1. Make sure you have one of the supported database engines installed :

  • MySQL
  • PostgreSQL (6 and 7)
  • Oracle 8
  • Microsoft SQL server 7

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

mysqladmin -user -password 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 administer your web server / your virtual web server yourself: then you need a database access to a database engine on the web server (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 web host. You cannot run the grant statement, only the database administrator may do it. Your host performed this service for you having declared "db_user_1" as your own identification to access the database on the web server

Installation

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

- If you are installing w-agora for the first time, read the detailed installation instructions below
For impatient readers, follow the "Quick Installation Instructions" below.

- If you are upgrading an existing w-agora installation, read the UPGRADE.txt file located in the doc/ directory

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 fields1

Detailed Installation

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" You may rename it to "forums" or anything else.

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, which you may rename to forums or anything else/.

The next step is the uploading of the subdirectory "w-agora" (or"forums") with all created subdirectories to your web server 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 files are used by Apache Web servers and others 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 web server 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 web server 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 :

The database information (backend, username, password, hostname and port).

currently MySQL, Oracle8, PostgreSQL and MSSQL are supported.
This database must first be created, you can give it 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

  optionally, you can specify some database access parameters :
  • username : this is the name of the database user (e. g. "db_user_1" - see above)
  • password: it 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.
  • 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 not used but can be useful on some "non standard" installation

The default parameters that will be used for sites creation

  1. The directory where w-agora will create all the forums (forums is a good choice).
    w-agora will then create a directory for each forum you'll later create:
    • If the directory doesn't exist, w-agora will try to create it
    • If the directory already exists, you must give it write access to the user-id that the Web server runs as.
    • NB: You CAN put this directory outside the web tree (document_root) so that users cannot access these files outside the w-agora scripts.
  2. 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 in the database. 
  3. The name, email and password 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 !!
    The password must be entered twice for verfication
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 forums has its own database access and its own set of users The creation is done by the script : http://localhost/forums/create_site.php3

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

  1. The name, title and description that you want to give to this site.
  2. The database information (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:
    • If the directory doesn't exist, w-agora will try to create it
    • If the directory already exists, you must give it write access to the user-id that the WEB server runs as.
    • 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 a menu that will allow you to create a forum, administer 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 or http://localhost/forums/create_forum.php3?site=sitename if you changed the w-agora directory name to forums

Follows the instructions on 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 chose at the site creation (step IV) or a new specific theme.

Once the site is created, w-agora will propose a menu that will allow you to edit or administer 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 can later create other sites, create categories, forums, edit the graphic layout, and so on.

To access the administration of your forums again, use "admin.php", i.e. point your browser at :
http://yourdomain.com/w-agora/admin.php

Documentation

The following documentation is available in the w-agora distribution:

install.html - This file
doc/license.txt - Copyright and license information
doc/ChangeLog - List of changes by release
doc/INSTALL.txt - Installation instructions (english)
doc/INSTALL_*.txt - Installation instructions (Localized: French, japanese, Deutsch)
doc/UPGRADE.txt - Upgrading instructions & release notes (english)
doc/TODO.txt - What is in the pipe

More documentation is available on the w-agora website (http://www.w-agora.net)

Assistance & Commercial Support

- If you encounter problems with w-agora, help is available at: http://www.w-agora.net/

- Please send bugs reports, comments, suggestions (and criticisms!) to the support / development forum : http://www.w-agora.net/support.php

- Latest versions of w-agora can be downloaded from http://www.w-agora.net/download.php and from the CVS repository hosted at http://sourceforge.net/projects/w-agora/

- If you need customized commercial support, professional installation or specific developments, please drop a mail at <mailto:info@w-agora.net>

Enjoy it,

-- The w-agora team (Marc Druilhe and all the people who helped me in the development of w-agora)