Enable universal and document co-browsing

1. Introduction

The information on this page assumes you are already familiar with how to set up and configuring an unblu collaboration server, please read Unblu Server Setup and Unblu Server Configuration.

In order to be able to use universal co-browsing and/or document sharing in an unblu collaboration server running on your application server, the unblu/renderingservice appliance is required.

This page describes how the unblu/renderingservice appliance is installed, configured and made known to the unblu collaboration server.

2. Preconditions

2.1. Docker

The unblu/renderingservice appliance is based on docker https://www.docker.com. In order to install and run the unblu/renderingservice appliance, you need a docker engine installation where you can start a container from the unblu/renderingservice docker image available on docker hub( https://hub.docker.com/r/unblu/renderingservice).

For more information on how to install and run a docker engine please visit https://docs.docker.com.

2.2. Unblu collaboration server

The unblu/renderingservice appliance is a helper appliance that augments the unblu collaboration server with additional capabilities (universal co-browsing and document sharing) hence you need to have an unblu collaboration server installed in order to make use of the unblu/renderingservce virtual appliance. Please read Setting up enterprise On Premise for more information on how to install, configure and run the unblu collaboration server on the application server of your choice.

2.3. Network connectivity

Enabling universal co-browsing and or document sharing using the unblu/renderingservice adds the following network connectivity requirements:

2.3.1. SSH unblu collaboration server to unblu/renderingservice

The unblu collaboration server must be able to connect to the unblu/renderingservice using the SSH protocol on a tcp port on the docker host that is mapped to the tcp port 22 in the unblu/renderingservice container.

2.3.2. HTTP(s) from the unblu/renderingservice to the unblu collaboration server

The unblu/renderingservice container must be able to connect to the unblu collaboration server using http(s) using the url provided in the com.unblu.hbworker.headlessBrowserReverseBaseUrl configuration property (see below).

The unblu/renderingservice uses the WebSocket protocol over the given HTTP(S) connection thus there should be no proxies on the way or they must also support the HTTP UPGRADE header and the WebSocket protocol.

2.3.3. HTTP(S) unblu/renderingservice to internet / intranet

If the unblu/renderingservice is used for universal co-browsing, then the unblu/renderingservice container needs to be able to access all web servers (using HTTP(S)) that need to be available in the universal co-browsing. Please note that this requirement does not apply, when the rendering service is only used for document co-browsing.

3. Configure and run the unblu/renderingservice appliance

The unblu/renderingservice appliance is installed / started using the docker command line tool with the following command:

Create and start the renderingservice container
# <name>: name of the docker container that is created on the docker host 
# <port>: tcp port mapping for the unblu/renderingservice on the docker host 
#         (the unblu collaboration server will connect to the 
#          unblu/renderingservice trough this tcp port)
# <password>: password for the unblu collaboration server to connect to 
#             the unblu/renderingservice
docker run -d --name <name> -p <port>:22 -e PASSWORD=<password> unblu/renderingservice

This command creates and starts a container from the unblu/renderingservice image on the docker host.

The container can then be stopped using:

Stopping the renderingservice container
# <name>: name of the docker container as given in the "docker run" command above
docker stop <name>

...and started again using:

Starting the reneringservice container
# <name>: name of the docker container as given in the "docker run" command above
docker start <name>

The unblu/renderingservice docker image is stateless and does not store any persistent data thus it is also possible to use a transient container (create a new container on every start of the system) instead of using a persistent container.

Stop and remove the renderingservice
# <name>: name of the docker container as given in the "docker run" command above
docker -t 10 stop <name>; docker rm -f <name>


4. Configure the unblu collaboration server to use the unblu renderingservice

Once the renderingservice is installed and started, the unblu collaboration server can be configured to use the renderingservice with the following configuration properties:


# <collaborationServerBaseUrl>: fully qualified base url of the unblu 
#          collaboration server (reachable from the renderingservice), 
#          i.e. https://unbluserver.mycompany.com 
#          (format: <protocol>://<host>[:<optionalPort>]
# <dockerHost>: host name or IP of the docker host where the unblu/renderingservice 
#               container is running
# <renderingServicePort>: tcp port of the unblu/renderingservice container 
#                         as mapped using the -p <renderingServicePort>:22 
#                         argument in the "docker run" command
# <password>: the password of the unblu/renderingservice


While the above block deals with the technical requirements to establish connections between unblu collaboration server and rendering service, the following property is required to enable universal and document co-browsing in unblu as a whole:

# enable universal co-browsing options in agent desk

5. Test connectivity

Once docker has been started with docker run (see above), try to connect from the collaboration server into docker as follows:

Connecting to the docker image
# <port>: port on which docker host is providing access to the image 
#         (corresponds to <port> from docker run command)
# <dockerHost>: host name or IP of the docker host where the 
#               unblu/renderingservice container is running
# <password>: the password specified when starting the unblu rendering service 
#             with docker run
ssh -p <port> unblu@<dockerHost>
Password: <password>


Within the docker image, you should also check, whether the connection back to the collaboration server works. For that purpose, make sure, the collaboration server has been successfully started. Once it is started, login to the docker image using ssh (see above) and execute:

Connecting back to collaboration server
# <collaborationServerBaseUrl>: fully qualified base url of the unblu collaboration server. 
#                               Must eventually match with what's specified in the 
#                               unblu.properties file 
#                               (see com.unblu.hbworker.headlessBrowserReverseBaseUrl 
#                               above) 
curl <collaborationServerBaseUrl>/sys-unblu/rest/product/all
# example output from the above command:
product.com.unblu.enterprise.universe.staticusers_4.1.7.RELEASE MAIN


6. Troubleshooting

Some other network diagnostic tools that may help to analyze problems, when you're connected with SSH into the unblu docker image

Example diagnostic tools
# check if dns lookups work
# <collaborationServerHostname>: Hostname or IP of the unblu collaboration server
nslookup <collaborationServerHostname>
# check if ping works. Note: must be called with sudo. Operation is not permitted otherwise.
# <collaborationServerHostname>: Hostname or IP of the unblu collaboration server
sudo ping <collaborationServerHostname>