Configuration options
Configure Document Engine with environment variables for the document-engine container. For deployment setup, refer to the Kubernetes deployment guide. If you use Helm, refer to the Helm deployment guide to set these options with Helm values.
General configuration options
Use these options to control core Document Engine behavior:
PORT— Sets the port where Document Engine listens for incoming traffic.ALLOW_DOCUMENT_UPLOADS— Enables or disables document uploads to Document Engine. Supported values aretrueandfalse. The default value istrue.ALLOW_REMOTE_DOCUMENTS— Enables or disables adding documents from URLs. Supported values aretrueandfalse. The default value istrue.ALLOW_DOCUMENT_GENERATION— Enables or disables document creation through PDF generation. The default value istrue.ALLOW_REMOTE_ASSETS_IN_GENERATION— Controls whether Document Engine loads external resources such as images and stylesheets from the network during PDF generation. If set tofalse, Document Engine won’t load external assets. The default value istrue.AUTOMATIC_LINK_EXTRACTION— Extracts link annotations from text automatically. Refer to the link annotations guide for more information. The default value isfalse.IGNORE_INVALID_ANNOTATIONS— Controls how Document Engine handles invalid annotations during PDF export. If set totrue, Document Engine ignores invalid annotations and logs them instead of failing. If set tofalse, PDF export fails and logs an error when invalid annotations are present. Supported values aretrueandfalse. The default value istrue.MIN_SEARCH_QUERY_LENGTH— Sets the minimum number of characters required to start a document search. The default value is3.ENABLE_BULK_DOCUMENT_DELETION— Enables or disables the bulk deletion endpoint. The default value isfalse.SERVER_HEADER_TOKENS— Controls theserverresponse header. This option has been available since Document Engine 1.10.0. Supported values are:off— Noserverheadername—server: Document Engineversion—server: Document Engine/1.10.0
Hoard internal cache options
Document Engine uses an internal cache called Hoard for frequently accessed data, including large files or parts of files. In some cases, a small cached value can still reference a much larger file. Hoard can copy only the smaller relevant portion to avoid keeping the larger file in memory.
These options have been available since Document Engine 1.10:
HOARD_MAX_SIZE— Sets the maximum Hoard cache size. The default value is100000000bytes (100 MB).HOARD_BINARY_COPY_ENABLED— Enables the binary copy optimization. It’s enabled by default. To disable it, set the value tooff,no,false, or0.HOARD_BINARY_COPY_THRESHOLD— Sets the size ratio at which Hoard performs a copy. The default value is2.
These are advanced settings with tuned default values. Don’t change them unless you understand the memory tradeoffs, because incorrect values can increase memory usage and reduce performance.
Trust and secrets
Use these options to configure credentials, signing keys, and trusted connections:
ACTIVATION_KEY— Sets the online license activation key or offline license key. Refer to the product activation guide for more information.API_AUTH_TOKEN— Sets the authentication token for the Server API. Use a long, randomly generated string.SECRET_KEY_BASE— Sets the base key used to generate authentication-related secret keys. Use a strong random string. You can generate one withopenssl rand -hex 256.JWT_PUBLIC_KEY— Verifies the JWT payload signature. This key must match the private key your application uses to sign JWTs. Refer to the authentication guide for more information.JWT_ALGORITHM— Sets the algorithm used for JWT verification. Supported values areRS256,RS512,ES256, andES512. This must match the signing algorithm in your application. Refer to RFC 7518(opens in a new tab) for details.DASHBOARD_USERNAME,DASHBOARD_PASSWORD— Set the credentials for the dashboard. Leave them unset to disable dashboard access.REPLACE_SECRETS_FROM_ENV— Controls whether Document Engine readsJWT_PUBLIC_KEY,SECRET_KEY_BASE, andDASHBOARD_PASSWORDfrom environment variables. The default value istrue. You can also configure secrets through the API. Refer to the secrets management guide for more information.TRUSTED_PROXIES— Accepts a comma-separated list of trusted proxy IP addresses or ranges. Set this todefaultto use private IP address ranges(opens in a new tab).- When configured, Document Engine reads specific request headers to determine the original client IP address behind proxies.
- If unset, Document Engine uses the immediate connection IP address.
DOWNLOADER_CERT_FILE_PATH— Sets the certificate file used to verify TLS certificates from remote document servers. By default, Document Engine uses the Mozilla-included CAs(opens in a new tab) at/certificate-stores-downloader/root-certificates.pem. Refer to the certificate trust configuration guide for more information.REMOTE_URL_FETCH_POLICY— Controls which destinations Document Engine may fetch for customer-controlled remote URLs, such as document creation from a remote URL, Build API URL file inputs, remote document assets, and Office template image URLs. Supported values areallowlist_only,public_only,allow_private, andallow_all. The default value ispublic_only, which allows public HTTP(S) destinations while blocking local, private, link-local, and cloud metadata address ranges.- Use
allowlist_onlyto deny all remote destinations except configured hosts or CIDRs while still blocking critical SSRF ranges. - Use
allow_privateonly when the deployment must fetch from RFC1918 IPv4 or IPv6 ULA destinations; localhost, link-local, and cloud metadata addresses remain blocked. - Use
allow_allonly as an emergency escape hatch for controlled self-hosted deployments.
- Use
REMOTE_URL_FETCH_ALLOWED_HOSTS— Accepts a comma-separated list of DNS hostnames or wildcard DNS patterns, such asassets.example.comor*.assets.example.com, that may be fetched even when they resolve to otherwise blocked non-critical ranges.REMOTE_URL_FETCH_ALLOWED_CIDRS— Accepts a comma-separated list of CIDR ranges that may be fetched under controlled self-hosted deployments. Critical SSRF ranges remain blocked unless the policy isallow_all.REMOTE_URL_FETCH_ALLOW_EMBEDDED_CREDENTIALS— Controls whether remote URLs may include embedded credentials, such ashttps://user:pass@example.com/file.pdf. It’s disabled by default.
Limits and timeouts
If you need to support large documents, refer to the large documents guide.
PSPDFKIT_WORKER_POOL_SIZE— Controls the number ofpspdfkitdprocesses that handle PDF-related tasks.- A typical starting point is two or three times the number of available CPU cores.
- Setting it too high can create CPU contention.
- Setting it too low can increase wait times.
- The default value is
16.
DATABASE_CONNECTIONS— Sets the database connection pool size. The default value is20.PSPDFKIT_PREFERRED_FONTS— Sets a comma-separated list of font names or family names to try before the default annotation font fallback behavior. Refer to the preferred annotation fonts guide for more information.MAX_UPLOAD_SIZE_BYTES— Sets the maximum upload size in bytes.- This applies to all upload types, including remote documents.
- If unset, it defaults to
1000000000bytes, which is about950 MB, for multipart and remote uploads.
ASSET_STORAGE_CACHE_SIZE— Sets the size of the local document cache in bytes. The default value is2000000000(2 GB).ASSET_STORAGE_CACHE_TIMEOUT— Sets the timeout in milliseconds for fetching assets from storage. The default value is5000. Increase it if asset fetches time out.PDF_GENERATION_TIMEOUT— Sets the timeout in milliseconds for creating documents through PDF generation. If the process exceeds this limit, it fails. The default value is20000.PSPDFKIT_WORKER_TIMEOUT— Sets the timeout in milliseconds forpspdfkitdto complete PDF-related tasks. The default value is60000.REMOTE_URL_FETCH_TIMEOUT— Sets the maximum timeout in milliseconds for downloading a remote PDF. Increase it for large files. The default value is5000. Refer to the add documents from URLs guide for more information.READ_ANNOTATION_BATCH_TIMEOUT— Sets the timeout in milliseconds for reading a batch of annotations from a PDF. The default value is20000.SERVER_REQUEST_TIMEOUT— Sets the timeout in milliseconds for each request sent to the Document Engine HTTP API. This timeout overrides other request-specific timeouts. The default value is60000.MAX_HEADER_VALUE_LENGTH— The maximum length, in bytes, for each HTTP request header value accepted by Document Engine. Increase this only when a trusted reverse proxy or load balancer adds headers that legitimately exceed the default limit. Defaults to8192(8 KB).ASYNC_JOBS_TTL— Sets how long asynchronous jobs remain before they expire, in seconds. Document Engine deletes expired jobs and their output assets automatically. The default value is172800seconds, which is two days.FILE_UPLOAD_TIMEOUT_MS— Sets the timeout in milliseconds for uploading files to S3-compatible object storage or Azure Blob Storage. The default value is30000.
Digital signature options
Use these options to configure how Document Engine applies and validates digital signatures:
SIGNING_SERVICE_URL— Sets the URL Document Engine uses to contact an external signing service when it applies a digital signature. This applies only to instances with digital signatures support.SIGNING_SERVICE_TIMEOUT— Sets the maximum wait time in milliseconds for a response from the signing service during document signing. The default value is5000.DIGITAL_SIGNATURE_CADES_LEVEL— Sets the PAdES/CAdES level used for digital signatures. This applies only to instances with digital signatures support.- Supported values are
b-b,b-t, andb-lt. - The default value is
b-lt. - Ensure the OCSP URI in the signing certificate is reachable from Document Engine. Refer to the digital signatures overview guide for more information.
- Supported values are
TIMESTAMP_AUTHORITY_URL— Sets the URL of the timestamp authority for PAdES/CAdES signatures at levelb-tor higher. The default value ishttps://freetsa.org/.TIMESTAMP_AUTHORITY_USERNAMEandTIMESTAMP_AUTHORITY_PASSWORD— Set the optional credentials for the timestamp authority.DEFAULT_SIGNER_NAME,DEFAULT_SIGNATURE_REASON, andDEFAULT_SIGNATURE_LOCATION— Set the default metadata used during signing. These apply only to instances with digital signatures support.DIGITAL_SIGNATURE_HASH_ALGORITHM— Sets the hash algorithm used for digital signatures. This applies only to instances with digital signatures support.- The default value is
sha256. - Supported values are
md5,sha160,sha224,sha256,sha384, andsha512. - Use
sha256or higher.
- The default value is
DIGITAL_SIGNATURE_CERTIFICATE_CHECK_TIME— Sets the time reference used to validate the signing certificate. The default value iscurrent_time.- If set to
signing_time, Document Engine validates the certificate against the signature creation time. - If set to
current_time, valid signatures whose certificates have expired are marked as expired.
- If set to
Trusted root certificates for digital signatures
Document Engine looks for certificate stores in the /certificate-stores directory inside the container. To add custom certificates, mount a host directory that contains your certificate files.
Database options
Use these options to configure the PostgreSQL connection and migrations:
PGUSER,PGPASSWORD,PGDATABASE,PGHOST,PGPORT— Configure how thepspdfkitservice connects to thedbservice.- Replace the default password with a secure one.
- Use the same value for
PGPASSWORDandPOSTGRES_PASSWORD.
PGSSL— Enables an SSL connection to PostgreSQL. The default value isfalse.- If set to
true, Document Engine uses the container’s preinstalled certificates to verify the server certificate. - To use a custom CA certificate, set
PGSSLtotrueand provide the certificate throughPGSSL_CA_CERT_PATHorPGSSL_CA_CERTS. Don’t use both.
- If set to
PGSSL_CA_CERT_PATH— Sets the path to a CA certificate file used for server certificate verification. This option conflicts withPGSSL_CA_CERTS.PGSSL_CA_CERTS— Sets a CA certificate directly for server certificate verification. This option conflicts withPGSSL_CA_CERT_PATH.PGSSL_CERT_COMMON_NAME— Sets the common name of the server certificate. By default, it uses the value ofPGHOST.PGSSL_DISABLE_HOSTNAME_VERIFY— Disables hostname verification for the server certificate. The default value isfalse.PGSSL_DISABLE_VERIFY— Disables server certificate verification entirely. The default value isfalse.ENABLE_DATABASE_MIGRATIONS— Controls whether Document Engine checks for pending database migrations and runs them when needed. The default value istrue.EXIT_AFTER_DATABASE_MIGRATIONS— Controls whether Document Engine exits after it completes pending migrations. This is useful for dedicated migration jobs. The default value isfalse.PG_ADMIN_USER— OverridesPGUSERwhen set.- If Document Engine runs with limited database permissions and
ENABLE_DATABASE_MIGRATIONSisfalse, use this option for administrative credentials in separate migration jobs. - To run migrations separately, set both
ENABLE_DATABASE_MIGRATIONSandEXIT_AFTER_DATABASE_MIGRATIONStotrue.
- If Document Engine runs with limited database permissions and
PG_ADMIN_PASSWORD— OverridesPGPASSWORDand works withPG_ADMIN_USER.PG_OPERATION_USER— Sets the database user that receives operational permissions after migration. By default, it usesPGUSER.
Asset storage options
Use these options to configure where Document Engine stores uploaded documents and attachments:
ASSET_STORAGE_BACKEND— Sets how Document Engine stores uploaded PDFs and attachments. Supported values arebuilt-in,s3, andazure. The default value isbuilt-in.ENABLE_ASSET_STORAGE_FALLBACK— Enables fallback reads from secondary storage backends when assets aren’t available in the primary backend.- The default value is
false. - Set this to
trueduring asset storage backend migration. Refer to the asset storage configuration guide for more information.
- The default value is
ENABLE_ASSET_STORAGE_FALLBACK_POSTGRES— Enables built-in database storage as a fallback. The default value isfalse. This requiresENABLE_ASSET_STORAGE_FALLBACKto betrue.ENABLE_ASSET_STORAGE_FALLBACK_S3— Enables S3 storage as a fallback. The default value isfalse. This requiresENABLE_ASSET_STORAGE_FALLBACKto betrue.ENABLE_ASSET_STORAGE_FALLBACK_AZURE— Enables Azure Blob Storage as a fallback. The default value isfalse. This requiresENABLE_ASSET_STORAGE_FALLBACKto betrue.USE_UNSAFE_DELETE_FOR_ASSETS— Controls whether Document Engine skips the trash directory and deletes assets immediately. The default value isfalse.If an error occurs during deletion, assets can’t be recovered.
S3-compatible object storage
Use these options when ASSET_STORAGE_BACKEND is s3:
ASSET_STORAGE_S3_BUCKET— Sets the S3 bucket name whenASSET_STORAGE_BACKENDiss3. Refer to the asset storage configuration guide for more information.ASSET_STORAGE_S3_REGION— Sets the bucket region.ASSET_STORAGE_S3_ACCESS_KEY_IDandASSET_STORAGE_S3_SECRET_ACCESS_KEY— Set optional AWS credentials.- If you don’t provide them, Document Engine tries platform-specific authentication methods.
- Supported methods are:
- AWS EC2 instance roles
- AWS ECS task roles
- AWS EKS instance roles for service accounts
ASSET_STORAGE_S3_HOST— Sets an optional custom endpoint for S3-compatible object storage.ASSET_STORAGE_S3_PORT— Sets an optional custom port for S3-compatible object storage.ASSET_STORAGE_S3_SCHEME— Sets the URL scheme for S3-compatible object storage. Supported values arehttp://andhttps://. The default value ishttps://.
Azure Blob Storage
Use these options when ASSET_STORAGE_BACKEND is azure:
AZURE_STORAGE_ACCOUNT_NAME,AZURE_STORAGE_ACCOUNT_KEY— Set the credentials for Azure Blob Storage whenASSET_STORAGE_BACKENDisazure. Refer to the asset storage configuration guide for setup details.AZURE_STORAGE_ACCOUNT_CONNECTION_STRING— Sets the Azure Blob Storage connection through a connection string instead of separate account name and key values.AZURE_STORAGE_DEFAULT_CONTAINER— Sets the Azure Blob Storage container name.
Rendering options
Use this option to limit rendered tile request scale:
TILE_MAX_SCALE— Sets the maximum permitted scale for rendered tile requests. Tile requests above this scale are rejected. If unset, Document Engine doesn’t enforce a tile scale limit. If set, the value must be a number greater than1.Document Engine calculates the requested tile scale from the requested tile size and the unscaled page size. It uses the larger value of:
- Requested tile width divided by page width
- Requested tile height divided by page height
When you use Nutrient Web SDK with Document Engine, the Web SDK
tileSizeconfiguration controls the requested tile size. The default server-backed tile size is512pixels. If you explicitly setTILE_MAX_SCALE=2, that can fail for small pages. For example, a512 × 512pixel tile requested from a200 × 300pixel page is rejected:max(512 / 200, 512 / 300) = max(2.56, 1.71) = 2.56This fails because
2.56is greater than the configured maximum scale of2. Reducing the Web SDKtileSizeto400keeps the request within that limit for this page:NutrientViewer.load({// ...tileSize: 400,});max(400 / 200, 400 / 300) = max(2, 1.33) = 2Prefer configuring the Web SDK
tileSize. If larger tiles are intentional, setTILE_MAX_SCALEexplicitly instead.
Rendering cache options
Use these options to configure Redis as a shared rendered-page cache:
USE_REDIS_CACHE— Enables or disables Redis(opens in a new tab) as a shared rendered-page cache. Supported values aretrueandfalse. The default value isfalse.REDIS_HOST,REDIS_PORT,REDIS_DATABASE,REDIS_USERNAME,REDIS_PASSWORD— Set how Document Engine connects to Redis(opens in a new tab). These options apply only whenUSE_REDIS_CACHEistrue.REDIS_SENTINELS— ReplacesREDIS_HOSTandREDIS_PORTwhen you use Redis Sentinel(opens in a new tab).- Provide a comma-separated list of Redis URIs for the Sentinel servers.
- Example value:
"redis://sentinel1:26379;redis://sentinel2:26379;redis://sentinel3:26379"
REDIS_SENTINELS_GROUP— Required whenREDIS_SENTINELSis set. This must match the master group name in your Redis Sentinel configuration. Refer to the configuring Sentinel documentation(opens in a new tab) for more information.REDIS_SSL— Enables an SSL connection to Redis(opens in a new tab) when set totrue.REDIS_TTL— Sets the Redis key TTL in milliseconds. The default value is86400000, which is 24 hours.USE_REDIS_TTL_FOR_PRERENDERING— Controls how long Redis entries created by document prerendering persist. The default value istrue.- If set to
true, entries use the TTL fromREDIS_TTL. - If set to
false, entries remain until Redis evicts them or you upgrade Document Engine.
- If set to
Logging and monitoring options
Use these options to configure logs, metrics, and tracing:
LOG_LEVEL— Sets the minimum log level. The default value isinfo.- Supported values, from most to least verbose, are
debug,info,warn, anderror. - Document Engine emits logs at the selected level and all levels below it.
- Supported values, from most to least verbose, are
LOG_STRUCTURED— Enables structured JSON logging when set totrue. If unset orfalse, Document Engine emits regular text logs.LOG_STRUCTURED_FLATTEN— Controls whether structured logs emit flattened top-level dotted fields instead of nested JSON metadata. WhenLOG_STRUCTURED=true, flattening is enabled by default. SetLOG_STRUCTURED_FLATTEN=falseto keep nested JSON fields.HEALTHCHECK_LOGLEVEL— Sets the log level for the healthcheck endpoint, including the root path (/). It supports the same values asLOG_LEVEL, plusnone. The default value isdebug.STATSD_HOSTandSTATSD_PORT— Set the host and port for a StatsD-compatible(opens in a new tab) daemon used for telemetry reporting.STATSD_CUSTOM_TAGS— Adds custom tags to all telemetry metrics. Use comma-separatedkey=valuepairs, such asregion=eu-1,env=prod.ENABLE_OPENTELEMETRY— Enables OpenTelemetry tracing. This requiresOTEL_EXPORTER_OTLP_ENDPOINTand, optionally,OTEL_EXPORTER_OTLP_PROTOCOL.
OpenTelemetry parameters
Use these parameters when you enable OpenTelemetry tracing:
OTEL_EXPORTER_OTLP_PROTOCOL— Sets the transport protocol. The default value isgrpc.OTEL_EXPORTER_OTLP_ENDPOINT— Sets the OpenTelemetry endpoint. The default value ishttp://localhost:4317.OTEL_RESOURCE_ATTRIBUTES— Sets custom OpenTelemetry resource attributes.OTEL_SERVICE_NAME— Sets the service name in OpenTelemetry traces. The default value isdocument-engine.OTEL_TRACES_SAMPLER— Controls trace sampling. By default, Document Engine uses a customparent_basedsampler that skips healthchecks and/requests.OTEL_PROPAGATORS— Sets the propagation format. The default value isbaggage,tracecontext.
Conversion options
Use these options to control spreadsheet conversion limits:
SPREADSHEET_MAX_CONTENT_HEIGHT_MM— Sets the maximum spreadsheet content height in millimeters. The default value is0, which means unlimited. Use this to control memory usage during spreadsheet conversion.SPREADSHEET_MAX_CONTENT_WIDTH_MM— Sets the maximum spreadsheet content width in millimeters. The default value is0, which means unlimited. Use this to control memory usage during spreadsheet conversion.
HTTP proxy options
Use these options to configure outbound proxy settings:
HTTP_PROXYorHTTPS_PROXY— Sets the proxy URL for Document Engine’s HTTP client. Document Engine uses this when it:- Fetches remote documents
- Downloads or uploads assets
- Contacts the CDN server
- Interacts with the signing service, OCSP, and timestamping authorities
- Communicates with the licensing service
This isn’t set by default. If you leave it unset, Document Engine doesn’t fall back to other
HTTP(S)_PROXY_*settings.HTTP_PROXY_ASSET_DOWNLOADorHTTPS_PROXY_ASSET_DOWNLOAD— OverrideHTTP_PROXYorHTTPS_PROXYfor downloads from configured asset storage backends. If unset, Document Engine usesHTTP_PROXYorHTTPS_PROXY.HTTP_PROXY_REMOTE_FILE_DOWNLOADorHTTPS_PROXY_REMOTE_FILE_DOWNLOAD— OverrideHTTP_PROXYorHTTPS_PROXYfor downloads from provided URLs during document upload. If unset, Document Engine usesHTTP_PROXYorHTTPS_PROXY.HTTP_PROXY_WEB_CDNorHTTPS_PROXY_WEB_CDN— OverrideHTTP_PROXYorHTTPS_PROXYwhen Document Engine retrieves the Web SDK from the CDN. If unset, Document Engine usesHTTP_PROXYorHTTPS_PROXY.HTTP_PROXY_SIGNING_SERVICEorHTTPS_PROXY_SIGNING_SERVICE— OverrideHTTP_PROXYorHTTPS_PROXYfor requests to the signing service. If unset, Document Engine usesHTTP_PROXYorHTTPS_PROXY.HTTP_PROXY_LICENSING_SERVICEorHTTPS_PROXY_LICENSING_SERVICE— OverrideHTTP_PROXYorHTTPS_PROXYfor requests to the customer licensing portal. If unset, Document Engine usesHTTP_PROXYorHTTPS_PROXY.
Clustering options
Refer to the horizontal scaling guide for background.
CLUSTERING_ENABLED— Enables clustering. The default value isfalse. Set it totrueon every node in the deployment.CLUSTERING_METHOD— Sets the peer discovery method. Supported values arelocalandkubernetes_dns. It defaults tolocalin development and test environments. In other environments, automatic clustering stays off unless you set a value. Unknown values disable clustering and log a warning.CLUSTERING_SERVICE_NAME— Sets the headless service name used by thekubernetes_dnsdiscovery method. The default value isdocument-engine.CLUSTERING_APPLICATION_NAME— Sets the distributed Erlang application name used by thekubernetes_dnsdiscovery method. The default value ispssync.
HTTP/2 shared rendering options
Shared rendering is an HTTP/2 performance feature for tiled viewing workloads. Refer to the HTTP/2 shared rendering guide for background.
HTTP2_SHARED_RENDERING_PROCESS_ENABLE— Enables the shared rendering path for supported tile endpoints. The default value isfalse.HTTP2_SHARED_RENDERING_PROCESS_CHECKOUT_TIMEOUT— Sets the maximum wait time in milliseconds when Document Engine checks out a rendering worker for a shared rendering session. The default value is5000.HTTP2_SHARED_RENDERING_PROCESS_CHECKIN_TIMEOUT— Sets the idle time in milliseconds that a worker can stay checked out between tile requests on the same connection before Document Engine returns it to the pool. The default value is0.
Mount custom fonts
Document Engine supports additional fonts through the /custom-fonts directory. Refer to the custom fonts guide for more information.