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.
Preparation
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 asunblu.war.
- Start Tomcat either by using Tomcat scripts (
startup.sh
) or by using another system service such as systemctl.
Deploying in Root Context
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.
Copy the (unblu server) WAR file to the webapps folder as
ROOT.war.
Start Tomcat either by using Tomcat scripts (
startup.sh
) 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
- After starting Tomcat, switch to the folder you configured for logging. You will find 3 files,
unblu.datestamp.log,
unblu-fatal.datestamp.log
andunblu-session.datestamp.log.
- 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
- If you deployed unblu in root context, then:
- the restricted unblu path "/co-unblu/" (locally) can be accessed via http://localhost:8080
- the public unblu path can be accessed via http://localhost:8080/unblu/
- If you deployed unblu in a non-root context (let's say as
unblu.war
), then:- the restricted unblu path "/co-unblu/" (locally) can be accessed via http://localhost:8080/unblu/
- the public path can be accessed via http://localhost:8080/unblu/unblu/
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 unblu.properties 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 offile:///full/path/to/unblu.properties.
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/unblu.properties"
Note: In a default Tomcat installation you can put the command at the top of the catalina.sh
file
<tomcatHome>/bin/catalina.sh
so that it is always executed when Tomcat starts.
Further Reading
- deployonprem