Section 1: Introduction
Welcome to phpBB 2.0. This document should outline all the issues dealing with the installation and operation of the second generation of phpBB. phpBB 2.0 has been a year in development and represents a huge leap forward for the software. This version is truly a professional product that is suitable for use in any environment and is scaleable for all types of implementation. We, the members of the phpBB group, thank you for choosing our software and hope you find it useful in all your endeavors.
Section 2: Installation
Installation of phpBB 2.0 will vary according to your server and database. If you have shell access to your account, you may want to upload the entire phpBB 2.0 archive (in binary mode!) to a directory on your host and unzip it there. If you do not have shell access or do not wish to use it, you will need to decompress the phpBB 2.0 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. All .php, .inc, .sql, .cfg, .htm and .tpl 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.
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 unnecessary.
Once all the files have been uploaded to your site you should point your browser to this location, eg. http://www.mysite.tld/phpBB2 or http://subdomain.mysite.tld/, etc. Of course replace these with the real location! Everything from this point is fully automated.
PLEASE NOTE, you should NOT place phpBB 2.0 files into the same directory as phpBB 1.x! Create a new directory (or move your old phpBB 1.x out of the way); failure to do this will more than likely result in runtime errors.
2.1: 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. Ask your provider for details if you are unsure whether you do or not.
2.2: MS Access 2000/XP
Before you install phpBB 2.0, you need to create a Data Source Name. 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 unzipped copy of the ms_access_primer.mdb file ( ms_access_primer.zip 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.
2.3: All database types
Once you have reached the installation page (as explained above) you should fill out all the 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! For ODBC databases you should enter the DSN here. 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 is usually fine, however if you have more than one copy of phpBB 2.0 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!
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 that will contain the basic configuration data used to run phpBB 2.0. 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.0 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.
2.4: Upgrade
2.4.1: Upgrade from 1.x
Before upgrading we strongly recommend that you do a full backup of your database! If you are unsure how to achieve this, please ask your hosting provider for advice. Once 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 (see Appendix A: Reporting Bugs)
2.4.2: Upgrade from 2.0 RC Versions
Upgrading from these versions is typically quite easy. First you should rename or copy your existing config.php to a temporary location. Next upload (see Installation for details if necessary) the new 2.0 files to the same location as your previous installation of phpBB 2.0, ie. overwrite the existing files. Next delete the newly uploaded copy of config.php and replace it with your existing copy (ie. rename or move back the copy you saved previously).
You should now run update_to_final.php which, depending on your previous version, will make a number of database changes. You may receive the occasional “FAILURE” during this procedure; they shouldn’t be a cause for concern unless you see an actual “ERROR”, in which case the script will stop.
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 that you comment out the “DROP FORUM TABLE” section in update_to_final.php, and instead manually alter the forum_id column to remove the IDENTITY setting (if it exists).
Once the update_to_final has completed, you MUST proceed to the Administration General Configuration panel and check all the values in General Configuration. This is essential if you were running any version before RC-3 since extra information needs to be entered to enable correct URLs to be outputted in emails.
2.4.3: Changes in language pack format
Please note that changes have been made to the format of both language and image localisations from previous RC’s to RC-3. If you were running a version previous to RC-3 you WILL need to download new versions of all non-English language and localised subSilver images. You can delete any existing *_lang.gif files in the root subSilver/images directory since they were moved to subfolders in RC-3. In addition various changes to template variable names has occured from RC-2 through RC-4. It is highly unlikely that a template written for RC-2 will work without some changes in RC-4. Most of these changes are minor and can be found by examining the default subSilver template.
2.4.4: Upgrade from 2.0 Beta
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 and where changes are needed.
2.5: Post Installation Tasks
Once you have successfully installed phpBB 2.0, you MUST ensure that you remove install.php, upgrade.php and any update_to_*.php files. Leaving these in place is a potential security issue. Additionally you may delete the db/schemas and this docs/ directory if you wish.
You should proceed to the administration panel, depending on the installation/upgrade, you may have been directed there automatically. If not, login as the administrator you specified during install/upgrade, and click the “Administration Panel” link at the bottom of any page. Ensure that details specified in General -> Configuration are correct! (see section 3.2 General Admin for more information)
2.5.1: Uploadable avatars
If you wish to allow users to upload avatars (this is dependant on your hosting provider allowing it), you should ensure that the directories specified for storing avatars in General -> Configuration exist and have appropriate access rights (ie. for uploadable avatars the directory needs to be world writeable, a+w, 777, depending on your setup). Gallery based avatars are stored in subfolders off the directory specified in General -> Configuration. This allows you to group together common types of avatar. Do not store gallery avatars in the root directory listed in General -> Configuration; they won’t appear! (for more information on avatar settings see section 3.2.2.5 Avatar Settings)
2.5.2: Safe Mode
phpBB 2.0 RC-4 introduced support for uploadable avatars on systems running PHP in safe mode. If this applies to your hosting service, you will need to create a sub-directory called tmp in the directory you specified for storage of uploaded avatars (by default this is images/avatars as explained above). Give it the same access rights as for uploadable avatars above. This safe mode support includes compatibility with various directory restrictions that your host may impose (assuming they are not too restrictive and that the PHP installed is version 4.0.3 or later). There is generally no need for any manual setup for safe mode support because it is typically handled transparently (although PHP 3 users may run into difficulties).