Configuration options

Customize Document Engine to fit your application’s needs by configuring various options through environment variables for the document-engine container. You can set these options using Helm values.

General configuration options

  • PORT — Specifies the port where Document Engine listens for incoming traffic.

  • ALLOW_DOCUMENT_UPLOADS — Controls whether users can upload documents to Document Engine. Supported values are true and false. The default value is true.

  • ALLOW_REMOTE_DOCUMENTS — Determines whether users can add documents from URLs. Supported values are true and false. The default value is true.

  • ALLOW_DOCUMENT_GENERATION — Enables or disables document creation using PDF generation. The default value is true.

  • ALLOW_REMOTE_ASSETS_IN_GENERATION — Controls whether external resources (images, stylesheets, etc.) are loaded from the network during PDF generation. If set to false, Document Engine won’t load external assets. The default value is true.

  • AUTOMATIC_LINK_EXTRACTION — Extracts link annotations from text automatically. For more information, refer to the link annotations guide. The default value is false.

  • IGNORE_INVALID_ANNOTATIONS — Determines how Document Engine handles invalid annotations when exporting PDFs. If set to true, Document Engine ignores invalid annotations and logs them instead of throwing an error. If set to false, PDF export fails if invalid annotations are present, logging an error. Supported values are true and false. The default value is true.

  • MIN_SEARCH_QUERY_LENGTH — Defines the minimum number of characters required to initiate a document search. The default value is 3 characters.

Trust and secrets

  • ACTIVATION_KEY — Specifies the online license activation key or offline license key. For more information, refer to the product activation guide.

  • API_AUTH_TOKEN — Defines the authentication token for the Server API. Use a long, randomly generated string to secure API access.

  • SECRET_KEY_BASE — Serves as the base key for generating authentication-related secret keys. Use a strong, random string. Generate one using: openssl rand -hex 256.

  • JWT_PUBLIC_KEY — Verifies the JSON Web Token (JWT) payload signature. Ensure this key matches the private key used for JWT generation in your app. For more information, refer to the authentication guide.

  • JWT_ALGORITHM — Specifies the algorithm for JWT verification. Ensure this matches the signing algorithm in your app. Supported values are RS256, RS512, ES256, ES512. See RFC 7518(opens in a new tab) for algorithm specifications.

  • DASHBOARD_USERNAME, DASHBOARD_PASSWORD — Sets login credentials for accessing the dashboard. Leave these unset to disable dashboard access.

  • REPLACE_SECRETS_FROM_ENV — Determines whether JWT_PUBLIC_KEY, SECRET_KEY_BASE, and DASHBOARD_PASSWORD values are sourced from environment variables. The default value is true. Alternatively, secrets can be configured through the API. For more information, refer to the secrets management guide.

  • TRUSTED_PROXIES — Accepts a comma-separated list of trusted proxy IP addresses or ranges. Setting this to default uses private IP address ranges(opens in a new tab).

    • When configured, Document Engine examines specific request headers to determine the originating client IP address, even when operating behind proxies.

    • If left empty or unset, Document Engine uses the immediate connection’s IP address as the client address.

  • DOWNLOADER_CERT_FILE_PATH — Specifies a certificate file for verifying the TLS certificate of remote document servers. Defaults to the Mozilla-included CAs(opens in a new tab) at: /certificate-stores-downloader/root-certificates.pem. For more information, refer to the certificate trust configuration guide.

Limits and timeouts

  • PSPDFKIT_WORKER_POOL_SIZE — Controls the number of pspdfkitd processes handling PDF-related tasks.

    • For optimal performance, set this to two or three times the number of available CPU cores.

    • Setting it too high can cause CPU resource contention, slowing down processing.

    • Setting it too low can leave CPU resources underutilized, increasing wait times.

    • The default value is 16.

  • DATABASE_CONNECTIONS — Defines the database connection pool size. The default value is 20.

  • MAX_UPLOAD_SIZE_BYTES — Specifies the maximum allowed size for uploaded documents, in bytes.

    • Applies to all upload types, including remote documents.

    • If unset, defaults to 1000000000 (one billion) bytes (approximately 950 MB) for multipart and remote uploads.

  • ASSET_STORAGE_CACHE_SIZE — Determines the size of the document cache in local storage, in bytes. The default value is 2000000000 (2 GB).

  • PDF_GENERATION_TIMEOUT — Sets the timeout (in milliseconds) for creating documents using PDF generation. If the process exceeds this limit, it fails. The default value is 20000 (20 seconds).

  • PSPDFKIT_WORKER_TIMEOUT — Specifies the timeout (in milliseconds) for pspdfkitd to complete PDF-related tasks. The default value is 60000 (60 seconds).

  • REMOTE_URL_FETCH_TIMEOUT — Defines the maximum timeout (in milliseconds) for downloading a remote PDF. Increase this value if handling large files. The default value is 5000 (5 seconds). For more information, refer to the add documents from URLs guide.

  • READ_ANNOTATION_BATCH_TIMEOUT — Sets the timeout (in milliseconds) for reading a batch of annotations from a PDF. The default value is 20000 (20 seconds).

  • SERVER_REQUEST_TIMEOUT — Specifies the timeout (in milliseconds) for each request sent to the Document Engine HTTP API. This timeout overrides any other request-specific timeout. The default value is 60000 (1 minute).

  • ASYNC_JOBS_TTL — Determines how long (in seconds) async jobs remain before expiration. Document Engine deletes expired jobs and their output assets automatically. The default value is 172800 seconds (2 days).

  • FILE_UPLOAD_TIMEOUT_MS — Sets the timeout (in milliseconds) for uploading files to S3. The default value is 30000 milliseconds (30 seconds).

Digital signature options

  • SIGNING_SERVICE_URL — Specifies the URL Document Engine uses to contact an external signing service when applying a digital signature. 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 when signing a document. The default value is 5000 milliseconds (5 seconds).

  • DIGITAL_SIGNATURE_CADES_LEVEL — Defines the PAdES/CAdES level used for digital signatures. Applies only to instances with digital signatures support.

    • Allowed values are: b-b, b-t, and b-lt (corresponding to PAdES signature levels).

    • The default value is b-lt.

    • Ensure that the OCSP URI in the signing certificate is accessible to Document Engine. For more information, refer to the digital signatures overview guide.

  • TIMESTAMP_AUTHORITY_URL — Specifies the URL of the timestamp authority for PAdES/CAdES signatures at level b-t or above. The default value is https://freetsa.org/.

  • TIMESTAMP_AUTHORITY_USERNAME and TIMESTAMP_AUTHORITY_PASSWORD — Sets the optional credentials required to connect to the timestamp authority.

  • DEFAULT_SIGNER_NAME, DEFAULT_SIGNATURE_REASON, and DEFAULT_SIGNATURE_LOCATION — Defines the default metadata used when signing a document. Applies only to instances with digital signatures support.

  • DIGITAL_SIGNATURE_HASH_ALGORITHM — Specifies the hash algorithm used for digital signatures. Applies only to instances with digital signatures support.

    • The default value is sha256.

    • Allowed values are: md5, sha160, sha224, sha256, sha384, or sha512.

    • Recommended values: sha256 or higher for better security.

  • DIGITAL_SIGNATURE_CERTIFICATE_CHECK_TIME — Determines the time reference for validating the signing certificate’s validity. The default value is current_time.

    • If set to signing_time, validation occurs based on the signature’s creation time.

    • Using current_time means valid signatures with expired certificates are marked as expired.

Trusted root certificates for digital signatures

Document Engine searches for certificate stores in the /certificate-stores directory inside its container. To add custom certificates, mount a folder from the host machine containing your certificate files.

Database options

  • PGUSER, PGPASSWORD, PGDATABASE, PGHOST, PGPORT — Configure these options to define how the pspdfkit service connects to the db service.

    • Ensure you replace the default password with a secure custom password.

    • Use the same value for both PGPASSWORD and POSTGRES_PASSWORD.

  • PGSSL — Enables a secure SSL connection to a PostgreSQL database. The default value is false.

    • If enabled (true), Document Engine uses the container’s preinstalled certificates to verify the server certificate.

    • To use a custom CA certificate, set PGSSL to true and provide the certificate path using PGSSL_CA_CERT_PATH or PGSSL_CA_CERTS (these two options are mutually exclusive).

  • PGSSL_CA_CERT_PATH — Specifies the path to a CA certificate file for server certificate verification. This option cannot be used together with PGSSL_CA_CERTS.

  • PGSSL_CA_CERTS — Provides a CA certificate directly for server certificate verification. This option cannot be used together with PGSSL_CA_CERT_PATH.

  • PGSSL_CERT_COMMON_NAME — Defines the common name of the server certificate. Defaults to the value of PGHOST.

  • PGSSL_DISABLE_HOSTNAME_VERIFY — Disables verification of the server certificate’s hostname. The default value is false.

  • PGSSL_DISABLE_VERIFY — Disables verification of the server certificate entirely. The default value is false.

  • ENABLE_DATABASE_MIGRATIONS — Controls whether Document Engine checks for pending database migrations and runs them if needed. The default value is true.

  • EXIT_AFTER_DATABASE_MIGRATIONS — Determines whether Document Engine should exit after completing pending migrations. Useful for running dedicated migration jobs in an infrastructure setup. The default value is false.

  • PG_ADMIN_USER — Overrides PGUSER when specified.

    • If Document Engine runs with limited database permissions (ENABLE_DATABASE_MIGRATIONS is set to false), use this option to provide administrative credentials for separate migration jobs.

    • To execute migrations separately, set both ENABLE_DATABASE_MIGRATIONS and EXIT_AFTER_DATABASE_MIGRATIONS to true.

  • PG_ADMIN_PASSWORD — Overrides PGPASSWORD and works as the counterpart to PG_ADMIN_USER.

  • PG_OPERATION_USER — Defines the database user who receives operational permissions over the Document Engine database after migration. The default value is PGUSER.

Asset storage options

  • ASSET_STORAGE_BACKEND — Specifies how Document Engine stores uploaded PDFs and attachments. Supported values are built-in and s3. The default value is built-in.

  • ENABLE_ASSET_STORAGE_FALLBACK — Allows Document Engine to retrieve PDFs and attachments from secondary storage backends if they’re unavailable in the primary backend.

    • The default value is false.

    • It’s recommended to set to true during asset storage backend migration. For more information, see the asset storage configuration guide.

  • ENABLE_ASSET_STORAGE_FALLBACK_POSTGRES — Enables built-in database storage as a fallback option. The default value is false. Requires ENABLE_ASSET_STORAGE_FALLBACK to be true.

  • ENABLE_ASSET_STORAGE_FALLBACK_S3 — Enables S3 storage as a fallback option. The default value is false. Requires ENABLE_ASSET_STORAGE_FALLBACK to be true.

  • ENABLE_ASSET_STORAGE_FALLBACK_AZURE — Enables Azure Blob Storage as a fallback option. The default value is false. Requires ENABLE_ASSET_STORAGE_FALLBACK to be true.

  • USE_UNSAFE_DELETE_FOR_ASSETS — Controls whether Document Engine uses a trash directory for safe asset deletion. The default value is false.

    • When enabled (true), Document Engine deletes assets immediately without using a trash directory.

    If an error occurs during deletion, assets cannot be recovered.

S3-compatible object storage

  • ASSET_STORAGE_S3_BUCKET — Specifies the S3 bucket name when ASSET_STORAGE_BACKEND is set to s3. For more information, refer to the asset storage configuration guide.

  • ASSET_STORAGE_S3_REGION — Defines the region of the S3 bucket.

  • ASSET_STORAGE_S3_ACCESS_KEY_ID and ASSET_STORAGE_S3_SECRET_ACCESS_KEY — Optional AWS credentials for authentication.

    • If these aren’t provided, Document Engine attempts to use other platform-specific access methods.

    • Supported authentication methods are:

      • AWS EC2 instance roles

      • AWS ECS task roles

      • AWS EKS instance roles for service accounts

  • ASSET_STORAGE_S3_HOST — (Optional) Custom endpoint for S3-compatible object storage.

  • ASSET_STORAGE_S3_PORT — (Optional) Custom port for S3-compatible object storage.

  • ASSET_STORAGE_S3_SCHEME — Defines the URL scheme for accessing S3-compatible object storage. Supported values are http:// or https://. The default value is https://.

Azure Blob Storage

  • AZURE_STORAGE_ACCOUNT_NAME, AZURE_STORAGE_ACCOUNT_KEY — Credentials required for Azure Blob Storage when ASSET_STORAGE_BACKEND is set to azure. For detailed setup instructions, refer to the asset storage configuration guide.

  • AZURE_STORAGE_ACCOUNT_CONNECTION_STRING — An alternative way to connect to Azure Blob Storage. Use this instead of specifying AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_ACCOUNT_KEY separately.

  • AZURE_STORAGE_DEFAULT_CONTAINER — Specifies the name of the Azure Blob Storage container.

Rendering cache options

  • USE_REDIS_CACHE — Enables or disables the use of Redis(opens in a new tab) as an additional image cache. Supported values are true and false. The default value is true.

  • REDIS_HOST, REDIS_PORT, REDIS_DATABASE, REDIS_USERNAME, REDIS_PASSWORD — Defines how Document Engine connects to Redis(opens in a new tab). These settings apply only if USE_REDIS_CACHE is set to true.

  • REDIS_SENTINELS — Replaces REDIS_HOST and REDIS_PORT when using Redis Sentinel(opens in a new tab).

    • Provide a comma-separated list of Redis URIs specifying the Sentinel servers.

    • Example value: "redis://sentinel1:26379;redis://sentinel2:26379;redis://sentinel3:26379"

  • REDIS_SENTINELS_GROUP — Required when REDIS_SENTINELS is set. This should match the master group name in your Redis Sentinel configuration. It’s passed as a first argument to sentinel monitor in the Sentinel configuration file. For more information, refer to the configuring Sentinel(opens in a new tab) documentation.

  • REDIS_SSL — If set to true, enables an encrypted SSL connection to Redis(opens in a new tab).

  • REDIS_TTL — Defines the time-to-live (TTL) for Redis cache keys in milliseconds. The default value is 86400000 milliseconds (24 hours).

  • USE_REDIS_TTL_FOR_PRERENDERING — Controls how long Redis cache entries persist during document prerendering (POST /api/documents/:document_id/prerender). The default value is true.

    • If set to true, cache entries follow the TTL set in REDIS_TTL.

    • If set to false, cache entries remain in Redis until evicted by Redis’ eviction policy or after upgrading Document Engine.

Logging and monitoring options

  • LOG_LEVEL — Sets the minimum log level for Document Engine. The default value is info.

    • Allowed values (from most to least verbose): debug, info, warn, and error.

    • Logs from the chosen level and all lower levels will be emitted. For example, if the value is set to debug, Document Engine emits logs for debug, info, warn, and error.

  • HEALTHCHECK_LOGLEVEL — Defines the log level for the healthcheck endpoint. The allowed values are the same as for LOG_LEVEL, with an additional none. This includes the root path (/) as well. The default value is debug.

  • STATSD_HOST and STATSD_PORT — Defines the host and port for a running StatsD-compatible(opens in a new tab) daemon for telemetry reporting.

  • STATSD_CUSTOM_TAGS — Adds custom tags to all telemetry metrics. Format is: comma-separated key=value pairs attached as tags to every metric published by Document Engine. For example, region=eu-1,env=prod.

  • ENABLE_OPENTELEMETRY — Enables OpenTelemetry tracing. Requires specifying OTEL_EXPORTER_OTLP_ENDPOINT and, optionally, OTEL_EXPORTER_OTLP_PROTOCOL.

OpenTelemetry parameters

  • OTEL_EXPORTER_OTLP_PROTOCOL — Defines the transport protocol. The default value is grpc.

  • OTEL_EXPORTER_OTLP_ENDPOINT — Specifies the OpenTelemetry endpoint. The default value is http://localhost:4317.

  • OTEL_RESOURCE_ATTRIBUTES — Custom OpenTelemetry resource attributes.

  • OTEL_SERVICE_NAME — Defines the service name in OpenTelemetry traces. The default value is document-engine.

  • OTEL_TRACES_SAMPLER — Controls tracing behavior. The default value is a custom parent_based sampler that skips healthchecks and / requests.

  • OTEL_PROPAGATORS — Defines the propagation format. The default value is baggage,tracecontext.

Conversion options

  • SPREADSHEET_MAX_CONTENT_HEIGHT_MM — Sets the maximum height (in millimeters) for spreadsheet content. The default value is 0 (unlimited). Use this to manage memory usage during spreadsheet conversions.

  • SPREADSHEET_MAX_CONTENT_WIDTH_MM — Sets the maximum width (in millimeters) for spreadsheet content. The default value is 0 (unlimited). Helps control memory consumption in the Document Engine container.

HTTP proxy options

  • HTTP_PROXY or HTTPS_PROXY — URL of a proxy server for Document Engine’s HTTP client. Used when:

    • Fetching remote documents

    • Downloading/uploading assets

    • Contacting the CDN server

    • Interacting with the signing service, OCSP, and timestamping authorities

    • Licensing service communication

    Not set by default. If unset, no fallback applies to other HTTP(S)_PROXY_* configurations.

  • HTTP_PROXY_ASSET_DOWNLOAD or HTTPS_PROXY_ASSET_DOWNLOAD — Overrides HTTP_PROXY/HTTPS_PROXY when downloading assets from configured asset storage backends. If unset, defaults to HTTP_PROXY/HTTPS_PROXY.

  • HTTP_PROXY_REMOTE_FILE_DOWNLOAD or HTTPS_PROXY_REMOTE_FILE_DOWNLOAD — Overrides HTTP_PROXY/HTTPS_PROXY when downloading files from provided URLs during document upload. If unset, defaults to HTTP_PROXY/HTTPS_PROXY.

  • HTTP_PROXY_WEB_CDN or HTTPS_PROXY_WEB_CDN — Overrides HTTP_PROXY/HTTPS_PROXY when retrieving the Web SDK from the CDN(opens in a new tab). If unset, defaults to HTTP_PROXY/HTTPS_PROXY.

  • HTTP_PROXY_SIGNING_SERVICE or HTTPS_PROXY_SIGNING_SERVICE — Overrides HTTP_PROXY/HTTPS_PROXY when making requests to the signing service. If unset, defaults to HTTP_PROXY/HTTPS_PROXY.

  • HTTP_PROXY_LICENSING_SERVICE or HTTPS_PROXY_LICENSING_SERVICE — Overrides HTTP_PROXY/HTTPS_PROXY when making requests to the customer licensing portal. If unset, defaults to HTTP_PROXY/HTTPS_PROXY.

Mounting custom fonts

Document Engine supports additional fonts through the /custom-fonts directory. For more information, refer to the configuring custom fonts guide.