Some test text!

keyboard_arrow_down

Getting started

keyboard_arrow_down

Deployment options

keyboard_arrow_down

Webviewer Server

keyboard_arrow_down

Fundamentals

keyboard_arrow_down

Basics

keyboard_arrow_down

Annotations

keyboard_arrow_down

UI

keyboard_arrow_down

Legacy UI

keyboard_arrow_down

Advanced

keyboard_arrow_down

PDFNetJS Full

keyboard_arrow_down

PDF Processing API

WebViewer Server Configuration Options

In this document
chevron_rightHardware configuration
chevron_rightMinimum hardware requirements
chevron_rightNetwork configuration
chevron_rightSSL Config
chevron_rightScaling to multiple backend nodes
chevron_rightServer configuration
chevron_rightSupport for externally mapped static data drives
chevron_rightCustomize server URL
chevron_rightConfigure Docker container
chevron_rightRelative URL
chevron_rightDisable client side PDF access
chevron_rightDebug: disable client side rendering
chevron_rightDebug: disable HTTPS
chevron_rightAccess Control

linkHardware configuration

WebViewer Server manages its own work queues and caches a lot of intermediate data opportunistically locally, both in RAM and on disk. As such, having access to more system resources will allow the Server to operate more responsively and efficiently (using cached data improves response time, and also conserves CPU resources).

If your use case calls for multiple backend nodes, then a smaller number of more capable nodes is a better choice than a large umber of smaller nodes -- a 4 core/8GB server will have a higher peak user capacity than two 2 core/4GB servers.

linkMinimum hardware requirements

In order to maintain efficient operation, WebViewer server requires access to at least 2 CPU cores, at least 2GB of RAM, and 50GB of storage space. Anything less than 2 cores, and internal work queues will start to behave serially, which will drastically raise server response times.

Access to insufficient RAM limits the amount of data that can be held in the short-term cache, and it also limits the ability of the server to process particularly difficult documents.

If there is insufficient storage space, then the server will be unable to generate data without first pushing out existing cached data that is still in use by clients.

linkNetwork configuration

linkSSL Config

The WebViewer server comes with a self-signed certificate, usable for SSL debugging purposes only.

In order to have SSL work correctly on your own domain you must provide a certificate chain file. This certificate chain file should:

  • Contain within it a public certificate, an optional intermediary certificate and a private key in the pem format.
  • The private key must not have an associated password.
Excluding the intermediary certificate
If you do not include an intermediary certificate in your certificate chain file, SSL may not work correctly for users on Firefox.

Once the key is prepared you should:

  1. Place the key within the haproxy/ directory in the root directory.
  2. Set the SSL_CHAIN variable to the name of the certificate chain file in the docker-compose.yml file.

linkScaling to multiple backend nodes

The container (along with webviewer) now has built-in support for using multiple backends behind a load balancer.

As the container is not entirely stateless, the balancer needs to fulfill a few requirements:

  • operates at layer 7 (http)
  • supports instance affinity ("stickiness") via cookies.
  • supports http health checks at a specific path

There is a sample configuration included in the download archive which demonstrates a fully working load balancer setup. Running docker-compose -f docker-compose_load_balance.yml up will launch a container composed of two WebViewer Server nodes with an HAProxy load balancer front end.

In the sample setup, incoming connections are directed to the least occupied backend node, and will remain attached to that node for the remainder of the session, or until the node starts to become overloaded.

If there are no available healthy nodes, then WebViewer will attempt to continue in client-only rendering mode.

linkServer configuration

Server configuration is most easily done via docker-compose.yml, located in the root of the downloadable WebViewer server distribution. server environment variables can be set directly within that file.

linkSupport for externally mapped static data drives

It is possible to map the statically served data generated by the container to an external volume. The external folder must be granted full write access. See the commented out volumes: sections in both docker-compose.yml and docker-compose_load_balance.yml. Please be aware that the performance of this volume is critical to the performance of the server in general, and that the server operates under the assumption that the files will not be modified or locked by another process.

linkCustomize server URL

To access the server from a different internal URL, adjust the URL_PREFIX options in docker-compose.yml. For example, with the option value URL_PREFIX: custom-prefix, the demo would be available at http://localhost:8091/custom-prefix/demo/?s

linkConfigure Docker container

In order to adjust the capabilities of the built container, please see the following options in docker-compose.yml: LIBRE_SUPPORT, HTML_SUPPORT and INCLUDE_DEMO. Turning these options off will result in smaller built container.

linkRelative URL

If the server container has the environment variable TRN_FETCH_DEFAULT_BASE_ADDR set, then the url argument can start with a slash, in which case it will be appended to TRN_FETCH_DEFAULT_BASE_ADDR before fetching.

linkDisable client side PDF access

Setting the environment variable TRN_DISABLE_CLIENT_PDF_ACCESS will prevent the server from sending the PDF directly to the client, preferring other display modes instead (like server-side image rendering or .xod). Intended to protect sensitive documents by ensuring that only derived data (like rendered pages) are ever sent to the client.

linkDebug: disable client side rendering

setting the environment variable TRN_DEBUG_DISABLE_CLIENT_BACKEND_SWITCH in the server container will cause webviewer to stick with the server-rendering image backend and not switch to a more efficient client side option at any point. This option is for debugging only, as it may be removed in a future version.

linkDebug: disable HTTPS

If the environment variable TRN_FETCH_DOWNGRADE_HTTPS is set, then all fetches originating from the docker server will be made as http, rather than https.

linkAccess Control

During the course of normal operation, WebViewer server will generate content static content like rendered pages or document metadata and make it accessible to clients via an obfuscated URI. While this link is unguessable, it is not access-limited by default -- if a client shares or leaks the link, it could be accessible by third parties. If this is a concern, the environment variable TRN_ENABLE_SESSION_AUTH can be set. This will ensure that these URL are only to clients with currently connected WV sessions. This will add a small amount of overhead to each connection, and hinder the viewing of thumbnails in the demo application.