Explore PSPDFKit Server configuration options

PSPDFKit Server has been deprecated and replaced by Document Engine. To migrate to Document Engine and unlock advanced document processing capabilities, refer to our migration guide. Learn more about these enhancements on our blog.

You’ll likely want to customize some of the server’s options for your own app. Configuration options for the server are exposed via environment variables for the pspdfkit service in the docker-compose.yml file. The following options are available:

• PORT — This option determines the port where PSPDFKit Server listens for traffic.

• 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 server that supports encrypted SSL connections. Defaults to "false".

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

• TRUSTED_PROXIES — A comma-separated list of IP addresses or IP address ranges of trusted proxies in front of the server. Setting this to default will use the default list of private addresses defined by IPv4 and IPv6.

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

  Leaving this empty or omitting the setting completely will make the server use the IP address of the immediate connection that sent a request.

• ASSET_STORAGE_BACKEND — How PSPDFKit Server stores uploaded PDFs and attachments. Supported backends are built-in and s3. The default value for this option is built-in.

  The S3 backend supports additional configuration; please see the asset storage configuration guide.

• ENABLE_ASSET_STORAGE_FALLBACK — Determines whether PSPDFKit Server will attempt to fetch PDFs and attachments from the secondary backend 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.

• ALLOW_DOCUMENT_UPLOADS — Allow or prevent uploading documents to PSPDFKit Server. 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 PSPDFKit Server. 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.

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

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

• 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, PSPDFKit Server 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.

• USE_REDIS_CACHE — If set to true, PSPDFKit Server 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_PASSWORD — Only relevant if USE_REDIS_CACHE is set to true. These options determine how PSPDFKit Server 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 server 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 PSPDFKit Server 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 PSPDFKit Server to a newer version. This option is set to true by default.

• ASSET_STORAGE_CACHE_SIZE — This option determines the size of the document cache. The size is specified in bytes, and it defaults to 2000000000 (=2 GB).

• DATABASE_CONNECTIONS — This option defines the database connection pool size. The default value for this option is 20.

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

• REMOTE_URL_FETCH_TIMEOUT — This option defines the maximum timeout period used, in milliseconds, when waiting for a remote PDF to download. Please see adding documents from URLs for more information on this feature. It can be increased if PSPDFKit Server needs to handle large files. It defaults to 5000 (5 seconds).

• 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 will log debug, info, warn, and error. This defaults to info.

• SIGNING_SERVICE_URL — This option only affects a PSPDFKit instance with support for Digital Signatures. It defines the URL used by PSPDFKit Server when contacting the external signing service required to apply a digital signature to a document.

• SIGNING_SERVICE_TIMEOUT — This determines how long Server 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 PSPDFKit Server. 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.

• LIBREOFFICE_CONVERSION_TIMEOUT — The timeout in milliseconds applied when converting an Office document to PDF using LibreOffice. Any conversion taking longer than the configured timeout will fail. Defaults to 60000 (1 minute).

• STATSD_HOST and STATSD_PORT — The host and port of a running StatsD-compatible daemon that PSPDFKit Server can report telemetry data to.

• STATSD_CUSTOM_TAGS — A comma-separated list of key=value pairs attached as tags to every metric published by Server, e.g. region=eu-1,env=prod.

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

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

• DOWNLOADER_CERT_FILE_PATH — This option allows you to configure a certificate that’s used to verify the HTTPS server when downloading a remote PDF. Refer to our remote URL certificate configuration guide for more details.

• 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 Server HTTP API. Note that this timeout takes precedence over any other timeout related to the request being processed. Defaults to 60000 (1 minute).

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

• DATABASE_ADMIN_USER — If set, overrides PGUSER. If Server 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).

• DATABASE_ADMIN_USER_PASSWORD — If set, overrides the PGPASSWORD variable, which is a counterpart to DATABASE_ADMIN_USER.

• DATABASE_OPERATION_USER — This option sets the name of the database user name to be granted operational permissions over the Server database after migration. Defaults to the PGUSER value.

Make sure to run docker-compose up --force-recreate pspdfkit when you have an existing PSPDFKit container and want to run it with a new configuration.

Mounting Ephemeral Storage for Temporary Files

PSPDFKit Server uses the /srv/pspdfkit/assets/tmp directory to store temporary files instead of the default /tmp directory.

To store temporary files separately, mount the storage to the /srv/pspdfkit/assets/tmp directory.