Installing on Tomcat

This section describes how to install unblu on an existing Tomcat server. The installation described here aims to provide a straightforward way to ensure that unblu runs on the server. Depending on your server environment and your practices, you may choose to deviate from the steps suggested here.

Note: This example, using Tomcat, is designed as an illustrative guide only. unblu can be installed on virtually any web container. You should consult your web container’s documentation to get the specific information you need to get up and running.

NOTE: Before starting the installation you should be clear as to whether you want to install unblu in root context or not. For example, if you want easy access to Tomcat's GUI (Tomcat Manager default page) to control other applications, as well as unblu, then you should install in non-root context.

Deploying unblu Server on Tomcat

Note: This deployment is performed with the Tomcat default server configuration; this means no port or other changes are made to the server.xml file.


  • You will need the unblu server, which is delivered as a WAR or EAR file. For Tomcat you will need the unblu server as a WAR file.

    Ensure you have the correct version of the unblu server. If in doubt, contact our support and service team.

  • Copy the WAR file to the file system of the host where Tomcat runs.

  • Next, you will need a configuration file. Keep in mind that any version of unblu ≥ 4.2 requires a database. For database configuration see Introduction to the Database.

  • You will also need to define an output directory for logging. See Logging.

  • The configuration file can be passed to the unblu server using JAVA Options. See Configuration.

  • Finally, you will need to decide whether you want to deploy unblu in root or in non-root context.

    Deploying in non-Root Context

  • Switch to Tomcat webapps folder (for example, $TOMCAT_HOME/webapps).

  • Copy the (unblu server) WAR file, to the webapps folder in whatever context you want to deploy unblu. For example, if you want to deploy the unblu server as unblu, then copy the file as unblu.war.
  • Start Tomcat either by using Tomcat scripts ( or by using another system service such as systemctl.

Deploying in Root Context

  1. Switch to the Tomcat webapps folder (for example, $TOMCAT_HOME/webapps).

    Depending on whether you will need to access to the Tomcat default (manager) application, delete or move or rename the existing ROOT folder.

  2. Copy the (unblu server) WAR file to the webapps folder as ROOT.war.

  3. Start Tomcat either by using Tomcat scripts ( or by using another system service such as systemctl.

Note: You can, if you wish, delete the WAR file in the webapps folder.

Note: If you are installing unblu in root context, only one file called ROOT.war can exist. (In this case it will be the unblu war file.)

Check the Server Logs

  1. After starting Tomcat, switch to the folder you configured for logging. You will find 3 files, unblu.datestamp.log, unblu-fatal.datestamp.log and unblu-session.datestamp.log.
  2. Check the file unblu.datestamp.log, to see whether the server started normally or if there are any configuration or DB connectivity issues.

Accessing the unblu Server

  1. If you deployed unblu in root context, then:
  2. If you deployed unblu in a non-root context (let's say as unblu.war), then:

Note: For more on restricted and public entry paths see System Entry Path Concept.

Test Whether unblu Runs Correctly

If unblu runs correctly, you will see the login screen for the agent view.

Login with the username unblu and the password secret. unblu displays the code screen.

Enable a Configuration File for unblu

  • If you have received an file for your installation, put the file into the folder of the Tomcat server, for example into the conf folder. Make sure that the file can be read by the user running the Tomcat server.
  • If you have not received a file, create a new empty text file where you can store the configuration entries.
  • To enable the properties file you need to define a Java system property named com.unblu.propertyoverlay that contains a link to the configuration file, in the form of file:///full/path/to/ In a default Tomcat installation you can do so with the following command:
export JAVA_OPTS="$JAVA_OPTS -Dcom.unblu.propertyoverlay=file:///full/path/to/"

Note: In a default Tomcat installation you can put the command at the top of the file


so that it is always executed when Tomcat starts.

Further Reading

Order of Deployment


Migrating to a New Version

  • deployonprem

results matching ""

    No results matching ""