Installing the forum
--------------------

By Nick Gammon <nick@gammon.com.au>

Home page: http://www.gammon.com.au/

Date: 10th January 2003

This document is best viewed in a monospaced font (eg. Courier, FixedSys).

General notes about the forum are in the document README.

Many of the actions below can be carried out by someone with normal access to a web server, however a few (such as creating the database, configuring Apache, and setting permissions on the file with the database password in it) may need to be done by the site administrator (root user) of the web server.

If you have problems with these instructions please write to me so that they can be amended for future users. Please be specific about what went wrong and how you fixed it.


Section A - Setting up the directory structure
----------------------------------------------

1. Unzip the archive into a suitable directory (eg. your home directory):

  tar xvzf forum_1.1.tgz

2. You should see a "forum" directory, and inside it, the following directories:

  admin  config  docs  forum_include html  images  include  sql

3. Move, or create soft links to, directories as appropriate. Important - only the directory "admin", "html" and "images" should be visible from the web server.

4. The purposes of the directories are:

admin

  PHP pages for administering the SQL database. You may wish to put an Apache "password" on this directory.

config

  Site-specific configuration. The two files here must be edited as described below.

docs

  Documentation and GNU public license.

forum_include
  
  PHP files included into other PHP files for use by the forum.

html  

  PHP pages for using the forum - this is the directory that your users will use. 

  In this directory there should be a soft link from index.php to bbshowpost.php. If not, type in this:

  ln -s bbshowpost.php index.php

images  

  GIF pictures used by the forum. To work properly these should be the top-level directory "images" (from the point of view of the web server). If you already have a directory called "images" in your web server root hierarchy, just copy these files into it.

include  

  PHP files included into the other PHP pages during execution (at present the file common.php).

sql

  SQL commands for initialising the database.


Section B - Configuration
-------------------------

Edit the two configuration files in the config directory: general_config.php  and general_config_2.php.

general_config.php

  General settings, excepting passwords. These are self-explanatory. If the example entries have slashes in them, make sure your own entries have slashes in similar places. 

  Most of the site configuration is stored in the database in the "control" table, however the contents of this file are needed to tell the forum where the database is, its password, and how to contact you if it can't open the database.

general_config_2.php

  Database password. This is in a separate file so you can protect it from other users of the web server. Assuming the Apache server runs as "www" user, we suggest you set its privileges like this:

    chmod 400 general_config_2.php
    chown www general_config_2.php


Section C - Create the mysql database and import tables
-------------------------------------------------------

1. Gain database root access to mysql:

  mysql -uroot -p
  Enter password: <database root password>

Note - the datababase root user is not the same as the Unix root user. It is simply the mysql user set up for administering mysql.

2. Use mysql to create a database called "forum":

 create database forum;

3. Grant access to this database to the approriate database user:
 
  GRANT ALL ON forum.* TO forumuser@localhost IDENTIFIED BY "password"; 

Note - the user (in this case "forumuser") is merely the user name that is used to gain access to the database. It is not necessarily a user name that logs into the operating system. 

You should choose a better password than "password". This password is stored in the file "general_config_2.php", mentioned earlier. 

The forum name and forum user are stored in the file "general_config.php".

4. Exit from mysql:

  quit

5. Import data into database.

  In the "sql" subdirectory you will find the table definitions and initial values to get the forum started. Use this command (modified to suit your database name and password) to import the data ...

  mysql -uforumuser -ppassword forum < forum.sql

  Substitute your user name and database password in the above example. Note the absence of a space beween "-u" and the user name, and "-p" and the password.


Section D - set up the web server
---------------------------------

It will help considerably to configure Apache to have "index.php" as a default page to load if the user merely specifies a directory.

eg. In the httpd.conf file have a line like this:

  DirectoryIndex index.html index.htm index.shtml index.cgi index.php

Note the "index.php" at the end of the line.



Section E - log on as administrator
-----------------------------------

1. Open the "logon.php" web page, and enter the administrator password.

The exact URL will depend on how you have set it up, but it will be something like this:

  http://your_site.com/admin/logon.php


User name: Administrator
Pass word: adminpassword


If you get an error message about "Fatal error: Failed opening required", or something similar, check the entry for "INCLUDE_DIRECTORY" in the file general_config.php. 

If you get an error message about "Cannot select database", or something similar, check the entry for "GENERAL_DATABASE_NAME" in file general_config.php. 

If you get an error message about "Warning: Access denied" or something similar, check the entries for "GENERAL_DATABASE_USER" in file general_config.php, and the entry for "GENERAL_DATABASE_PASSWORD" in file general_config_2.php.


2. CHANGE the administrator password now! 

  a. Select "Edit table" : "user", then click on "Edit" button.
  b. Click on "List All" button.
  c. Click on "Administrator [1]".
  d. Change the username from "Administrator" to your name (if you want).
  e. Change the password by putting an "=" in front of it, eg.
       Password:  =swordfish
     The password is hashed, when you visit the page again you will see it hashed.
  f. Click on the "Change" button near the bottom of the page.

3. CHANGE the forum administrator password and details now!

  a. Select "Edit table" : "bbuser", then click on "Edit" button.
  b. Click on "List All" button.
  c. Click on "Forum Administrator [1]".
  d. Change the username from "Forum Administrator" to your name.
  e. Change the password by typing in a new one. This one is stored as clear text to it can be emailed to people if they forget it. Thus, just type in the password literally without an "=" sign.
  f. Change your email address to the correct address. 
  g. Change "date_registered" to the word "now".
  h. Change "home_page", "bio" and "signature" as desired.
  f. Click on the "Change" button near the bottom of the page.

  
Section F - change control items
--------------------------------

  a. Select "Edit table" : "control", then click on "Edit" button.
  b. Click on "List All" button.
  c. Visit each link and amend as appropriate (click the Change button to save each amendment). You can then click on "List All" to see the list again, and do another one.

Below are the purpose of each control item:

admin_links  

  Extra HTML that is available to the site administrator once logged in.
  eg.  <a href="/forum/">(Forum)</a>

allow_deletes  
allow_edits  
allow_messages  
allow_notification  
allow_posts  
allow_registrations  

  These are all normally "1" to allow the above actions globally in the forum.
  Set to "0" to disable any action. For example, if you are being spammed you might set "allow_posts" to zero. If you don't want anyone to be able to register, set "allow_registrations" to zero. 

amend_post_date  

  Normally zero, however set to "1" if you want to be able to change the date-posted of any posting. This was provided for migrating from earlier forums.

dateformat  
datetimeformat  
timeformat  

  These three entries control how dates and times are displayed.
  Dateformat - dates on their own, eg. Mon 07 May 2001 
  Timeformat - times on their own, eg. 05:11 PM 
  Datetimeformat - both date and time, eg. Fri 13 Apr 2001 06:07 AM  

  You can use any of the special symbols from the list below. Some older versions of mysql do not require the "%" symbol.

  Defaults are:
 
   Dateformat: %a %d %b %Y
   Timeformat: %h:%i %p
   Datetimeformat: %a %d %b %Y %h:%i %p

    %M  Month name (January..December)  
    %W  Weekday name (Sunday..Saturday)  
    %D  Day of the month with English suffix (1st, 2nd, 3rd, etc.)  
    %Y  Year, numeric, 4 digits  
    %y  Year, numeric, 2 digits  
    %X  Year for the week where Sunday is the first day of the week, numeric, 4 digits, used with '%V'  
    %x  Year for the week, where Monday is the first day of the week, numeric, 4 digits, used with '%v'  
    %a  Abbreviated weekday name (Sun..Sat)  
    %d  Day of the month, numeric (00..31)  
    %e  Day of the month, numeric (0..31)  
    %m  Month, numeric (01..12)  
    %c  Month, numeric (1..12)  
    %b  Abbreviated month name (Jan..Dec)  
    %j  Day of year (001..366)  
    %H  Hour (00..23)  
    %k  Hour (0..23)  
    %h  Hour (01..12)  
    %I  Hour (01..12)  
    %l  Hour (1..12)  
    %i  Minutes, numeric (00..59)  
    %r  Time, 12-hour (hh:mm:ss [AP]M)  
    %T  Time, 24-hour (hh:mm:ss)  
    %S  Seconds (00..59)  
    %s  Seconds (00..59)  
    %p  AM or PM  
    %w  Day of the week (0=Sunday..6=Saturday)  
    %U  Week (0..53), where Sunday is the first day of the week  
    %u  Week (0..53), where Monday is the first day of the week  
    %V  Week (1..53), where Sunday is the first day of the week. Used with '%X'  
    %v  Week (1..53), where Monday is the first day of the week. Used with '%x'  
    %%  A literal `%'.  


email_from  

  When the forum sends an email, this is put into the "from" address. It should be a valid email address that will reach you.

email_signature  

  When the forum sends an email, this is put at the end of the email as a standard "signature".

faq_url 

  The URL that the "faq" link on the top of each forum page should go to.

home_url  

  The URL that the "home" link on the top of each forum page should go to. eg. your main home page.
 
font  

  HTML command to set the font for each page in the forum. eg.
     <FONT FACE="Verdana, Arial, Helvetica, Geneva" SIZE=-1>

forum_name  

  Name of this forum. Used in various places, such as on the web pages, in emails, etc.

forum_url  

  The URL of the forum. Used to generate various web pages. It should NOT have a trailing slash. eg.

   http://www.your_site.com/forum

forum_version  

  Currently 1. Please leave untouched so that future versions of the forum software can detect which database version is in use. This is not the same as the PHP pages version, but will be used in future if new fields are added to the database, so that by checking the version number, new versions can automatically create those fields when required.

head  

  HTML code to go at the top of each generated page. The special keywords <%TITLE%>, <%KEYWORDS%> and <%FONT%> are replaced by appropriate values by the forum. You can customise this to add buttons, site links etc. that are required at the top of the page.

tail  

  HTML code to go at the end of each generated page. You can customise this to add buttons, links and so on to the bottom of each page.


minuteswest  

  The number of minutes west of UTC (Universal Coordinated Time, otherwise known as GMT - Greenwich Mean Time) that the forum server is. If zero, the forum will attempt to establish this from the operating system. However if your posts are tagged with the wrong date you should work out the correct figure. It can be negative if the server is east of GMT (ie. east of London).

motd  

  HTML code that appears near the top of each forum page. You can put a Message Of The Day (motd) there if you wish. Since it is HTML you can put links, images and so on in it.

posts_per_page  

  The number of posts per page. If the number of replies to a subject causes the posts count to exceed this value, then the subject is broken into multiple pages. A reasonable value might be something like 10, 15 or 20. If too large, a subject can potentially result in a very large web page being generated.

post_under_different_name  

  Normally zero, however set to "1" if you want to be able to change the poster-name of any posting. This was provided for migrating from earlier forums.

recent_posts_count 

  The number of postings shown on the main forum page as "recent posts". This should be some reasonable value between, say, 10 and 100. If you make it too large then users will get a very long "main" page once the forum gets a lot of postings. Also see recent_posts_days.
 
recent_posts_days  

  The number of prior days shown on the main forum page as "recent posts". This should be some reasonable value between, say, 5 and 30. If you make it too large then users will get a very long "main" page once the forum gets a lot of postings. Also see recent_posts_count.

subjects_per_page  

  The number of subjects listed per topic page. If the number of subjects (threads) in a topic causes the subject count to exceed this value, then the topic is broken into multiple pages. A reasonable value might be something like 10, 15 or 20. If too large, a topic can potentially result in a very large web page being generated.


users_per_page  

  The number of users listed per user page. If the number of registered users exceeds this value, then the user list is broken into multiple pages. A reasonable value might be something like 10, 15 or 20. If too large, the user list can potentially result in a very large web page being generated.


Section G - create forum sections
---------------------------------

The "top" level of the forum is sections, which are broken into topics, and then each topic has a subject.

At present, adding sections is done manually (using the SQL editor) as it will be done infrequently.

You can add sections by:

  a. Select "Edit table" : "bbsection", then click on "Edit" button.
  b. Click on "Add" button.
  c. Fill in appropriate fields. "section_description" is a text-only description, which appears in the summary (on the main forum page). "section_motd" is the section Message Of The Day (MOTD) which appears when you view that particular section. The message of the day is in HTML.

 
Section H - check it out
------------------------

You should now be able to execute the forum, eg.

  http://www.your_site.com/forum/bbshowpost.php

  or (if you have the link to index.php mentioned earlier setup)

  http://www.your_site.com/forum/


Section I - multiple forums
---------------------------

Although the forum is not really designed to host multiple forums on one server, this should be achieved fairly easily.

1. Make a directory for each forum's HTML pages, eg.

mkdir /home/foruma/html
mkdir /home/forumb/html
mkdir /home/forumc/html

... and so on.

2. In each directory create *soft* links to the "real" forum code, like this ...

cd /home/foruma/html

ln -s /home/forum/main/bbforumcode.php
ln -s /home/forum/main/bbpassword.php
ln -s /home/forum/main/bbsearch.php
ln -s /home/forum/main/bbsendmail.php
ln -s /home/forum/main/bbshowbio.php
ln -s /home/forum/main/bbshowpost.php
ln -s /home/forum/main/bbupdatesubject.php
ln -s /home/forum/main/bbupdatetopic.php
ln -s /home/forum/main/bbuseredit.php
ln -s /home/forum/main/bbuserlist.php

In this case "/home/forum/main" is the "main" area where the real forum files live. By making soft links we are sharing the PHP files amongst each "sub" forum without having to make actual copies.

3. Create a config.php file in each directory containing something like this:

<?php
$CONFIG_PATH = "/home/foruma/config/";
?>

... replacing "foruma" with "forumb" and so on as required.

4. Create directories for each forum's config file, eg.

mkdir /home/foruma/config/
mkdir /home/forumb/config/
mkdir /home/forumc/config/

5. Inside each config directory place the files:

general_config.php
general_config_2.php

These will be suitably modified for each individual forum - eg. different database name, different password.

6. Load up the database for each forum and modify the control table appropriately (eg. different forum URL).

