Subversion Repositories Applications.papyrus

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 4 or above;

   * A MySQL server, version 4 or above.

   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 disctribution 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.

 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 clients 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 sections 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.