Some test text!
Web / Guides / Configuration
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
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.
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 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
} } });
});
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.
WebViewer({ webviewerServerURL }).then((instance) => {
const { documentViewer } = instance.Core;
instance.UI.loadDocument(file, {rasterizerOptions: {'colorPostProcessMode': 1}});
});
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.
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:
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
WebViewer(
{
path: '../../../lib',
webviewerServerURL: 'https://demo.apryse.com/',
},
document.getElementById('viewer')
).then((instance) => {
instance.UI.loadDocument(url, {officeOptions: formatOptions: { locale: 'de-DE'}}); // sets it to the German locale
})
In WebViewer < 8.3
WebViewer(
{
path: '../../../lib',
webviewerServerURL: 'https://demo.apryse.com/',
},
document.getElementById('viewer')
).then((instance) => {
instance.UI.loadDocument(url, {officeLocale: 'de-DE'}); // sets it to the German locale
})
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.
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:
Webviewer({
pdftronServer: "http://localhost:8090",
path: '/lib',
}, document.getElementById('viewer')).then(instance => {
const { docViewer, annotManager } = instance;
instance.loadDocument(url);
docViewer.on("documentLoaded", () => {
const doc = docViewer.getDocument();
console.log("the auth id: " + doc.getAuthId());
});
});
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 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.
TRN_BLOCKED_DOMAINS: "google.com,yahoo.com,bing.com"
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.
Trial setup questions? Ask experts on Discord
Need other help? Contact Support
Pricing or product questions? Contact Sales