Installation and config » manual install for 2.1.8

Here will be shown how to manually configure and install JForum. It is assumed that the you has some knowledge on how to install / configure a Java servlet Container ( or already has one up and running ), and the database is properly configured.

For automated installation, check the Installation and configuration » wizard section.

Note: These instructions are for the installation of JForum, release version 2.1.8. Some of the steps here described may not be valid for older versions, which are no longer supported.

To get JForum, go to the download page and get the latest version.

After the download, unpack the .ZIP file into your webapp's directory (or anyplace you want to put it). A directory named JForum- will be created, where is the version, which may be "2.0", "2.1.7" etc... this it just for easy version identification.

You can rename the directory if you want. The next step you should do is register the JForum application within your Servlet Container, like Tomcat. This document will use the context name "jforum", but of course you can use any name you want.

JForum expects that some directories are writable by the webserver. Before you start installing, please check if the following directories, and their sub-directories, exist and have full write permissions:

• upload
• tmp
• images
• WEB-INF/config
• WEB-INF/jforumLuceneIndex

First of all, you must have MySQL, Oracle or PostgreSQL installed and properly configured. HSQLDB is supported as well, and has built-in support, so you don't need to download it (eg, it is an embedded database).

Open the file WEB-INF/config/SystemGlobals.properties. Now search for a key named database.driver.name and configure it according to the following table:

The default value is mysql, which means JForum will try to use MySQL. Note that the value should be in lowercase.

Next, you can tell JForum whether to use a Connection Pool or not. A connection pool will increase the performance of your application, but there are some situations where the use of a connection pool is not recommended or even possible, so you can change it according to your needs.

By default JForum uses a connection pool, option which is specified by the key database.connection.implementation. The following table shows the possible values for this key:

If you have chosen net.jforum.DataSourceConnection, then set the name of the datasource in key database.datasource.name, and ignore the table below. Otherwise, do the following steps:

Edit the file WEB-INF/config/database/<DBNAME>/<DBNAME>.properties, where <DBNAME> is the database name you are using - for instance, mysql, postgresql or hsqldb. In this file there are some options you should change, according to the table below:

The other properties you may leave with the default values if you don't know what to put.

If you're going to use MySQL 4.1 or newer, please pay attention to the fact that starting from this version (the mysql version, not JForum) many architectural changes were made. By default, now the system runs using the UTF-8 character set (previous versions lack support for it), and it may result in some problems depending the way you configured JForum to connect to MySQL. Regular installations will opt to use unicode and UTF-8 as character encoding, but, when using MySQL 4.1+, you shoudl avoid id. To do that, open the file mysql.properties and change the value of the keys "mysql.encoding" and "mysql.unicode" to empty (eg, mysql.unicode= ).

The next step is to create the tables. To do that, use the import script named "<DBNAME>_db_struct.sql", placed at WEB-INF/config/database/<DBNAME>. This script will create all necessary tables to run JForum. The script were tested and should work with no problem at all. Also, please keep in mind that if you are upgrading JForum you need to take a look to see if a migration script exists. Look in the file named "Readme.txt" in the root directory to see.

Now it is time to run the script to populate the database tables. To do that, use the script named "<DBNAME>_data_dump.sql", also located at WEB-INF/config/database/<DBNAME>. One more time, you should have no problems with this step. If you do, please remember to inform the error message, as well the database name and version you're using.

The main configuration file for JForum is WEB-INF/config/SystemGlobals.properties. The file is well documented, and you certainly will want to change some of the settings there, like forum's URL, name, description, location of some directories and etc.

• Remove the line "install = net.jforum.view.install.InstallAction" from the file WEB-INF/config/modulesMapping.properties
• JForum uses a servlet mapping to invoke the pages. This mapping is *.page, and is already properly configured at WEB-INF/web.xml. If you are running JForum on a ISPs which have Apache HTTPD in front of Tomcat, you may need to contact their Technical Support and ask them to explicity enable the mapping for you.
• The directory "images", "tmp", "upload" and "WEB-INF" ( and their sub-directories ) should have write permission to the user who runs the web server. You'll get nasty exceptions if there is no write permission. In the same way, if you're going to use the file attachments support, the directoy you'd chosen to store the files ("uploads" by default) should also be writable.
• The administration interface is accessible via the link Admin Control Panel, located in the bottom of the main page. You will only see this link if you are logged as Administrator. See above the default password for the admin user: the username is Admin and the password is admin
• This step is HIGHLY recommended: Open the file WEB-INF/config/SystemGlobals.properties and search for a key named user.hash.sequence. There is already a default value to the key, but is VERY RECOMMENDED that you change the value. It may be anything, and you won't need to remember the value. You can just change one or other char, insert some more... just type there some numbers and random characters, and then save the file. This value will be used to enhance the security of your JForum installation, and you will just need to do this step once.