Ultra Quick Server Installation (less than 5 minutes)

This page describes how to setup the embedded HiveBoard server in just a few minutes.

Important! If you have already installed a previous version of HiveBoard, then you will need to reinstall the complete HiveBoard Application Server as described below.

1. Pre-requisites

The only pre-requisite in order to install HiveBoard embedded server is a Sun JRE (Java Runtime Environment) 5 or later installed on your server (you can get it from this location).

Unzip the HiveBoard binary distribution (hiveboard-embedded-server-bin-0.6.0.tar.bz2) into a directory on your server. The distribution includes the following sub-directories:

hb-embedded-server-bin/bin: all necessary files to setup and launch the client application.
hb-embedded-server-bin/docs: copy of the HiveBoard web site and a few text files (release notes...)

2. Launch the HiveBoard server

If your OS supports executable jar files (eg Windows XP), then you can directly double click the hb-embedded-server-bin/bin/start.hiveboard.server.jar to launch the HiveBoard server. After a couple of seconds, the server should be up and ready to accept clients login.

To quickly check if launch was successful, you can take a look (with any text editor) at the log files produced by the server:

hb-embedded-server-bin/bin/logs/hiveboard.log: this is the main log file produced by HiveBoard. After a successful launch, this file should contain a bit more than 100 lines. Except for the first log line, there should be no "ERROR". Note that the first "ERROR" line is not actually an error. Pay attention to the fact that the size of that file will increase automatically even when no HiveBoard client is connected to the server.
hb-embedded-server-bin/bin/logs/hiveboard-jetty.log: this is the log file produced by the Jetty servlet container (the server in which HiveBoard application is embedded). Its content would be worth examining only in the situation where no hiveboard.log at all could be produced. In normal situations, after first launch, the content of that file should be a few "Info" lines only.

Another way to check if the server was launched successfully is to try and connect an HiveBoard client to it, as described in Client Installation. But examining the log files is generally faster for a first diagnosis.

If your OS does not support executable jar files, then you need to open a terminal window and type:

cd hb-embedded-server-bin/bin
java -jar start.hiveboard.server.jar

Now you are finished with the server installation!

3. Advanced Setup (optional)

Normally, default server configuration will suit your needs. However, you may want more avdanced settings to fit more specific requirements.

All the configuration of HiveBoard embedded server can be found in hb-embedded-server-bin/bin/etc. This directory contains several files, but only a few are really interesting for advanced setup:

hiveboard.properties: this file contains several properties that are unique to one deployment site.
log4j.xml: this file defines logging setup (for log4j tool).
log4j-*.xml: these files define sample 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. In order to use one or the other, you just have to copy it to overwrite log4j.xml.

First of all, you may want to set properties in hiveboard.properties: in addition to several values that should not be changed, this file contains a few parameters that help tune performance and memory consumption on the server. It has full comments about the meaning of each property.

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, 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 the absolute path to hb-embedded-server-bin/bin/logs.

Finally, if you want to use secure connections between clients and server, then you will have to tweak a little bit with jetty-server.xml configuration file (refer to Jetty web site for more information). Additionally, you will have to modify the "use.https.exclusively" property in hiveboard.properties file.