jforum - Powering Communities

Installation and configuration » wizard for 2.1.8

In this section is shown how to configure and install JForum using the Web Wizard interface. It is assumed that you have some knowledge on how to install/configure a Java servlet container (or already have one up and running), and the database is properly configured.

For manual installation instructions, check the Installation and configuration » manual Install 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.

Downloading JForum

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

Unpacking

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.

Directory permissions

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
Configuring

Next, point your browser to the following address: http://localhost:8080/jforum/install.jsp

The bold text, "jforum", is the context's name. If you changed the context name you will need to change it here too. After the page loads, you should see the screen shown by Image 1:


Image 1 - Welcome page

Please read carefully the fields' tips, since they contain valuable information. Below is a little explanation of each field:

Field name Required Description
Default Board Language Yes The language to display the messages in the forum. Note that, if the translation for some text is not available, an English text will be used
Database Type Yes The database server to use. If you don't know which one to choose, select "HSQLDB" from the list
Installation Type Yes Installation mode. Currently only "New Installation" is supported
Connection type Yes Which method to use to connect to database. Native will use regular connections, while DataSource will try to connect using the specified datasource name
DataSource name No If you chosen DataSource as Connection Type, then inform the name of the datasource
Database Server Hostname Yes The host where the database is located
Database Name Yes

Where the tables will be created. Note that the database should already exist.

If you're going go use HSQLDB, no extra configuration is needed, since it is created on the fly

If you are using Oracle, you probably will have to enter the SID here.

Database username No* The user of your database instance. *This field is required for databases other than HSQLDB
Database Password No The database password, if any. Please note that errors may occur when not using any password
Database Encoding No The text encoding for the database. You can specify it by hand in the "Other" field
Use Connection Pool Yes In case of doubt, choose No
Forum Link Yes The link to the forum context. If you are hosting it under some "real" domain and the context path is "/", the "Forum Link" will be the address of your site, in most cases.
Website Link Yes The link to your website.
Administrator Password Yes Type the password of the administrator (Admin user).

Now you can click the "Next Step "button. You will see the page shown in Image 2, which that contains a summary of your choices.


Image 2 - Checking the configuration before installation begins

If is everthing looks good, click on the "Begin Install" button. Note that if some warning message is shown, then there are some required steps that should be made before proceding with the installation.

Wait until the installation ends. If no errors occur, then you will see a page like the one shown in Image 3


Image 3 - Installation Finished

Congratulations! You have finished your JForum Installation. Before accessing the forum, do the actions pointed by the arrows, click on the check button and click on the button "Click Here to Access the Forum".

Administering the forum

Now you can login as Admin / and click in the link "Admin Control Panel", at the end of the page. There you will be able to create Categories, Forums, Groups, and Users. Don't forget to give write access to the webserver's user to the directories "images" and "tmp" (as well from its subdiretories, if any).

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.

Downloading JForum

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

Unpacking

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.

Directory permissions

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
Database configuration

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:

Database Key value
MySQL mysql
PostgreSQL postgresql
Oracle oracle
HSQLDB hsqldb

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:

Connection storage type Key value
Pooled Connections net.jforum.PooledConnection
Simple Connections net.jforum.SimpleConnection
DataSource Connections net.jforum.DataSourceConnection

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:

Key name Key value description
database.connection.username Database username
database.connection.password Database password
database.connection.host The host where the database is located
dbname The database name. The default value is jforum. All JForum tables are preceded by "jforum_", so you don't need to worry about conflicting table names.

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

Note for MySQL users

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= ).

Creating the database tables

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.

Populating the tables

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.

General configuration

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.

Security informations and considerations
  • 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.