phpBB 2 : Creating Communities phpBB 2.0.1 INSTALL

Please read this document completely before proceeding with installation.

Please note these instructions are not fully comprehensive, a more thorough userguide will be available on the phpBB website in the near future. However, this document will walk you through the basics on installing the forum software.

A basic overview of running phpBB 2.0.1 can be found in the accompanying README documentation. Please ensure you read that document in addition to this! For more detailed information on using phpBB 2 you should read Userguide now available online.

  1. Quick Install
  2. Requirements
  3. New Installations
    1. Changing the file extension
    2. Replacing an old phpBB 1.x install
    3. Installing on MySQL 3 and 4, PostgreSQL 7.x, MS SQL 7/2000 (inc. via ODBC)
    4. Installing on MS Access 2000/XP
    5. Entering required data
    6. Completing installation
  4. Upgrade from phpBB 1.4.x
  5. Upgrade from phpBB 2.0 beta-1
  6. Upgrade from previous Release Candidate versions of phpBB 2
    1. Changes in language pack format and templates
  7. Upgrade from stable releases of phpBB 2
    1. Full package
    2. Changed files only
    3. Patch file
    4. All package types
  8. Important post-Install tasks for all installation methods
    1. Uploadable avatars
    2. Safe Mode
    3. Optional extras
  9. Disclaimer

1. Quick Install

If you have basic knowledge of using FTP and are sure your hosting service or server will run phpBB 2 you can use these steps to quickly get started. For a more detailed explanation you should skip this and go to section 2 below.

  1. Decompress the phpBB 2 archive to a local directory on your system.
  2. Upload all the files contained in this archive (retaining the directory structure) to a web accessible directory on your server or hosting account.
  3. Change the permissions on config.php to be writeable by all
  4. Using your web browser visit the location you placed phpBB 2, e.g. http://www.mydomain.com/phpBB 2, http://www.mydomain.com/forum/ etc.
  5. Fill out all the requested information and hit Submit
  6. Change the permissions on config.php to be writeable only by yourself
  7. Click the Complete Installation button or revisit the location you entered above.
  8. phpBB 2 should now be available, please read at least section 8 below for important post-installation instructions.

If you experienced problems or do not know how to proceed with any of the steps above please read the rest of this document.

2. Requirements

Installation of phpBB 2.0.1 requires the following:

  • A webserver or web hosting account running on any major Operating System
  • A SQL database system, one of:
    • MySQL (3.22 or higher)
    • PostgreSQL 7.0.3 or higher (preferably 7.1.x or 7.2.x)
    • MS SQL Server (7 or 2000) directly or via ODBC
    • MS Access (2000 or XP) via ODBC
  • PHP (3.0.9 and above or preferably a recent 4.x) with support for the database you intend to use above

If your server or hosting account does not meet the requirements above I am afraid phpBB 2.0 is not for you.

3. New Installations

Installation of phpBB 2 will vary according to your server and database. If you have shell access to your account (via telnet or ssh for example) you may want to upload the entire phpBB 2 archive (in binary mode!) to a directory on your host and unarchive it there.

If you do not have shell access or do not wish to use it you will need to decompress the phpBB 2 archive to a local directory on your system using your favourite compression program, e.g. winzip, rar, zip, etc. From there you must FTP all the files it contains (being sure to retain the directory structure and filenames) to your host.

All .php, .inc, .sql, .cfg and .htm files should be uploaded in ascii mode, while all graphics should be uploaded in binary mode. If you are unfamiliar with what this means please refer to your FTP client documentation. In most cases this is all handled transparantly by your ftp client but if you encounter problems later you should be sure the files where uploaded correctly as described here.

Once all the files have been uploaded to your site you should point your browser at this location. For example if your domain name is www.mydomain.tld and you placed phpBB 2 in a directory /phpBB 2 off your web root you would enter http://www.mydomain.tld/phpBB 2/ into your browser. When you have done this you should see the phpBB 2 Installation screen appear.

3.i. Changing the file extension

If the file extension used to execute PHP scripts on your server is not .php but for example .php3 or .phtml you should first rename all files ending in .php and change the value of $phpEx in extension.inc. In the vast majority of cases this step will be unncessary.

3.ii. Replacing an old phpBB 1.x install

PLEASE NOTE, you should NOT place phpBB 2 files into the same directory as any previous installation of phpBB 1.x! Create a new directory (or move your old phpBB 1.x out of the way), failure to do this will result in runtime errors.

3.iii. Installing on MySQL 3 and 4, PostgreSQL 7.x, MS SQL 7/2000 (inc. via ODBC)

Before proceeding with installation you should ensure you have a database available. Most good hosting accounts now come with at least one database as part of the basic package although it may need to be setup before first use. Ask your provider for details if you are unsure whether you do or not. If you are running your own server and are unsure how to create a database you should refer to your SQL servers documentation or website, e.g. http://www.mysql.com/doc/, http://www.postgresql.org/users-lounge/, etc.

3.iv. Installing on MS Access 2000/XP

Before you install phpBB 2 you need to create a Data Source Name or DSN. The exact way to do this will depend on your hosting provider, if you are unsure you should check with them before proceeding. In general though you should create a System DSN which points to the location where you have stored an unarchived copy of the ms_access_primer.mdb file (this is contained in the ms_access_primer.zip which can be found in db/schemas/). The name you give this DSN will be used during installation. Do not proceed until this step is complete!

Please note that MS Access support is not designed for busy boards. If you anticipate more than one or two users being online at any given time you should upgrade to a more robust server solution.

3.v. Entering required data

Once you have reached the installation page you need to fill out several fields. Be sure to select the right database type! If you do not have or do not know the database name, database server, etc. please check with your hosting provider. For non-ODBC databases the database server is typically localhost but this is not universal! If you are using an ODBC based database (such as MS Access or MSSQL via ODBC) you should enter the DSN here (see 2.iv.).

The database prefix allows you to enter a few characters, short name, etc. which all tables used by this installation will be prefixed with. The default (phpbb_) will usually be fine. However if you have more than one copy of phpBB 2 using the same database be sure to alter it or you will receive errors during installation.

The remaining information is personal to you and your site. You will need to enter a username and password for the initial administration account (more administrators can be created later). The server name, server port and script path are essential because all emails containing URLs will use these values. The installer will guess initial values, however they may not be correct so be sure to check them!

Remember that a domain (or server) name does not include http://! Enter just the domain name, eg. www.mydomain.tld and not http://www.mydomain.tld/. The server port can, in the great majority of cases be left as 80, this is the standard http port. However if your web server listens to a different port because for example port 80 is blocked then alter this appropriately. The script path is the relative path from your webroot where phpBB 2 is installed, e.g. if you install phpBB 2 into phpBB 2/ in your webroot then enter phpBB 2 (or /phpBB 2/) as the script path.

3.vi. Completing installation

Once you have checked all the data press submit. The installation script will create and populate all the necessary tables. It will then attempt to write to the config.php file which will contain the basic configuration data used to run phpBB 2. If the installer cannot write config.php directly you will be given the option of either downloading the file or even FTPing it to the correct location. If you choose to download you should then re-upload the file to your server, overwriting the existing config.php in the process. If you attempt to FTP via the install script you should supply the requested information. Should FTP fail you will be able to download the file and then re-upload as described earlier.

During the installation procedure phpBB 2 will check to ensure the relevant PHP database module is available and will not proceed if it cannot be found. Should this happen be sure to check you have selected the correct database and/or ask your hosting provider for advice.

Do not proceed untill the installation is completed and (if necessary) you have uploaded the config.php file.

4. Upgrade from phpBB 1.4.x

Before upgrading we heavily recommend you do a full backup of your database! If you are unsure how to achieve this please ask your hosting provider for advice. One you have backed up your database you should follow the basic instructions given for New Installations above. However instead of selecting Install as the Installation Method you should select Upgrade.

As with install the upgrade is automated. The config.php will be written automatically (if possible, else you will be able to download a copy as with New Installation above). Once the config.php is in place everything should proceed without error. Please note that this upgrading process may take quite some time and depending on your hosting provider this may result in it failing (due to web server or other timeout issues). If this is the case you should ask your provider if they are willing to allow the upgrade script to temporarily exceed their limits (be nice and they will probably be quite helpful).

Once completed your board should be immediately available. If you encountered errors you should restore your original database and report the problems to our bug tracker or seek help via our forums (see README for details).

5. Upgrade from phpBB 2.0 beta-1

Sorry but no direct upgrade is available from beta-1 (we did warn you!). If you are reasonably confident with the use of SQL, etc. you may be able to make the required changes to the database manually. You will need to examine the CVS check-ins to determine what needs changing where.

6. Upgrade from previous Release Candidate versions of phpBB 2

Upgrading from these versions is generally quite easy. First you should make a copy of your existing config.php, keep it in a safe place! Next delete all the existing phpBB 2 files, do not leave any in place otherwise you may encounter errors later. You can leave alternative templates in-place but you should note they may not function correctly with the final release. It is therefore recommended you switch back to subSilver if you are currently using a different style. With this complete you can upload the new phpBB 2.0.0 files (see New Installations for details if necessary). Once complete copy back your saved config.php, replacing the new one.

You should now run update_to_201.php which, depending on your previous version, will make a number of database changes. You may receive FAILURES during this procedure, they should not be a cause for concern unless you see an actual ERROR, in which case the script will stop (in this case you should seek help via our forums or bug tracker).

RC-2 and below MSSQL users, please note that during the update procedure your existing forums table will be dropped and re-created. All data in standard fields will be retained. However if you have modified the forums table and added additional fields or altered existing ones these changes WILL be lost. If this is a significant issue for you we advise you comment out the "DROP FORUM TABLE" section in update_to_201.php and instead