This document describes version 6 of Unblu. If you’re using the latest major version of Unblu, go to the documentation of the latest version.

The support period for version 6 ended on 29 August 2023. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu.

Configuring the Unblu Rendering Service

Document co-browsing and universal co-browsing both depend on the Unblu Rendering Service. This guide describes how to configure the Rendering Service.

Obtaining and running the Rendering Service Docker image

The Rendering Service application is provided as a Docker image. The Docker image is hosted in the Unblu container repository on the Google Container Registry at https://gcr.io/unblu-containerrepo-public.

The Collaboration Server uses the Docker API to manage Rendering Service containers. You needn’t run Docker containers yourself to use the Rendering Service.

Each instance of the Rendering Service runs in a separate container. In a cluster deployment, the container engine you choose must be one supported by Kubernetes. In all other deployment scenarios, the Rendering Service containers must run on the Docker Engine. Alternative container engines such as podman are not supported.

The DockerClientConfiguration section of the configuration properties reference provides further details on configuring Docker for the Collaboration Server.

Configure access to the Rendering Service

The configuration properties that influence access to the Renderings Service from the Collaboration Server are described in the HBRpcConfiguration section of the configuration properties reference.

The Collaboration Server communicates with the Rendering Service via gRPC. The Rendering Service acts as the gRPC server, the Collaboration Server is the gRPC client. com.unblu.hbrpc.port specifies the TCP port that the gRPC server is listening on.

If you are using a gRPC proxy, you must set the following configuration properties:

com.unblu.hbrpc.useProxyMode: If this property is true, the Collaboration Server will evaluate the property com.unblu.hbrpc.proxyAddress.
com.unblu.hbrpc.proxyAddress: The address of the gRPC proxy.

Configure exponential backoff retry policy

If an RPC to the Rendering Service fails, the Collaboration Server will retry the RPC based on an exponential backoff retry policy.

com.unblu.hbrpc.retryMaxAttempts specifies the maximum number of RPC attempts, including the initial RPC.
The following configuration properties determine the randomized delay for the RPC retry attempts:
- com.unblu.hbrpc.retryInitialBackoff: The upper bound, in milliseconds, before the first retry attempt
- com.unblu.hbrpc.retryMaxBackoff: The upper bound, in milliseconds, before subsequent retry attempts
- com.unblu.hbrpc.retryBackoffMultiplier: The multiplier used to calculate the lower bound before subsequent retry attempts
The actual delay before a retry attempt is calculated according to the method outlined here.
If the RPC was unsuccessful after the time specified in com.unblu.hbrpc.connectionAttemptTimeout (in milliseconds), the Collaboration Server’s gRPC client aborts.

Configure the pool of Rendering Service Docker containers

The Collaboration Server can create a pool of Docker containers running the Rendering Service Image. This significantly reduces the delay before universal and document co-browsing sessions can begin.

com.unblu.hbrunner.runnerStrategy: Which strategy the Collaboration Server to provision Rendering Service Docker containers. A number of the possible settings are intended for use in non-productive environments. The options most of interest in productive environments are:
- HB_RUNNER_NOPOOL_DOCKER: Launch Rendering Service containers when needed for a co-browsing session.
- HB_RUNNER_POOL_DOCKER: Create a pool of Rendering Service containers.
- HB_RUNNER_OPENSHIFT: Create a pool of pods running the Rendering Service container. This is the default setting if you are running Unblu in a cluster deployment.
The last two settings should be used for cluster deployments of Unblu.
com.unblu.hbrunner.hbPoolsize: The number of Rendering Service containers to provision. When a container is used for a document or universal co-browsing session, the Collaboration Server launches a new container and adds it to the pool.

Please refer to the HBRunnerStrategyFactory section of the configuration properties reference for further details.

Universal co-browsing configuration

There are a number of configuration properties that affect universal co-browsing.

Internet access for the Rendering Service

If the Rendering Service is used for universal co-browsing, the Rendering Service container needs HTTP(S) access to all web servers that should be available for universal co-browsing.

You can specify a proxy via which the browser launched by the Rendering Services should access web pages. Furthermore, you can bypass the proxy when accessing certain domains or hosts.

com.unblu.hbworker.httpProxyUrl: The URL of the HTTP forward proxy
com.unblu.hbworker.httpProxyExcludes: A list of hosts, domains, and rules for which to bypass the proxy settings. The format for the exclusion rules can be found here.

Restricting universal co-browsing access to websites

You can restrict the URLs for which universal co-browsing is permitted. For example, you can block certain protocols completely:

com.unblu.hbworker.javaScriptProtocolAllowed specifies whether access to javascript: URLs is permitted.
com.unblu.hbworker.localSitesAllowed defines whether it is possible to access URLs starting with file://.
com.unblu.hbworker.sslSitesAllowed allows you to block all SSL sites.

You can also block or permit domain patterns using regular expressions:

com.unblu.hbworker.urls.black: A deny list of regular expressions matching URLs that may not be accessed in universal co-browsing sessions.
com.unblu.hbworker.urls.white: An allow list of regular expressions matching URLs that may be accessed in universal co-browsing sessions.
com.unblu.hbworker.urls.order: The order in which the URL entered in the browser is compared with the regular expressions defined in com.unblu.hbworker.urls.black and com.unblu.hbworker.urls.white.

Note that the evaluation of URLs is not short-circuited. The URL entered is always compared to the regular expressions in both the allow list and the deny list.

For example, to allow universal co-browsing only for the English, Polish, and Swedish versions of Wikipedia, you could use the following configuration

Add http[s]://* to com.unblu.hbworker.urls.black.
Add http[s]://(en|pl|sv).wikipedia.org to com.unblu.hbworker.urls.white.
Set com.unblu.hbworker.urls.order to black,white.

If you don’t set the evaluation order to black,white, no websites will be accessible in universal co-browsing, including the ones in the allow list. This is because the URLs matched by the allow list are also matched by the regular expression in the deny list. The allow list must therefore be evaluated after the deny list.

Configure the TURN server

The Rendering Service needs access to a TURN server to relay the network traffic between the conversation participants. Please review the WebRTC configuration section of the configuration properties reference for a list of settings that must be set to ensure the Rendering Service can access the TURN server you choose to use.

Fonts in the Rendering Service

The Docker image for the Rendering Service contains a wide selection of font sets. Nevertheless, we recommend that you embed any fonts you use in the PDF files you create. This ensures that the files are displayed as you expect them to be.

You can review the fonts included in the Docker image by running a Rendering Service container interactively and launching /bin/bash to explore the image on the command line.