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 to unblu.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 at http://<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/` as ROOT.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.

Listing 1. Configure Unblu to use a datasource provided by the application server

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 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 /app/ (locally) can be accessed via http://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.