Some test text!

Hamburger Icon

Web / Guides / Configuration

WebViewer Server Configuration Options

In this document you will find all available WebViewer Server configuration options. All the options here are configured within the docker-compose.yml file. For more information on docker-compose, visit the Docker website.

Setting docker variables
When modifying Docker arguments and environment variables, booleans must be surrounded by single quotes, in this manner: 'true' or 'false'

Configuration for WebViewer

There are some options for the server which must be done before requesting a document render on WebViewer Side. For example

CAD Convert Options

Requires WebViewer >=10.1 and WebViewer Server >=2.1.3

CAD convert options are responsible for controlling how WebViewer Server renders AutoCAD documents. A detailed API for usage can be found here. These options can be passed into the loadDocument call after WebViewer initialization. These settings will be considered when caching the document.

WebViewer({ webviewerServerUrl }).then((instance) => {
  const cadOpts = new instance.Core.PDFNet.Convert.CADConvertOptions();
  // instance.Core.PDFNet.Convert.createCADConvertOptions().then((opts) => ...)
  cadOpts.setBackgroundColor({R: 255, G: 0, B: 0});
  instance.loadDocument(mydoc, { cadOptions: cadOpts });

Office Options

Office options are responsible for controlling how WebViewer Server renders Microsoft Office document formats. These options can be passed into the loadDocument call after WebViewer initialization. These settings will be considered when caching the document.

WebViewer({ webviewerServerURL }).then((instance) => {
  instance.loadDocument(mydoc, { officeOptions: { formatOptions: {
    ExcelMaxAllowedCellCount: 200000
  } } });

Rasterizer Options

Requires WebViewer >=10.1 and WebViewer Server >=2.1.3

Rasterizer options are responsible for changing how WebViewer displays documents and how WebViewer generates some output artifacts on initial load. In order to use them with WebViewer Server, you should set them on the loadDocument call instead of using updateRasterizerOptions.

These are documented here.

WebViewer({ webviewerServerURL }).then((instance) => {
  const { documentViewer } = instance.Core;
  instance.UI.loadDocument(file, {rasterizerOptions: {'colorPostProcessMode': 1}});

Server configuration

The options here can be configured by restarting the container with any changes. This can be done by restarting the container through docker-compose restart.

Server configuration is most easily done via docker-compose.yml, located in the root of the WebViewer Server zip. The configuration is handled through environment variables set in the container.

If you are using the containers withoutdocker-compose you can pass these variables through -e environment flags to docker directly as detailed here.

If you are using our Windows installer the process for setting these variables is documented here .

All possible variables for WebViewer Server are as follows:

General Options

Security Options

Deployment Options

Debug Options

General Options

Add Your PDFNet Key

To add your PDFNet key to the WebViewer Server the key must be set on the TRN_PDFNET_KEY option in docker-compose.yml (you do not need to set this property if you are demoing our software). This key must also be set in your WebViewer client constructor. This guide details how to add a license key to the constructor.

WebViewer Server Demo

WebViewer server comes with a demo that can be used for testing and debugging purposes. To remove this demo from the container set INCLUDE_DEMO to false. If not set to false, the demo is accessible at http://<HOST_IP_ADDRESS or localhost>:8090/demo?s

Customize 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://<HOST_IP_ADDRESS or localhost>:8090/custom-prefix/demo/?s

Configuring the maximum size of the local disk cache

TRN_MAX_CACHED_MB to configure the maximum size of the local disk cache before a cache deletion will occur. This should be set to 10% lower than the available space to WebViewer Server. Accepts a number in megabytes. Defaults to 10GB if not set. Has a minimum value of 1 GB. If set to -1, cache will not be cleaned unless total disk space is less than 1 GB. Refer to this guide for more info about cache interactions

We do not suggest setting this higher than 100GB as this can lead to excessive clean-up times

Configuring the maximum age of the local disk cache

TRN_MAX_CACHE_AGE_MINUTES determines how long the local disk cache will be kept before deletion. It accepts a number in minutes for deletion time with a minimum of 1 minute and a default of 30 minutes. Refer to this guide for more info about cache interactions .

Configuring the maximum age of the local memory cache

TRN_MAX_MEMORY_CACHE_AGE_MINUTES determines how long the local document will be kept in the in-memory cache before deletion. Setting this lower or higher will decrease or increase the speed at which your server uses memory. Setting this does not effect the disk cache. It accepts a number in minutes for deletion time with a minimum of 1 minute and a default of 1 minute. Refer to this guide for more info about cache interactions .

This should only be altered if you wish to increase memory usage or lower it. While the in memory cache can be deleted, a disk cache may still be available.

Force lossless images

Setting the environment variable TRN_FORCE_LOSSLESS_IMAGES to true will force the server to use lossless images when creating PDF image tiles. This option is required if performing differential layering with the WebViewer client to avoid image artifacts when highlighting document differences.

Disable client side rendering

Setting the environment variable TRN_DISABLE_CLIENT_SIDE_RENDERING to true 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 will create a greater load on the server.

Max Excel Cell Count

TRN_MAX_EXCEL_CELL_COUNT sets the upper limit for maximum unique cell count on an excel document. If a document sent to the server exceeds this cell count, the server will reject it.

Sometimes excel file's unique cell counts can exceed the millions and consume large amounts of memory. This option offers a way to prevent excessive memory usage on the server when processing excel documents of an unknown size. Their exact relation between memory and unique cells is as follows:

100,000 unique cells within an excel document = 400 MB of memory consumption during initial document processing

CAD XRef Config

TRN_CAD_XREF_CONFIG_URL allows for supporting external references inside of CAD files. Should be set to a server which returns JSON containing the location of the external files on the local WebViewer Server system. For more information, please refer to our FAQ on XRefs .

Change the internal data directory

This should not be changed unless absolutely required

TRN_INTERNAL_DATA_DIR sets the internal data directory for WebViewer Server. WebViewer Server must have access to this directory in order to function. This directory stores some log data and various operation files.

Change the HTTP data directory

This should not be changed unless absolutely required

TRN_DATA_STORAGE_DIR sets the HTTP data directory for WebViewer Server. WebViewer Server must have access to this directory in order to function. This directory stores all completed and processed documents. For more detailed information on setting this option visit our FAQ .

Disable the Watchdog Auto Restart

When TRN_DISABLE_WATCHDOG_RESTART is set to 'true' WebViewer Server will no longer attempt to auto restart itself after a crash. If enabling this, ensure your deployment system manages restarts based on container health or system status.

Health Failure Code

WebViewer Server returns a 500 HTTP error when a health check is failed. Setting TRN_HEALTH_FAILURE_CODE to an HTTP code will change what WebViewer Server responds with when a health check is failed.

Set the Default Office Locale

WebViewer Server allows setting language locales for office document conversions. To do so, set TRN_SET_LOCALE to a locale code listed here. Currently Arabic, Chinese, Dutch, English, French, German, Hebrew, Hindi, Japanese, Korean, Portuguese, Russian and Spanish are supported.

This will change how things like dates are ordered among other locale specific data.

It is also possible to set a per document locale when calling loadDocument from WebViewer, the following example shows how this can be done.

In WebViewer 8.3

    path: '../../../lib',
    webviewerServerURL: '',
).then((instance) => {
    instance.UI.loadDocument(url, {officeOptions: formatOptions: { locale: 'de-DE'}}); // sets it to the German locale

In WebViewer < 8.3

    path: '../../../lib',
    webviewerServerURL: '',
).then((instance) => {
    instance.UI.loadDocument(url, {officeLocale: 'de-DE'}); // sets it to the German locale

Changing the bound port

If you change your port bound on Tomcat from 8090 to another port, you should also set TRN_RUNNING_PORT_NUM to the value you have set it to. This should only be done when using the Windows installer and changing the Tomcat port normally via the tomcat apache-tomcat/conf/server.xml. If not done, the health check will fail.

Changing the localhost URL

If your environment happens to alter how localhost binding generally works this can cause the server's internal health check to fail, which relies on a localhost URL request. By default this value is set to Changing this value may fix issues where the healthcheck is failing with 403 or 404 errors in your server logs.

Using z-order for text

Requires WebViewer >= 10.7 and WebViewer Server >= 2.2.0

TRN_TEXTEXT_EX_USING_ZORDER set to true to use z-order (aka paint order) as the reading order for text.

Security Options

Fetch Timeout

If the server has the environment variable TRN_FETCH_TIMEOUT_MS set, the server will set the timeout to the value specified in milliseconds. This value is the time it takes before a timeout occurs when opening a connection and when waiting for the first byte of a requested file. The default value is 20000 milliseconds.

HTML2PDF Timeout

HTML2PDF conversions have a seperate timeout controlled by TRN_HTML2PDF_TIMEOUT defined in milliseconds. This defaults to 300000 milliseconds (5 minutes). This effects conversions for .eml.msg.html.url files.

Relative URL

If the server container has the environment variable TRN_FETCH_DEFAULT_BASE_ADDR set, any incoming URL to the server will be TRN_FETCH_DEFAULT_BASE_ADDR + the incoming url when the server attempts to fetch it.

URL root restriction

If the server container has the environment variable TRN_FETCH_REQUIRED_URL_ROOTS set, then each URL will be checked against its value before initiating any fetch routine. You may specify more than one possible URL root by seperating addresses with semicolons:


This check is done after any URL alteration performed due to the above TRN_FETCH_DEFAULT_BASE_ADDR option. For example, if TRN_FETCH_REQUIRED_URL_ROOTS ==, then the document would be be allowed, but both and would fail. The protocol is not part of this check, and will be ignored if it is included in TRN_FETCH_REQUIRED_URL_ROOTS.

Same domain cookie forwarding

If the server container has specified TRN_FORWARD_CLIENT_COOKIES as true, cookies a client has received from another server on the same domain will be shared with the WebViewer Server. This can allow cookie based authorization schemes to pass their cookies for the server to use.

Force URL Rechecking

TRN_FORCE_URL_RECHECK should be set to true if you want to check the accessiblity of a document's original url whenever performing an action with this document. This ensures the document is still accessible to the user requesting it, preventing them from gaining access to documents that may have expired.

Restrict client origins

TRN_ALLOWED_ORIGINS should be set to the origin of the site your clients will be accessing WebViewer from. This will ensure WebViewer Server will only accept requests from that site. If this option is not defined, any origin is allowed.

This option can be passed domains seperated by a comma. You may use the wildcards * to represent multiple (0 or more) wildcard characters and ? to represent a single (0 or more) wildcard character.


With wildcards

TRN_ALLOWED_ORIGINS: *//,https://amazon.*

Disable client side PDF access

Setting the environment variable TRN_DISABLE_CLIENT_PDF_ACCESS to true 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.

Access Control

Locks user document links to user sessions so they are inaccessible to other users with the document link while the original document owner is disconnected. Set TRN_ENABLE_SESSION_AUTH to true to enable this feature.

During the course of normal operation, WebViewer server will generate static content like rendered pages or document metadata and make it accessible to clients via an obfuscated URI. This link is hashed and obfuscated -- if a client shares or leaks the link, it could be accessible by third parties. By enabling the option, it will ensure that this URL is only accessible to those with the link while the client is actively connected.

It is possible to access the authentication token client side by calling the following API:

  pdftronServer: "http://localhost:8090",
  path: '/lib',
}, document.getElementById('viewer')).then(instance => {
	const { docViewer, annotManager } = instance;
	docViewer.on("documentLoaded", () => {
		const doc = docViewer.getDocument();
		console.log("the auth id: " + doc.getAuthId());

Session caching

By setting TRN_ENABLE_PER_SESSION_CACHING to true, cached files will be stored behind a session identifier path on the server. Enable this with TRN_ENABLE_SESSION_AUTH for completely user session secure documents. This will prevent the server from allowing clients who request a document, that has already been fetched, from accessing a version cached by a different user. With these features both enabled, most caching will be disabled and the server will take a performance hit.

Disable fetch validation

TRN_DISABLE_VALIDATION should be set to true to disable HTTPS link validation. HTTPS link validation is done whenever a file url is passed to WebViewer Server. Enabling this option will leave your system unsecure, but will allow for fetching of file urls with invalid certificates. This should only be used if your setup has been properly secured for this scenario or you are testing the server without public access.

Strip URLs from logs

TRN_STRIP_URLS when set to true will remove URL information from fetched links in the server logs. This should only be enabled if you need information security on internal file server fetches.

Block domains for file fetches

TRN_BLOCKED_DOMAINS when set to true will prevent the server from performing file fetches that contain the terms provided in TRN_BLOCKED_DOMAINS. These terms should be seperated by a comma (,). If the URL that is being fetched contains one of these domains, it will be blocked.


TRN_DISABLE_JSESSION disables Tomcat's usage of JSESSION. This should not be used with TRN_ENABLE_AUTH_SESSION. This should only be used if you find WebViewer Server is overwriting your own JSESSION cookie inside of your environment.


Hide product key in logs

SHOULD_HIDE_PRODUCT_KEY hides the Apryse license key inside of logs if set to true

Deployment Options

Client stickiness refresh

If running the server in a distributed environment we offer an argument for improving user stickiness when using cookies to manage stickiness. Set `TRN_BALANCER_COOKIE_NAME** to the name of your stickiness cookie. Once set, WebViewer will delete the stickiness cookie whenever opening a new document. This allows users to only be stuck on a particular server on a per document basis.

In order to use this option your environment must allow WebViewer Server to delete cookies server side.

Readable timestamps on Windows WebViewer Server

Windows Installer Only

By default timestamps appear in the UNIX time format. When using Docker this timestamp is automatically converted. To do the same on Windows, you should set the option TRN_FORCE_READABLE_TIMESTAMPS to true.

Debug Options

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.

Disable backend switch

If the environment variable TRN_DEBUG_DISABLE_CLIENT_BACKEND_SWITCH is set to true WebViewer and WebViewer Server will only use image renders of a document. This option can be very taxing on the server and will require a far stronger server than WebViewer Server would normally require. Not recommended for production usage.

Debug Mode

If the environment variable TRN_DEBUG_MODE is set to true WebViewer Server will output more logs than normal and allow the execution of dangerous tasks for debugging purposes.

Get the answers you need: Chat with us