Configuration Options

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:

  • 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 in order 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 key has to correspond to the private key you’ll use when generating JWTs in your app. See the Client Authentication guide for details.

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

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

  • 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 1,000,000,000 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.

  • 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) and can be increased if PSPDFKit Server needs to handle large files and defaults to 5,000 milliseconds.

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

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

  • LIBREOFFICE_CONVERSION_TIMEOUT — The timeout in ms applied when converting an Office document to PDF using LibreOffice. Any conversion taking longer than the configured timeout will fail. Defaults to 60,000 ms.

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

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.