Application server deployment
Unblu can be deployed on any Java application server (i.e., any server that functions as a Java Servlet Container, implementing the Java Servlet API). You should consult your application server documentation to get the specific installation directions.
Deploying Unblu on Tomcat
As an example, here we will describe the installation process on Tomcat.
At present, Unblu is not compatible with Tomcat 10, which targets Jakarta EE rather than Java EE. Unblu is compatible with Jakarta EE 8; it is not compatible with Jakarta EE 9 or 10. Deploy Unblu on Tomcat 9. |
Preparation
To begin with, you will need the following:
-
Suitable hardware on which to deploy the application server. See System requirements with no cluster.
-
Java 11 Unblu only targets long-term support (LTS) versions of Java. See Oracle’s Java SE Support Roadmap for further information.
-
An installed Tomcat server. Consult the Tomcat documentation for details on installation.
-
The Unblu WAR file, typically called
product.com.unblu-<version>-<guid>.war
-
The Unblu properties file, typically called
unblu-config.properties
The Unblu files should be provided to you by the Unblu delivery team.
Deployment
In Tomcat terminology $CATALINA_HOME is the Tomcat home directory. If your Tomcat is properly installed, this environment variable should point to the location of the Tomcat installation. |
Configuration file
To ensure that Unblu starts up properly upon deployment, you need to install the unblu-config.properties
file so that Tomcat reads it on startup. The recommended way of doing this is:
-
Copy
unblu-config.properties
to$CATALINA_HOME/conf
-
In the file
$CATALINA_HOME/bin/catalina.sh
insert the following line at the top of the file:export JAVA_OPTS="$JAVA_OPTS -Dcom.unblu.propertyoverlay=file:///$CATALINA_HOME/conf/unblu-conf.properties"
Once you have made this change, restart Tomcat.
Context path
In Tomcat (and other application servers), applications have a context path. This is simply the URI path (relative to the hostname of the server) where you point your browser to access the application. An application can be deployed either to the root context or a non-root context.
Assuming that the server is at http://<tomcat>/
then a typical non-root context for an Unblu install would be
`\http://<tomcat>/unblu/`
Alternatively, if Unblu were deployed to the root context then its URI would be identical to that of the Tomcat server itself:
`\http://<tomcat>/`
Non-root context deployment
To deploy to a non-root context, the simplest method is:
-
Rename the WAR file to
<path>.war
where path is the relative path at which you wish to deploy Unblu. Following the above example, we would simply rename the WAR file tounblu.war
. -
Ensure that Tomcat is running and copy the WAR file to the directory
$CATALINA_HOME/webapps/
. Tomcat should automatically unzip the WAR file and deploy the application. After a delay Unblu should be accessible athttp://<tomcat>/unblu
. -
Once deployed, you can safely delete the original WAR file
$CATALINA_HOME/webapps/unblu.war
.
Root context deployment
In Tomcat the root context app is found in the directory $CATALINA_HOME/webapps/ROOT
. By default this directory contains the Tomcat server management application. To install another app at this location you need to replace the contents of that directory with the app you want to deploy. If you still want to keep the Tomcat management apps you have to first rename the existing ROOT
folder. Assuming you want to keep the management apps, the following is the easiest way to deploy Unblu to the root context:
-
Stop Tomcat.
-
Rename
$CATALINA_HOME/webapps/ROOT
to something else, like$CATALINA_HOME/webapps/mgmt
. -
Copy the Unblu WAR file to
$CATALINA_HOME/webapps/`
asROOT.war
. -
Restart Tomcat.
-
Once deployed you can safely delete the original WAR file
$CATALINA_HOME/webapps/ROOT.war
.
Database
You can either use the approach outlined in the database configuration section or use the datasource provided by the application server to connect Unblu to a relational database.
com.unblu.storage.database.datasourceFactory=USE_PROVIDED
com.unblu.storage.database.datasourceName=jdbc/Unblu (1)
1 | JNDI name of the datasource |
Docker for rendered co-browsing
If you want your Unblu system to support either universal or document co-browsing (both types of rendered co-browsing) then you will need to provide access from the Unblu server to Docker host (either on the same machine or another). Unblu will use the Docker host to spawn headless browsers for the rendered browsing sessions. See Rendered co-browsing for more details.
See com.unblu.headlessbrowser.server.core.DockerClientConfiguration for information on how to enable the connection to the Docker host.
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
-
unblu-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
/app/
(locally) can be accessed viahttp://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
/app/
(locally) can be accessed viahttp://localhost:8080/unblu/
. -
The public path can be accessed via
http://localhost:8080/unblu/unblu/
.
For more information about internal and public entry paths, refer to Entry paths.
Test whether Unblu is running correctly
If Unblu is running correctly, you will see the login screen for the agent view. Log in with the username unblu
and the password secret
.
JavaScript demo page and documentation
If you need to use the Unblu JavaScript demo page, you can activate it by setting com.unblu.server.resources.enableDemoResources to true
. If you also want the Unblu docs available locally, set com.unblu.server.resources.enableDocResources to true
.