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
- gunzip/Untar the package inside your document root
- set execute/write permissions to the conf/ and forums/
folders
- 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
- 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.
- 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.
- 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.
- The name, title and description that you want to give to
this site.
- The database information (username, password, hostname and
port). This database must first be created.
- 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.
- 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.
- 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)
|