Server Installation

You have just downloaded the binaries of HiveBoard (hiveboard-bin-0.6.0.tar.bz2) and you want to install it on your current web server (servlet container)? This page is for you!

Please note that if you have no servlet container installed on your server, an easier solution to install HiveBoard server is to use the embedded server (as described there).

This page describes step by step what you will have to do to install HiveBoard server.

1. Pre-requisites

First of all, you need to have a Sun JDK (Java Development Kit) 5 or later installed on your server (you can get it from this location.

Then you must have a Servlet Container (compliant to Servlet Specifications 2.3) installed on your machine. Currently, HiveBoard 0.6.0 has been tested on the following containers:

You must also have an SQL Database server installed and running on your machine (or another machine accessible through the network, but it is preferrable to have the database engine on the same machine for performance reasons and because setup is generally easier). Currently, HiveBoard 0.6.0 supports (and has been tested on) the following engines:

Please note that if you start the SQL engine and the servlet container as daemons (Unix) or services (Windows), then you need to make sure that the SQL engine starts before the servlet container.

Check that you have the JDBC driver that matches your SQL engine:

Connector/J 5.0 for MySQL
postgresql-8.2-jdbc3 for PostgreSQL
hsqldb.jar for HSQLDB
derbyclient.jar for Derby

Unzip the HiveBoard Server binary distribution (hiveboard-server-bin-0.6.0.tar.bz2) into some directory. The distribution includes the following directories:

hb-server-bin: contains HiveBoard server war file (to be deployed to a servlet container).
hb-server-bin/docs: copy of the HiveBoard web site and a few text files (release notes...)
hb-server-bin/etc: contains various configuration files that will have to be modified then used for HiveBoard server deployment.
hb-server-bin/initdb: contains subdirectories (one per supported database engine) with SQL scripts to create the HiveBoard database.

2. Setup the HiveBoard database

If you use MySQL, follow this step.

If you use PostgreSQL, then follow that step.

If you use HSQLDB, then follow that step.

If you use Derby, then follow that step.

3. Setup the HiveBoard Web Application server

The full HiveBoard server application is contained within a single war file: hiveboard-bin/server/hiveboard.server.war. In order to deploy this file to a Servlet Container, several configuration steps must be taken. All configuration happens in files located in hiveboard-bin/server/etc:

hiveboard.properties: this file contains several properties that are unique to one deployment site.
log4j-*.xml: these files define logging setup (for log4j tool). One file is most useful for testing while the other removes lots of traces and is useful for production sites.
tomcat-context.xml: this file is used for Tomcat deployment; it contains a few properties that need setting beforehand.
jetty-hiveboard.xml: this file is used to hot-deploy HiveBoard on Jetty.

First of all, you need to set properties in hiveboard.properties: the minimum to specify is the connection information to the HiveBoard database. The file also contains a few parameters that help tune performance and memory consumption on the server. It has full comments about the meaning of each property. For most properties, default values are good for a quick start.

For database connection, you must properly set all properties beginning with "db." prefix. If you have MySQL database, those properties will look like this:

db.type=mysql
db.driver=com.mysql.jdbc.Driver
db.url=jdbc:mysql://localhost/hiveboard
db.user=root
db.password=
db.exception.mapper=hivetranse.core.exceptions.MySQLMapper

If you use PostgreSQL, you would have setting like the following:

db.type=postgres
db.driver=org.postgresql.Driver
db.url=jdbc:postgresql://localhost/hiveboard
db.user=postgres
db.password=postgres
db.exception.mapper=hivetranse.core.exceptions.PostgreSQLMapper

If you use HSQLDB, you would have setting like the following:

db.type=hsqldb
db.driver=org.hsqldb.jdbcDriver
db.url=jdbc:hsqldb:hsql://localhost/hiveboard
db.user=sa
db.password=
db.exception.mapper=hivetranse.core.exceptions.HSQLDBMapper

Finally, if you use Apache Derby, you would have setting like the following:

db.type=derby
db.driver=org.apache.derby.jdbc.ClientDriver
db.url=jdbc:derby://localhost/hiveboard
db.user=hiveboard
db.password=hiveboard
db.exception.mapper=hivetranse.core.exceptions.DerbyMapper

Please note that all these settings are already defined in hiveboard.properties but they are commented out for some SQL engines. You just have to comment out the properties that do not apply for your SQL engine and uncomment those which apply, then modify only the following properties according to your current installation:

db.url
db.user
db.password

Then you may want to specify specific logging setup (for log4j). There are 2 files, first you need to choose one for your site deployment. When installing for the first time, i{log4j-test.xml} would be a good option (but it will quickly generate huge log files if the system is used regularly). Normally, you would not change the file's content. However, there may be one property you might wish to change:

<appender name="logfile" class="org.apache.log4j.DailyRollingFileAppender">
    <param name="File" value="${logdir}/hiveboard.log"/>
    <param name="DatePattern" value="'.'yyyy-MM-dd"/>
    <layout class="org.apache.log4j.PatternLayout">
        <param name="ConversionPattern" value="%d{ABSOLUTE} %5p [%x] %c - %m%n"/>
    </layout>
</appender>

Basically, this property defines 2 things:

where to put the log file (and how to create log files)
how to format the messages in the log file

If you know enough about log4j, then you may change this property.

In the sample above, ${logdir} is a placeholder that will be replaced at runtime by any directory you want. By default, this placeholder will refer to the Tomcat or Jetty logs directory.

The last configuration step for the servlet container depends on the container you use.

If you use Tomcat, follow this step.

If you use Jetty, then follow that step.

To make sure that everything went fine, you should take a look in the Tomcat logs or Jetty logs directory and check the hiveboard.log file (that should have been created if there was no big mistake) or the other various log files there (if there was a big problem).

Check that, besides the first "ERROR' line (which is actually not an actual error), no "ERROR" message was logged in hiveboard.log. Under normal circumstances (and when using log4j-test.xml log config file), that file should be roughly 50 to 100 lines long (beware that its size will grow even if nothing happens).

Now you are finished with the server installation!

Please note that although HiveBoard 0.6.0 is a very stable and complete system, it still requires quite some setup before running; hopefully, future versions will provide simpler installation for HiveBoard server. However, do not forget the other way, quicker (and preferred), to install HiveBoard server through the "embedded" version.