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.

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

• CADConvert Options
• Office Options
• Rasterizer Options

Requires WebViewer >=10.1 and WebViewer Server >=2.1.3

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

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

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.

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

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.

Find more on our API docs covering rasterizer options.

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

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 -eenvironment flags to docker directly.

If you are using our Windows installer, see related guides for the process for setting these variables.

All possible variables for WebViewer Server are as follows:

General Options

• TRN_PDFNET_KEY
• INCLUDE_DEMO
• URL_PREFIX
• TRN_MAX_CACHED_MB
• TRN_MAX_CACHE_AGE_MINUTES
• TRN_MAX_MEMORY_CACHE_AGE_MINUTES
• TRN_FORCE_LOSSLESS_IMAGES
• TRN_DISABLE_CLIENT_SIDE_RENDERING
• TRN_MAX_EXCEL_CELL_COUNT
• TRN_CAD_XREF_CONFIG_URL
• TRN_INTERNAL_DATA_DIR
• TRN_DATA_STORAGE_DIR
• TRN_DISABLE_WATCHDOG_RESTART
• TRN_HEALTH_FAILURE_CODE
• TRN_SET_LOCALE
• TRN_RUNNING_PORT_NUM
• TRN_LOCALHOST_URL
• TRN_TEXTEXT_EX_USING_ZORDER
• TRN_ENABLE_PROMETHEUS

Security Options

• TRN_FETCH_TIMEOUT_MS
• TRN_HTML2PDF_TIMEOUT
• TRN_FETCH_DEFAULT_BASE_ADDR
• TRN_FETCH_REQUIRED_URL_ROOTS
• TRN_FORWARD_CLIENT_COOKIES
• TRN_FORCE_URL_RECHECK
• TRN_ALLOWED_ORIGINS
• TRN_DISABLE_CLIENT_PDF_ACCESS
• TRN_ENABLE_SESSION_AUTH
• TRN_ENABLE_PER_SESSION_CACHING
• TRN_DISABLE_VALIDATION
• TRN_STRIP_URLS
• TRN_BLOCKED_DOMAINS
• TRN_ALLOWED_DOMAINS
• TRN_DISABLE_JSESSION
• SHOULD_HIDE_PRODUCT_KEY

Deployment Options

• TRN_BALANCER_COOKIE_NAME
• TRN_FORCE_READABLE_TIMESTAMPS

Debug Options

• AWS_ERROR_REPORTING
• TRN_FETCH_DOWNGRADE_HTTPS
• TRN_DEBUG_DISABLE_CLIENT_BACKEND_SWITCH
• TRN_DEBUG_MODE

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 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

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

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

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

WebViewer Server allows setting language locales for office document conversions. To do so, set TRN_SET_LOCALE to a locale code. 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

1WebViewer(
2  {
3    path: '../../../lib',
4    webviewerServerURL: 'https://demo.apryse.com/',
5  },
6  document.getElementById('viewer')
7).then((instance) => {
8    instance.UI.loadDocument(url, {officeOptions: formatOptions: { locale: 'de-DE'}}); // sets it to the German locale
9})

In WebViewer < 8.3

1WebViewer(
2  {
3    path: '../../../lib',
4    webviewerServerURL: 'https://demo.apryse.com/',
5  },
6  document.getElementById('viewer')
7).then((instance) => {
8    instance.UI.loadDocument(url, {officeLocale: 'de-DE'}); // sets it to the German locale
9})

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.

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 0.0.0.0. Changing this value may fix issues where the healthcheck is failing with 403 or 404 errors in your server logs.

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.

Prometheus is a metric monitoring tool which WebViewer Server now supports an integration with. This integration can be enabled by setting TRN_ENABLE_PROMETHEUS to true. The metrics enabled by this option will be available at domain/blackbox/metrics and will return Prometheus formatted text data. This API can be put into your Prometheus server as a target. The server will return the following information to Prometheus, with the first value being the metric name and the values after being the key types for this metric.

• Base server information: software_info - id, os_version, main_thread_pool_size
• Hardware information: hardware_info - num_cpu_cores, total_memory
• Version information: version_info - wvs_version, build_version
• CPU usage: cpu_usage_percent
• Memory usage: mem_free_mb
• Internal job queue sizes: queue_sizes - queue_types (main, convert and fetch queue)
• Internal job queue delays for each of the 5 timing windows: queue_delay_times - window (50ms, 2000ms, 5000ms, 30000ms, 60000ms)
• How health checks are responding determined from an internal perspective: health_responses

The API will still be available with this set to false but will not collect metric data.

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 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.

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.

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:

TRN_FETCH_REQUIRED_URL_ROOTS: www.test.com;www.pdftron.com;www.google.com

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 == my.domain.com/subpath, then the document http://my.domain.com/subpath/doc.pdf would be be allowed, but both http://my.domain.com/doc.pdf and http://my.other.domain.com/subpath/doc.pdf would fail. The protocol is not part of this check, and will be ignored if it is included in TRN_FETCH_REQUIRED_URL_ROOTS.

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.

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.

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.

TRN_ALLOWED_ORIGINS: https://pdftron.com,https://amazon.com

With wildcards

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

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.

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:

1Webviewer({
2  pdftronServer: "http://localhost:8090",
3  path: '/lib',
4}, document.getElementById('viewer')).then(instance => {
5	const { docViewer, annotManager } = instance;
6	instance.loadDocument(url);
7	docViewer.on("documentLoaded", () => {
8		const doc = docViewer.getDocument();
9		console.log("the auth id: " + doc.getAuthId());
10	});
11});

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.

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.

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.

TRN_BLOCKED_DOMAINS when provided domains will prevent the server from performing file fetches that containing 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. You may use the wildcards * to represent multiple (0 or more) wildcard characters and ? to represent a single (0 or more) wildcard character.

1TRN_BLOCKED_DOMAINS: "google.com,yahoo.com,bing.com, *.my.domain/*"

TRN_ALLOWED_DOMAINS when set to a list of domains, will only allow the server to fetch files which follow the list defined in TRN_ALLOWED_DOMAINS. These terms should be seperated by a comma (,). The domains included here must include wildcard characters in order to match anything except a specific file URL. URLs are checked for exact matches when comparing to the whitelist. You may use the wildcards * to represent multiple (0 or more) wildcard characters and ? to represent a single (0 or more) wildcard character.

1TRN_ALLOWED_DOMAINS: "https://google.com/*,*://yahoo.com/*,bing.com/*, *.my.domain/*,https://myfile.com/test.pdf"`

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.

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

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.

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.

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.

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.

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.