Configuration Options

You’ll likely want to customize some of Document Engine’s options for your own app. Configuration options for Document Engine are exposed via environment variables for the document-engine container.

Setting of these options is supported through Helm values.

General

PORT — This option determines the port where Document Engine listens for traffic.
HTTP_PROXY or HTTPS_PROXY — A URL of a proxy server used for Document Engine’s HTTP client. Used when fetching remote documents; contacting PSPDFKit’s licensing service; and interacting with the signing service, OSCP, and time stamping authorities.
ALLOW_DOCUMENT_UPLOADS — Allow or prevent uploading documents to Document Engine. Supported values are true and false. The default value for this option is true.
ALLOW_REMOTE_DOCUMENTS — Allow or prevent adding documents from URLs to Document Engine. Supported values are true and false. The default value for this option is true.
ALLOW_DOCUMENT_GENERATION — Allow or prevent creating documents with PDF Generation. The default value for this option is true.
ALLOW_REMOTE_ASSETS_IN_GENERATION — Allow or prevent loading the resources from the network during PDF generation. If set to false, any images, stylesheets, and other assets won’t be loaded from external URLs. The default value for this option is true.
AUTOMATIC_LINK_EXTRACTION — Automatically extract link annotations from text. Check out the link annotations guide for more information. The default value for this option is false.
IGNORE_INVALID_ANNOTATIONS — If set to true, Document Engine will ignore invalid annotations on PDF export instead of throwing an error. Invalid annotations will still be logged. If set to false, PDF export for PDFs containing invalid annotations will throw and log an error. Supported values are true and false. The default value for this option is true.
MIN_SEARCH_QUERY_LENGTH — This option defines the minimum amount of characters required to start a search on a document. By default, the minimum length is three characters.

Trust and Secrets

ACTIVATION_KEY — Online license activation key or offline license key. See more in our product activation guide.
API_AUTH_TOKEN — A string used for authenticating with the Server API. Choose a sufficiently long random string for this option to prevent unauthorized access to the API.
SECRET_KEY_BASE — A string used as the base key for deriving secret keys for the purposes of authentication. Choose a sufficiently long random string for this option. To generate a random string, use openssl rand -hex 256.
JWT_PUBLIC_KEY — This is the public key used to verify the JSON Web Token (JWT) payload signature. Ensure that this public key corresponds to the private key used to generate JWTs in your app. For more information, see the [authentication][] guide.
JWT_ALGORITHM — The algorithm used for JSON Web Token (JWT) verification. This should be the same as the one you’ll use for signing JWTs in your app. Supported algorithms: RS256, RS512, ES256, ES512. See RFC 7518 for details about specific algorithms.
DASHBOARD_USERNAME, DASHBOARD_PASSWORD — The username and password to access the dashboard. To disable the dashboard, leave these unset.
REPLACE_SECRETS_FROM_ENV — Take JWT_PUBLIC_KEY, SECRET_KEY_BASE, and DASHBOARD_PASSWORD values from environment variables. The default value is true. The alternative approach is setting the secrets through the API. Check the secrets management guide for more information.
TRUSTED_PROXIES — A comma-separated list of IP addresses or IP address ranges of trusted proxies in front of Document Engine. Setting this to default will use private IP address ranges.

When set, Document Engine will examine some of the request headers to determine the IP address of the actual client, even if Document Engine is behind one or more proxies.

Leaving this empty or omitting the setting completely will make Document Engine use the IP address of the immediate connection that sent a request.
DOWNLOADER_CERT_FILE_PATH — This option allows you to configure a certificate that’s used to verify the TLS certificate of the server when downloading a remote document. Defaults to the Mozilla-included CAs saved as /certificate-stores-downloader/root-certificates.pem within the Document Engine container. Refer to our certificate trust configuration guide for more details.

Limits and Timeouts

PSPDFKIT_WORKER_POOL_SIZE — This option controls how many pspdfkitd processes are started for handling PDF-related work. In general, setting this to two-to-three times the number of cores available will give you the best performance. Keep in mind that if you set this too high, the processes will starve each other for CPU time, leading to unnecessarily long processing times. And if you set this too low, available CPU time won’t be used efficiently, as tasks will have to wait for a long time for a worker to be available. This defaults to 16.
DATABASE_CONNECTIONS — This option defines the database connection pool size. The default value for this option is 20.
MAX_UPLOAD_SIZE_BYTES — The maximum allowed size of uploaded documents, in bytes. If set, it applies to all upload types, including remote documents. If unset, the default limit of 1000000000 (one billion) bytes (or around 950 MB) applies to multipart and remote uploads.
ASSET_STORAGE_CACHE_SIZE — This option determines the size of the document cache in the local storage. The size is specified in bytes, and it defaults to 2000000000 (=2 GB).
PDF_GENERATION_TIMEOUT — The timeout in milliseconds applied when creating documents with PDF Generation. Any generation taking longer than the configured timeout will fail. Defaults to 20000 (20 seconds).
PSPDFKIT_WORKER_TIMEOUT — The timeout in milliseconds for the pspdfkitd process to handle any PDF-related work. By default, it’s set to 60000 (60 seconds).
REMOTE_URL_FETCH_TIMEOUT — This option defines the maximum timeout period used, in milliseconds, when waiting for a remote PDF to download. See adding documents from URLs for more information on this feature. It can be increased if Document Engine needs to handle large files. It defaults to 5000 (5 seconds).
READ_ANNOTATION_BATCH_TIMEOUT — The timeout in milliseconds applied when reading an annotations batch from a PDF document. Defaults to 20000 (20 seconds).
SERVER_REQUEST_TIMEOUT — The timeout in milliseconds applied to each request sent to the Document Engine HTTP API. Note that this timeout takes precedence over any other timeout related to the request being processed. Defaults to 60000 (1 minute).
ASYNC_JOBS_TTL — The amount of time in seconds after which async jobs should expire. The default is 2 days, or 172800 seconds. Expired jobs and their output assets will be deleted from the system.
FILE_UPLOAD_TIMEOUT_MS — Timeout in milliseconds for file uploads to S3. The default is 30000 milliseconds (30 seconds).

Digital Signature Options

SIGNING_SERVICE_URL — This option only affects a PSPDFKit instance with support for Digital Signatures. It defines the URL used by Document Engine when contacting the external signing service required to apply a digital signature to a document.
SIGNING_SERVICE_TIMEOUT — This determines how long Document Engine waits for the response from the signing service when signing a document, in milliseconds. The default is 5000.
DIGITAL_SIGNATURE_CADES_LEVEL — This option is relevant when using a PSPDFKit instance with support for digital signatures. It defines the PAdES/CAdES level to be used when signing a document. The values allowed are b-b, b-t, and b-lt, which correspond to the PAdES signature levels. The default value is b-lt. Note that the OCSP URI mentioned in the signing certificate should be reachable by Document Engine. For more information, refer to the digital signatures overview guide.
TIMESTAMP_AUTHORITY_URL — This option is relevant for PAdES/CAdES signatures with level b-t or above. It defines the URL of the timestamp authority to be used when signing a document. By default, PSPDFKit uses https://freetsa.org/ as the timestamping authority.
TIMESTAMP_AUTHORITY_USERNAME and TIMESTAMP_AUTHORITY_PASSWORD — The optional username and password required to connect to the timestamping authority.
DEFAULT_SIGNER_NAME, DEFAULT_SIGNATURE_REASON, and DEFAULT_SIGNATURE_LOCATION — These options only affect a PSPDFKit instance with support for Digital Signatures. When signing a document, they’re used to prepare the signature metadata.
DIGITAL_SIGNATURE_HASH_ALGORITHM — This option only affects a PSPDFKit instance with support for Digital Signatures. If you require a hash algorithm that’s different than the default sha256, you can choose between any of these allowed values: md5, sha160, sha224, sha256, sha384, or sha512. We recommend using sha256 or higher.
DIGITAL_SIGNATURE_CERTIFICATE_CHECK_TIME — This option only affects a PSPDFKit instance with support for Digital Signatures. If set to current_time (default), the signing certificate’s validity is validated against the current time. If set to signing_time, the signing time (i.e. signature creation time) is used instead. By default, the current_time is used. This means that valid signatures with expired certificates validate as expired.

Trusted Root Certificates for Digital Signatures

Document Engine will search for certificate stores at the /certificate-stores path inside its container. You can mount a folder from the host machine containing your certificates.

Database Options

PGUSER, PGPASSWORD, PGDATABASE, PGHOST, PGPORT — These options determine how the pspdfkit service will communicate with the db service. Don’t forget to replace the default password with a custom one, using the same value for both PGPASSWORD and POSTGRES_PASSWORD.
PGSSL — A Boolean string that can be used to enable connection to a PostgreSQL instance that supports encrypted SSL connections. By default, the certificates installed in the container are used to verify the server certificate. If you need to use a custom CA certificate, you can set PGSSL to "true" and provide the path to the CA certificate file using the PGSSL_CA_CERT_PATH or PGSSL_CA_CERTS options. Defaults to "false".
PGSSL_CA_CERT_PATH — Optional path to the CA certificate file used to verify the server certificate. Mutually exclusive with PGSSL_CA_CERTS.
PGSSL_CA_CERTS — Optional CA certificate used to verify the server certificate. Mutually exclusive with PGSSL_CA_CERT_PATH.
PGSSL_CERT_COMMON_NAME — Common name of the server certificate. Defaults to the value of PGHOST.
PGSSL_DISABLE_HOSTNAME_VERIFY — A Boolean string that can be used to disable verification of the server certificate’s hostname. Defaults to "false".
PGSSL_DISABLE_VERIFY — A Boolean string that can be used to disable verification of the server certificate. Defaults to "false".
ENABLE_DATABASE_MIGRATIONS — This option determines whether to check for pending migrations on the database and attempts to run migrations if necessary. The default is true.
EXIT_AFTER_DATABASE_MIGRATIONS — This option determines whether to exit after running any pending migrations. This could be useful for running dedicated migration jobs on infrastructure. The default is false.
PG_ADMIN_USER — If set, overrides PGUSER. If Document Engine operates with limited database permissions (ENABLE_DATABASE_MIGRATIONS is set to false), this option can be used to provide administrative database credentials for separately executed migration jobs (with both ENABLE_DATABASE_MIGRATIONS and EXIT_AFTER_DATABASE_MIGRATIONS set to true).
PG_ADMIN_PASSWORD — If set, overrides the PGPASSWORD variable, which is a counterpart to PG_ADMIN_USER.
PG_OPERATION_USER — This option sets the name of the database user name to be granted operational permissions over the Document Engine database after migration. Defaults to the PGUSER value.

Asset Storage Options

ASSET_STORAGE_BACKEND — How Document Engine stores uploaded PDFs and attachments. Supported backends are built-in and s3. The default value for this option is built-in.
ENABLE_ASSET_STORAGE_FALLBACK — Determines whether Document Engine will attempt to fetch PDFs and attachments from the secondary backends if they’re not available in the currently configured backend. The default value for this option is false.

It’s recommended to set this value to true during asset storage backend migration. Read more in the asset storage migration guide.
ENABLE_ASSET_STORAGE_FALLBACK_POSTGRES — Enables the built-in database storage backend as a fallback. Default is false. Requires ENABLE_ASSET_STORAGE_FALLBACK to be true.
ENABLE_ASSET_STORAGE_FALLBACK_S3 — Enables the S3 storage backend as a fallback. Default is false. Requires ENABLE_ASSET_STORAGE_FALLBACK to be true.
ENABLE_ASSET_STORAGE_FALLBACK_AZURE — Enables the Azure Blob Storage backend as a fallback. Default is false. Requires ENABLE_ASSET_STORAGE_FALLBACK to be true.
MULTITENANT_ASSETS — When set to true, Document Engine will ensure that each document is associated with a separate copy of all its assets and is not sharing an asset file with any other document. “Assets” in this case includes PDF files, image attachments, and other types of PDF attachments.

This is false by default.

With this option set to true, it’s possible for one document to have an image attachment stored in one S3 bucket, while another document using the exact same image attachment could have a copy of that attachment stored in a different S3 bucket.
USE_UNSAFE_DELETE_FOR_ASSETS — This is set to false by default. When set to true, Document Engine will not attempt to use a trash directory to safely delete assets from the configured asset storage. IMPORTANT — This means that assets cannot be restored should an error happen during the deletion transaction.

S3-Compatible Object Storage

ASSET_STORAGE_S3_BUCKET — S3 bucket name in case ASSET_STORAGE_BACKEND is set to s3. Refer to the asset storage configuration guide for more information.
ASSET_STORAGE_S3_REGION — S3 bucket region.
ASSET_STORAGE_S3_ACCESS_KEY_ID and ASSET_STORAGE_S3_SECRET_ACCESS_KEY — Optional AWS credentials. If they aren’t provided, different platform access options are attempted. Currently supported: 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 — URL scheme used for accessing the S3-compatible object storage, either http:// or https://. The default is https://.

Azure Blob Storage

AZURE_STORAGE_ACCOUNT_NAME, AZURE_STORAGE_ACCOUNT_KEY — Credentials for Azure Blob Storage in case ASSET_STORAGE_BACKEND is set to azure. Refer to the asset storage configuration guide for more information.
AZURE_STORAGE_ACCOUNT_CONNECTION_STRING — Azure Blob Storage connection string, an alternative to AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_ACCOUNT_KEY.
AZURE_STORAGE_DEFAULT_CONTAINER — Container name.

Rendering Cache Options

USE_REDIS_CACHE — If set to true, Document Engine will use Redis as an additional image cache. Supported values are true and false. The default value for this option is true.
REDIS_HOST, REDIS_PORT, REDIS_DATABASE, REDIS_USERNAME, REDIS_PASSWORD — Only relevant if USE_REDIS_CACHE is set to true. These options determine how Document Engine will communicate with Redis.
REDIS_SENTINELS — Only relevant if USE_REDIS_CACHE is set to true. This option replaces REDIS_HOST and REDIS_PORT. Instead, you can supply a comma-separated list of Redis URIs specifying the sentinels your Document Engine connects to. See Redis Sentinel for more information about this.

Example Value: "redis://sentinel1:26379;redis://sentinel2:26379;redis://sentinel3:26379"
REDIS_SENTINELS_GROUP — Needs to be provided if REDIS_SENTINELS is set. This is the name of your Redis sentinel master group, which is passed as a first argument to sentinel monitor in the Sentinel configuration file. You can read more about configuration in the documentation.
REDIS_SSL — If set to true, enables an encrypted SSL connection to Redis.
REDIS_TTL — Time to live in milliseconds for Redis cache keys. By default, this is set to 86400000 milliseconds, which means that Redis cache keys expire after 24 hours if this value isn’t set.
USE_REDIS_TTL_FOR_PRERENDERING — If this is set to true, the value configured for REDIS_TTL is applied to Redis cache entries that Document Engine generates while prerendering a document in response to POST /api/documents/:document_id/prerender requests. If this is set to false, the cache keys generated during prerendering exist in the Redis data store until they’re evicted using the eviction policy configured for the Redis data store or until you upgrade your instance of Document Engine to a newer version. This option is set to true by default.

Logging and Monitoring Options

LOG_LEVEL — This option defines a minimum log level. The allowed values, from higher to lower, are debug, info, warn, and error. The application will emit logs from the chosen level and all lower ones, so if the value is set to debug, it’ll log debug, info, warn, and error. This defaults to info.
HEALTHCHECK_LOGLEVEL — This option defines the log level for the healthcheck endpoint. The allowed values are same as for LOG_LEVEL, with an additional none. This includes root path (/) as well. This defaults to debug.
STATSD_HOST and STATSD_PORT — The host and port of a running StatsD-compatible daemon that Document Engine can report telemetry data to.
STATSD_CUSTOM_TAGS — A comma-separated list of key=value pairs attached as tags to every metric published by Document Engine, e.g. region=eu-1,env=prod.
ENABLE_OPENTELEMETRY — Enable OpenTelemetry tracing. Enabling requires also specifying OTEL_EXPORTER_OTLP_ENDPOINT and, optionally, OTEL_EXPORTER_OTLP_PROTOCOL (defaults to grpc).
OTEL_EXPORTER_OTLP_PROTOCOL (default: grpc), OTEL_EXPORTER_OTLP_ENDPOINT (default: http://localhost:4317), OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME (default: document-engine), OTEL_TRACES_SAMPLER (default: customized parent_based that skips healthchecks and requests to /), OTEL_PROPAGATORS (default: baggage,tracecontext), etc — OpenTelemetry standard parameters.

Conversion Options

SPREADSHEET_MAX_CONTENT_HEIGHT_MM — Specify the maximum content height for a spreadsheet (units in millimeters). Default set to 0 for unlimited. Use this to control memory usage within the Document Engine container during spreadsheet conversions.
SPREADSHEET_MAX_CONTENT_WIDTH_MM — Specify the maximum content width for a spreadsheet (units in millimeters). Default set to 0 for unlimited. Use this to control memory usage within the Document Engine container during spreadsheet conversions.

Mounting Custom Fonts

Document Engine uses a /custom-fonts directory for additional fonts.