Configuring the Rendering Service
Server-based document co-browsing, universal co-browsing, and conversation recording all depend on the Unblu Rendering Service. This article 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 aren’t 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.
If you use Unblu’s conversation recording or whiteboard feature, you must also provide the Rendering Service with the base URL of the entry point to access the Collaboration Server:
-
com.unblu.identifier.recordingEntryPointBaseUrl
-
com.unblu.identifier.whiteboardEntryPointBaseUrl
In most cases, the value of the two configuration properties will be the same.
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 co-browsing and server-based 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.
For more information, refer to the HBRunnerStrategyFactory section of the configuration properties reference.
Universal co-browsing configuration
Most of the configuration properties for universal co-browsing are described in the article Configuring the universal co-browsing collaboration layer. There are, however, also a number of Rendering Service 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’s 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 isn’t 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. 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.