Configuration Options
PSPDFKit Server has been deprecated and replaced by Document Engine. All PSPDFKit Server and PSPDFKit for Web Server-Backed licenses will work as before and be supported until 15 May 2024 (we will contact you about license migration). To start using Document Engine, refer to the migration guide. With Document Engine, you’ll have access to robust new capabilities (read the blog for more information).
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 thepspdfkit
service will communicate with thedb
service. Don’t forget to replace the default password with a custom one, using the same value for bothPGPASSWORD
andPOSTGRES_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, useopenssl 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 todefault
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 arebuilt-in
ands3
. The default value for this option isbuilt-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 isfalse
.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 aretrue
andfalse
. The default value for this option istrue
. -
ALLOW_REMOTE_DOCUMENTS
— Allow or prevent adding documents from URLs to PSPDFKit Server. Supported values aretrue
andfalse
. The default value for this option istrue
. -
ALLOW_DOCUMENT_GENERATION
— Allow or prevent creating documents with PDF Generation. The default value for this option istrue
. -
ALLOW_REMOTE_ASSETS_IN_GENERATION
— Allow or prevent loading the resources from the network during PDF generation. If set tofalse
, any images, stylesheets, and other assets won’t be loaded from external URLs. The default value for this option istrue
. -
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 to20000
(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 of1000000000
(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 isfalse
. -
IGNORE_INVALID_ANNOTATIONS
— If set totrue
, PSPDFKit Server will ignore invalid annotations on PDF export instead of throwing an error. Invalid annotations will still be logged. If set tofalse
, PDF export for PDFs containing invalid annotations will throw and log an error. Supported values aretrue
andfalse
. The default value for this option istrue
. -
USE_REDIS_CACHE
— If set totrue
, PSPDFKit Server will use Redis as an additional image cache. Supported values aretrue
andfalse
. The default value for this option istrue
. -
REDIS_HOST
,REDIS_PORT
,REDIS_DATABASE
,REDIS_PASSWORD
— Only relevant ifUSE_REDIS_CACHE
is set totrue
. These options determine how PSPDFKit Server will communicate with Redis. -
REDIS_SENTINELS
— Only relevant ifUSE_REDIS_CACHE
is set totrue
. This option replacesREDIS_HOST
andREDIS_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 ifREDIS_SENTINELS
is set. This is the name of your Redis sentinel master group, which is passed as a first argument tosentinel monitor
in the Sentinel configuration file. You can read more about configuration in the documentation. -
REDIS_SSL
— If set totrue
, enables an encrypted SSL connection to Redis. -
REDIS_TTL
— Time to live in milliseconds for Redis cache keys. By default, this is set to86400000
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 totrue
, the value configured forREDIS_TTL
is applied to Redis cache entries that PSPDFKit Server generates while prerendering a document in response toPOST /api/documents/:document_id/prerender
requests. If this is set tofalse
, 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 totrue
by default. -
ASSET_STORAGE_CACHE_SIZE
— This option determines the size of the document cache. The size is specified in bytes, and it defaults to2000000000
(=2 GB). -
DATABASE_CONNECTIONS
— This option defines the database connection pool size. The default value for this option is20
. -
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 to5000
(5 seconds). -
LOG_LEVEL
— This option defines a minimum log level. The allowed values, from higher to lower, aredebug
,info
,warn
, anderror
. The application will emit logs from the chosen level and all lower ones, so if the value is set todebug
, it will logdebug
,info
,warn
, anderror
. This defaults toinfo
. -
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 is5000
. -
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 areb-b
,b-t
, andb-lt
, which correspond to the PAdES signature levels. The default value isb-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 levelb-t
or above. It defines the URL of the timestamp authority to be used when signing a document. By default, PSPDFKit useshttps://freetsa.org/
as the timestamping authority. -
TIMESTAMP_AUTHORITY_USERNAME
andTIMESTAMP_AUTHORITY_PASSWORD
— The optional username and password required to connect to the timestamping authority. -
DEFAULT_SIGNER_NAME
,DEFAULT_SIGNATURE_REASON
, andDEFAULT_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 defaultsha256
, you can choose between any of these allowed values:md5
,sha160
,sha224
,sha256
,sha384
, orsha512
. We recommend usingsha256
or higher. -
DIGITAL_SIGNATURE_CERTIFICATE_CHECK_TIME
— This option only affects a PSPDFKit instance with support for Digital Signatures. If set tocurrent_time
(default), the signing certificate’s validity is validated against the current time. If set tosigning_time
, the signing time (i.e. signature creation time) is used instead. By default, thecurrent_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 to60000
(1 minute). -
STATSD_HOST
andSTATSD_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 ofkey=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 manypspdfkitd
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 to16
. -
PSPDFKIT_WORKER_TIMEOUT
— The timeout in milliseconds for thepspdfkitd
process to handle any PDF-related work. By default, it’s set to60000
(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 to20000
(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 to60000
(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 istrue
. -
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 isfalse
. -
DATABASE_ADMIN_USER
— If set, overridesPGUSER
. If Server operates with limited database permissions (ENABLE_DATABASE_MIGRATIONS
is set tofalse
), this option can be used to provide administrative database credentials for separately executed migration jobs (with bothENABLE_DATABASE_MIGRATIONS
andEXIT_AFTER_DATABASE_MIGRATIONS
set totrue
). -
DATABASE_ADMIN_USER_PASSWORD
— If set, overrides thePGPASSWORD
variable, which is a counterpart toDATABASE_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 thePGUSER
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.