Phorum 5 Installation instructions
==================================

Contents:

1. Requirements
2. Quickstart guide
3. Detailed installation instructions
   3.1 Download Phorum
   3.2 Unpack the downloaded archive
   3.3 Place the Phorum files in your website's document root
   3.4 Create a database and a database user
   3.5 Configure the database access
   3.6 Run the web based installer
   3.7 Things to do after installing Phorum
4. Additional issues
   4.1 Additional issues for UNIX (Linux, BSD, Solaris, etc.)
       4.1.2 Cache directory
   4.2 Additional issues for Windows
       4.2.1 Cache directory
       4.2.2 Problems sending mail to end-users
       4.2.3 Date formatting
5. Support


1. Requirements
-------------------------------------------------------------------------------


   Requirements for running Phorum are:

   * A webserver

   * PHP, version 5 or above.

     PHP4 is over 5 years old. As of Phorum 5.2 there are some functions
     used in Phorum which *require* PHP5 as they didn't exist before.
     Therefor PHP5 is a requirement now. 

   * A MySQL server, version 5 or above.

     MySQL has discontinued active development for all version below 5.0. The
     Phorum teams uses 5.0 for all development. MySQL 5.0.15 was the first
     production release of the 5.0 branch.
     Since the first release of Phorum 5.2 we were only testing against MySQL-5
     but weren explicitly using MySQL-4 incompatible queries. 
     As of Phorum 5.2.14 there were changes needed to make Phorum work with more
     recent MySQL versions and therefore MySQL-5 or higher is a requirement now.

   If you do not run your own website, but have hosted your website with
   a hosting provider, then please ask your hosting provider if your
   account meets these requirements.


2. Quickstart guide:
-------------------------------------------------------------------------------


   This is the quickstart guide for installing Phorum, aimed at people that
   are used to working with websites, PHP and databases. If you are having
   problems following this guide, then please read chapter 3 instead.

   1. Unpack Phorum into a directory below your website's document root;
   2. Create a database and a full-access database user for that database;
   3. Edit include/db/config.php.sample, save it as include/db/config.php;
   4. Open {phorum url}/admin.php in your web browser and finish the install.


3. Detailed installation instructions
-------------------------------------------------------------------------------


 3.1 Download Phorum
 -------------------

   If you haven't already done so, download the latest Phorum distribution
   from http://phorum.org/downloads.php


 3.2 Unpack the downloaded archive
 ---------------------------------

   From Windows:

   If you have downloaded the .zip file, you can extract the
   files from that archive directly using Windows XP's zipfile support.
   If you downloaded the .tar.gz file, you will have to download an
   appropriate tool for unpacking, e.g. WinZip (http://www.winzip.com/).

   From UNIX:

   If you have access to a UNIX shell, you can unpack the .tar.gz
   archive using the following command:

   shell> tar xvzf phorum-x.y.z.tar.gz

   Or if the tar program on your system does not support the -z flag:

   shell> gunzip phorum-x-y-z.tar.gz
   shell> tar xvf phorum-x.y.z.tar


 3.3 Place the Phorum files in your website's document root
 ----------------------------------------------------------

   The document root for a website is the directory in which your site's
   web pages are stored. If your website's URL is "http://www.example.com"
   and you place the Phorum files in a directory called "forum" inside
   your document root, your Phorum installation will be available at the
   URL "http://www.example.com/forum". From now on, we will name this
   URL simply {phorum url}. So if you see {phorum url}/admin.php, using the
   example we mean http://www.example.com/forum/admin.php

   If the webserver is running on the same system as where you have
   unpacked the downloaded archive, you can move the unpacked files
   to your website's document root.

   If the webserver is running on another system, you will have to upload
   the files to your website's document root. In most cases, you will use
   FTP for this, but some hosting providers require SCP (secure copy,
   which is more secure than FTP). If you do not know how or where to
   upload the Phorum files, please contact your hosting provider.

   Security note:
   (simply ignore this if it does not make sense to you)
   There are software packages that require you to make files writable
   for the webserver (using the infamous "chmod 777"). DO NOT DO THIS
   FOR ANY OF THE PHORUM FILES. The webserver only needs read access on
   the distribution files, because all dynamic data is stored in the
   database. If you run into problems running Phorum, it will never be
   because you "forgot" to do "chmod 777" on any the Phorum files.


 3.4 Create a database and a database user
 -----------------------------------------

   Phorum stores all its data in a database. So you now need to create
   a database. Officially, only the MySQL database server is supported
   by Phorum, so we recommend to use MySQL whenever possible.

   If you have hosted your site with a hosting provider, then ask
   your hosting provider to setup the database and a full access
   database user for you.

   If you run your own database server, then you will have to create
   the database and the user yourself. If you are using a control
   panel, like phpmyadmin, then use that control panel to create
   them. Else, you can use the mysql prompt to create the database
   by issuing commands like:

   mysql> CREATE DATABASE phorum;
   mysql> GRANT ALL ON phorum.* TO 'user'@'localhost' IDENTIFIED BY 'password';

   Of course, for security reasons you would use your own user and
   password instead.

   If you are unsure how to create a database and a database user,
   please refer to your system documentation.


 3.5 Configure the database access
 ---------------------------------

   After setting up the database, you'll have to tell Phorum how the
   database can be accessed. This configuration is put in the file
   include/db/config.php inside your Phorum directory. This file is
   not in the distribution. Only a differently named sample file is
   included.

   First, copy or rename the file "include/db/config.php.sample" to
   "include/db/config.php". Now edit the config.php file to match the
   access settings for the database that was created in step 4.

   If you run your website on a remote server, then either edit
   the config.php file directly on that server (e.g. through a
   UNIX prompt) or upload the file to the correct location after
   editing it locally.


 3.6 Run the web based installer
 -------------------------------

   Now all is in place to run Phorum's installer script.
   Open {phorum url}/admin.php using your web browser. This is the admin
   interface, which will automatically detect that a fresh install has
   to be performed.

   Follow the instructions on screen to finish the Phorum installation.

   In case you do not see the installer, but a blank screen instead,
   something is wrong. Please check the following:

   - Does the PHP installation include support your database server? If
     the PHP installation is lacking support, it will not be able to
     connect to the database. If you are running your website with a
     hosting provider, then ask your provider;

   - Is there a typo in include/db/config.php? A typo might crash PHP.
     If you have access to your server's error logging, then please check
     for errors in there. You could ask your provider to look at the error
     log, in case you have no direct access to it;

   - Did all files get uploaded and was filename case properly preserved
     by your FTP client? There are some FTP clients which upload all files
     using lower case only. Check whether the files
     include/admin/PhorumAdminMenu.php and include/admin/PhorumInputForm.php
     are uploaded, using exactly these names and not something like
     include/admin/phorumadminmenu.php for example.


 3.7 Things to do after installing Phorum
 ----------------------------------------

   Now the installation is complete, test if the forum is working
   correctly by opening {phorum url} in your web browser. If you run
   into problems, please go to {forum url}/admin.php and click on
   "System Sanity Checks" in the menu. This page will perform a couple
   of system checks to rule out some basic problems. If problems are
   found, please follow the instructions from the sanity checks page
   to solve them.

   Login into the admin interface at {phorum url}/admin.php and check
   out what settings can be done to customize Phorum to your likings.

   Customize the looks of Phorum to your needs by creating a custom
   template. Instructions can be found in docs/creating_templates.txt.

   Read the additional issues for your system (below), docs/faq.txt
   and any other files in the docs dir that may help you.


4. Additional issues
-------------------------------------------------------------------------------


 4.1 Additional issues for UNIX (Linux, BSD, Solaris, etc.)
 ----------------------------------------------------------

  4.1.2 Cache directory
  ---------------------

   In step 5 above (Edit Settings) There is an entry called Cache
   Directory. the installer should set that to /tmp if you appear to
   be running a *nix system. This will keep compiled PHP versions of
   your templates in /tmp. You can change the cache dir if you do not
   want to have your files sitting in /tmp on the server or if you see
   error messages like:

   Warning:
   fopen(/tmp/tpl-default-header-a72fb9dd20915e5953aa9b07d3eb3871.php):
   failed to open stream: Permission denied in
   /path/to/phorum/include/templates.php on line 184

   If you change the the Cache Directory, the best bet is to set it
   to ./cache and make that dir (that is already there in the Phorum dir)
   writable by the web server. Most likely this means making it world
   writeable (chmod 777). If you do not have access to the shell prompt
   of the server and are using only FTP to access the server, please see
   your FTP client's help on setting the permissions for a directory.


 4.2 Additional issues for Windows
 ---------------------------------


  4.2.1 Cache directory
  ---------------------

   In step 5 above (Edit Settings) There is an entry called Cache
   Directory. The installer should set that to C:\Windows\Temp, if it
   can detect you are using Windows. This should work for most modern
   Windows versions. If it does not, you will see error messages like:

   Warning:
   fopen(c:\windows\temp\tpl-default-header-a72fb9dd209153aa9b07d3eb3871.php):
   failed to open stream: Permission denied in
   c:\path\to\phorum\include\templates.php on line 184

   You will need to change the Cache Directory. The Phorum team is not
   very familiar with Windows as a web server platform. We can only tell
   you that it will need to be something that the web server can write to.
   Changing the Cache Directory to ./cache has worked for some.


  4.2.2 Problems sending mail to end-users
  ----------------------------------------

   PHP has to be configured correctly on Windows systems to be able to
   send out mail. If this is not done, you might get errors and mail
   will not arrive. What you need to do is edit the file "php.ini" (this
   file holds the configuration for PHP). Find the section that is called
   "[mail function]". In this section, set the parameter "SMTP" to the
   hostname or IP-address of the your SMTP server. If you do not know your
   SMTP server, please ask your internet access provider. After this,
   PHP will know what mailserver to use for sending out mail messages.

   If you have no access to the php.ini file and the system administrator
   is not willing to update it for you, you will have to install the
   SMTP module for Phorum. You can download this module from the module page:
   http://phorum.org/cgi-bin/trac.cgi/wiki/ListOfModules
   In the settings for this module, you can specify the SMTP server to use
   for sending mail. When using this module, you will completely bypass PHP's
   builtin mail system.


  4.2.3 Date formatting
  ---------------------

   Windows does not support the date formatting function strftime() fully.
   If your dates are not showing correctly, you have to edit your language
   file ({phorum dir}/include/lang/<yourlanguage>.php) and change the
   definitions for $PHORUM['long_date'] and $PHORUM['short_date'] in there
   to something that will work for your system. We suggest using the
   following definitions:

      $PHORUM['long_date']="%B %d, %Y %I:%M%p";
      $PHORUM['short_date']="%m/%d/%Y %I:%M%p";

   Go to http://www.php.net/strftime for information on all available
   formatting options as well as the formats that Windows does not support.


5. Support
-------------------------------------------------------------------------------

   If you have questions about installing Phorum, please visit the website
   http://phorum.org/ and ask the development team for help in the
   Support forum. Also read the file docs/faq.txt for answers to the most
   common questions.



