Installation requirements

The entire board is written in the PHP interpreter language. It is generally designed to run on anything from PHP version 4.1.0 on, but for security and performance reasons, version 4.3.3 or newer is greatly recommended. The Unclassified NewsBoard can also run with PHP 5 and is designed to run with almost any PHP configuration (e.g. register_globals, magic_quote_*). It may be necessary to increase the memory limitation of PHP to more than 8 MB using the memory_limit option. It seems to work fine with a limit of 20 MB.
If you want to use the graphical verification codes (these are codes the user has to copy out from the image which automated computers shouldn’t be able to do), you need to have the GD library set up with PHP. Read more about the requirements on If you have no GD library, you should unset the ‘use_veriword’ configuration option.
To use all functions correctly, the board needs certain filesystem access rights:
  • Any files and directories: read
  • Base directory: create files, write, rename (and on Windows only: delete)
  • unb_lib/logs/ directory: create files, append (ip.log: delete, write)
  • unb_lib/upload/ directory: create files, delete
  • unb_lib/rsscache/ directory: create and update files, delete
  • Each design’s tpl/cache/ directory: create and update files
  • board.conf.php, if it’s present: write, rename (and on Windows only: delete)
This overview is quite detailed and may only apply to environments that support filesystem ACLs. Generally, all files should be owned by the user that is running PHP and readable by the webbrowser. If this is not the case due to the administrative configuration, you may need to chmod some directories to something like 777, for details see the installation steps below.
The clean installation needs about 1.5 to 2 MB free webspace. User uploads (avatars, photos, attachments) and the log files (in unb_lib/logs/) need further space. Please read the warning about log files in the Show logs (TODO) section.
The only webserver I have tested is Apache 2. There are no big requirements on that, it should simply understand and process .htaccess files. Otherwise some security controls cannot be enforced. The Unclassified NewsBoard has been reported to run on Microsoft IIS, but you need to configure the directory options manually from the provided .htaccess files then. For details about these files, see the Internal Architecture documentation.
The only database back-end currently supported is MySQL. Version 3.23.something should be OK (I don’t know exactly, what version is required at least, their documentation can’t tell me). Versions 4.0 through 5.0 are recommended. There’s one major problem with MySQL up to the 4.0 series: it doesn’t natively support UTF-8 unicode data. In general, there’s no problem with that, except that sorting may be incorrect in some situations (e.g. the members list). The Unclassified NewsBoard will make use of MySQL 4.1’s unicode capabilities for new installations if available. For the installation process, the database that should be used must already exist, it cannot be created. The following access is needed on it:
  • Normal operation: SELECT, INSERT, UPDATE, DELETE, ALTER TABLE (for changing of extra profile fields)
Other DBMS support is planned, but the abstraction layer is currently not 100% implemented (see Bug #163).

Installation steps

  1. Unpack the distributed archive file into a directory on your webserver.
  2. Make sure you hold a MySQL database account where you are allowed to create tables and access to their data. You will need the following information to connect to the database:
    • Server name: IP address or hostname
    • Username and password
    • Database name
  3. You are now ready to run the automatic installation script. Its URL is the hostname and path that you copied the files into, followed by “install.php”, i.e.: http://localhost/forum/install.php. This script will first ask you some questions about the forum’s title and your database account information and then create all necessary tables in the database.
    It may be necessary to change some file access rights via FTP. If this is the case, the install script will inform you about that. Then please chmod the following directories to 0777:
    • The board’s main directory, this is where forum.php is in
    • unb_lib/logs/
    • unb_lib/upload/
    • unb_lib/rsscache/
    • Each design’s tpl/cache/ directory, i.e. unb_lib/designs/modern/tpl/cache/
    • board.conf.php, if it’s present from an older UNB version that is to upgrade
    Here’s a little chmod tutorial [page gone, find others]. Chmoding files is a workaround for poorly configured web servers only. This setting may not be necessary for your site, but if it doesn't work, be sure you have tried this.
  4. As the install script will tell you now, you still need to adjust some of the board settings, like the e-mail account to be used or display options. Just follow the link to the control panel. You should also update your profile and change your username and password there.
    At installation, the configuration file board.conf.php will not be overwritten if it already exists. Only if it’s not there, it will be copied from board.conf.php.example.
  5. You can now create all forums you wish to offer to your users and set all access rights accordingly.
  6. When you’re finished with all this, unlock the board by unchecking the “Administrative board lock” option in the “Advanced Configuration”.

Upgrading from a previous UNB version

Upgrading from an older UNB version works a lot the same way as installing. You need to unpack the archive and upload all its files (except the docs/ and extra/ directories) to the web location, overwriting existing files. When you upgrade from an older version, you should keep your old configuration file, board.conf.php.
Should it be necessary to update the database or the configuration file, the forum will tell you when accessing it after replacing the files. There will be an information box right at the top of the page, visible to all logged in administrators. It contains a link to the install script with the “Update” option pre-selected. This will perform all modifications to your database layout and the configuration file, keeping all users, forums, posts etc. It may be necessary to remove the lock.conf file before the upgrade can be run (details below). In case you cannot access the forum normally, probably because of a too fundamental change, you can directly call install.php in your web browser.
At some places you have the opportunity to create “user configuration” files, called *.user.php. The release archives do not contain these files directly but only as examples, with an additional .example appended to their filename. This way, your custom configuration files cannot be overwritten when replacing the files with a newer version. The board configuration file board.conf.php also belongs to this group. See the Files and directories structure page for details on each file.

Upgrading from version 1.5 to 1.6

Upgrading from version 1.5 to 1.6 is a little more complex though. The directory structure has changed a little so you need to move around some files. Previously, there have been several directories in the forum root directory (this is where forum.php is in), now only the board library directory is left there. Following is a list of new directory names:
/bb_lib /unb_lib
/bb_designs /unb_lib/designs
/bb_log /unb_lib/logs
/bb_plugins /unb_lib/plugins
/bb_upload /unb_lib/upload
/rss_cache /unb_lib/rsscache
In case you keep your current configuration file (see above), you need to manually update the directory names in that file. The only relevant keys are:
lib_path = unb_lib/
lib_url = unb_lib/
log_path = unb_lib/logs/
It may also be necessary to set the configuration option “db_utf8 = 1” if you have the MySQL server version 4.1 or newer. See the section “Moving to another webhoster” below for details.
You should also remove all designs for version 1.5 as they are incompatible with the HTML template system introduced in version 1.6.

How the upgrade script works

The upgrade script is always up-to-date with the code version it comes with and will always be able to upgrade from any version since 1.4.2, intermediate and development snapshots included. It does this by scanning the database layout for past changes. If an old table which has been renamed in the past still exists, it will be renamed. If a column still has another data type that was changed by then, it will be converted. If a configuration option which was once removed is still present, it will be removed, etc. This way, the upgrade script goes through the entire history of changes and applies every single change that is missing.
Note that this only works in one direction. You cannot downgrade the data automatically with this script. To go back to an older version, you either need to disassemble the upgrade script and revert all changes until you find the comment for the version you want to go to, or you can use a backup you made before upgrading, losing all changes since then.

Moving to another webhoster

You can move the entire board to another webhoster with ease. Just follow these steps:
  1. It may be a good idea to first lock the old board or at least set it into read only mode.
  2. Copy all files with their directory structure intact to the new webspace. You may download it to your computer and upload it again, both via FTP. The above notes about file access settings (CHMOD) also apply here.
  3. Dump the database. (TODO: we have a script for this built-in now!) You can do this with your webhoster’s database tools or other software like phpMyAdmin. You need a dump of all tables that begin with the prefix you defined at setup time (db_prefix configuration option). Be sure to enclose table and field names with backquotes. The recommended options for phpMyAdmin are:
    • Select all tables to export from the list
    • Export as SQL
    • Include structure and data
    • Enclose table and field names with backquotes
    • Export type: INSERT
    • Save as file
  4. Import the database dump into the new webhoster’s database.
  5. Update the home_url setting in the configuration file board.conf.php to the new URL. This is required, otherwise the first click on the new forum will bring you back to the old URL.
Be sure to specify the same character set for the database restore as for the backup. If there was nothing to specify for the backup, it is Latin1 (ISO-8859-1). If you have created your board database with an older UNB version than 1.6 RC 3 or on an older MySQL server than 4.1, your database contains UTF-8 data in a normal Latin1 table. In this case, you need to set the configuration option db_utf8 in the configuration file to the value “0”. This will disable the use of MySQL’s Unicode capabilities which are only useful for new board installations with a new database. At this time there’s no converter available for this in UNB.
There seems to be a serious character set problem with MySQL’s own backup and restore tool “MySQL Administrator”. Using this programme may lead to corrupted characters from the extended ASCII range (above 0x7F), i.e. accented characters, umlauts or cyrillic characters. Also the “mysql” command-line tool does not seem to help here.

The mysterious lock.conf file

Once the installation, import or update has completed, there will be an empty file called lock.conf in the base directory. The only function this file has with its existance is to disable these very scripts so that nobody can re-run the setup again and reset all data this way. It’s safe to remove the file when you also removed all install/import/update PHP scripts (e.g. install.php).
Attention: If file access rights are not set correctly, a warning will be displayed at the top of the install page. In case the lock.conf file could not be created, you should remove the install script immediately after setup is done since there will be no protection on them!
© 2003–2016 by Yves Goergen
Content last updated on 2006-11-01 20:00 UTC
dotforward webhosting Get Firefox XHTML 1.1 CSS