# 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. MySQL (version 3.21 and greater) => http://www.mysql.com/ PostgreSQL (6.x and above) => http://www.postgresql.org/ Microsoft SQL server 7 => http://www.microsoft.com/ Oracle 8 => http://www.oracle.com/ # 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)