Configuration reference
The server is configured entirely through environment variables. The same variables work whether you run it via npm, Docker, Compose, or Helm — only how you set them differs.
Only one variable is strictly required:
CLOUDPDF_LICENSE_KEY (see
Licensing). With a
development key, everything else has a sensible default — a minimal server
runs with just that. Any other license kind also requires
CLOUDPDF_JWT_SECRET and
CLOUDPDF_PASSWORD_VERIFICATION_HMAC_SECRET (plus
CLOUDPDF_PASSWORD_SESSION_SERVER_SECRET when a KMS is
configured) to be real random values of at least 32 bytes — the server fails
closed at boot and names the variable it needs.
Licensing#
| Variable | Default | Description |
|---|---|---|
CLOUDPDF_LICENSE_KEY | — | Required. Your license key; secret:// references resolve through the secrets providers. |
CLOUDPDF_LICENSE_MODE | connected when a key is set | connected or air-gapped. |
See Licensing.
Process#
| Variable | Default | Description |
|---|---|---|
PORT | 3000 | Port the HTTP server listens on. |
HOST | 0.0.0.0 | Interface to bind. |
CLOUDPDF_WORKER_POOL_SIZE | min(2, cpus) | Native PDFium worker threads. Integer, or max to use all cores. See Health & scaling. |
Engine plane#
| Variable | Default | Description |
|---|---|---|
CLOUDPDF_ENGINE_ISOLATION | inline | host runs PDFium in a supervised child process: a native crash costs a sub-second engine respawn instead of the instance. See Health & scaling. |
CLOUDPDF_ENGINE_SHARDS | 1 | Host mode: split the engine into K child processes (worker total must divide evenly). One crash costs 1/K of open documents. |
CLOUDPDF_ENGINE_MAX_IN_FLIGHT | workers × 2 | Admission cap on concurrently dispatched engine jobs; beyond the bounded queue the server sheds with 503 + Retry-After. |
CLOUDPDF_ENGINE_BG_MAX_IN_FLIGHT | ⌊workers / 2⌋ | Of the cap, how much background work (thumbnail warming) may occupy. 0 disables the background lane entirely. |
CLOUDPDF_ENGINE_RECYCLE | off | 1 opts into memory-watermark engine recycling (host mode). Companion knobs: _RECYCLE_SOFT_PCT (70), _RECYCLE_HARD_PCT (85), CLOUDPDF_ENGINE_MAX_RSS_MB, CLOUDPDF_ENGINE_MAX_LIFETIME_HOURS. |
CLOUDPDF_ENCODE_IN_ENGINE | on | 0 reverts image encoding to the API process (one-release escape hatch; rasters cross the engine boundary raw). |
Authentication#
| Variable | Default | Description |
|---|---|---|
CLOUDPDF_JWT_SECRET | dev fallback | HS256 secret used to verify document and admin tokens. Must match the secret your backend signs with. Required (≥32 bytes) under a production license; development keys fall back to a public dev value with a warning. |
CLOUDPDF_API_AUTH_TOKENS | — | Comma-separated static API tokens for trusted backends and tooling (root credential for the admin plane). ≥32 bytes each under a production license. |
CLOUDPDF_PASSWORD_VERIFICATION_HMAC_SECRET | dev fallback | HMAC pepper for the encrypted-PDF password-verification cache — it keeps stored password proofs non-reversible. Required (≥32 bytes) under a production license, whether or not you open encrypted PDFs. |
CLOUDPDF_PASSWORD_SESSION_SERVER_SECRET | dev fallback | Server key material for encrypted-PDF unlock sessions. Required (≥32 bytes) under a production license when a KMS is configured; unused otherwise. |
CLOUDPDF_PASSWORD_SESSION_SERVER_SECRET_ID | dev-v1 | Label for the active session secret, recorded on each session. Changing it (or the secret) invalidates existing sessions. |
See Authentication, and Encrypted-PDF secrets for what the last three protect.
Database#
| Variable | Default | Description |
|---|---|---|
CLOUDPDF_DB_DRIVER | sqlite | sqlite or postgres. |
CLOUDPDF_DB_SQLITE_PATH | ./data/cloudpdf.db | SQLite file path (when driver is sqlite). |
CLOUDPDF_DB_URL | — | Postgres connection string (required when driver is postgres). |
See Database.
Storage (object store)#
| Variable | Default | Description |
|---|---|---|
CLOUDPDF_STORAGE_KIND | fs | fs, s3, gcs, or azure-blob. |
CLOUDPDF_STORAGE_FS_ROOT | ./data/objects | Directory for stored objects (when kind is fs). |
CLOUDPDF_STORAGE_S3_BUCKET | — | Bucket name (S3). |
CLOUDPDF_STORAGE_S3_REGION | — | Bucket region (S3). |
CLOUDPDF_STORAGE_S3_ENDPOINT | — | Custom endpoint for S3-compatible stores (e.g. MinIO). |
See Storage.
Imports (server-side pull)#
On by default with a safe posture (HTTPS-only, public networks, 128 MiB cap). Registered connections let the server pull from your own buckets without presigning.
| Variable | Default | Description |
|---|---|---|
CLOUDPDF_IMPORT_ENABLED | on | Set 0 to disable the import endpoint. |
CLOUDPDF_IMPORT_MAX_BYTES | 128 MiB | Per-document transfer ceiling. |
CLOUDPDF_IMPORT_TIMEOUT_MS | 120000 | Wall-clock budget per transfer attempt. |
CLOUDPDF_IMPORT_MAX_CONCURRENT | 4 | Concurrent transfers per replica (sync + async). |
CLOUDPDF_IMPORT_ALLOW_HTTP | off | Permit http:// URL sources (dev / MinIO). |
CLOUDPDF_IMPORT_ALLOW_PRIVATE_NETWORKS | off | Permit private-address URL sources (dev / in-VPC). |
CLOUDPDF_IMPORT_CONNECTIONS | — | Comma-separated registry of named pull sources (S3, GCS, Azure Blob, filesystem), each configured via CLOUDPDF_IMPORT_CONNECTION_* variables. |
See Imports.
Engine cache#
The cache holds recently used documents and renders so repeat requests are fast. It is disposable — the server rebuilds it from the object store.
| Variable | Default | Description |
|---|---|---|
CLOUDPDF_CACHE_ROOT | ./data/cache | Cache directory. |
CLOUDPDF_CACHE_MAX_BYTES | 4 GiB | Maximum cache size before eviction. |
Fonts#
| Variable | Default | Description |
|---|---|---|
CLOUDPDF_FALLBACK_FONTS | — | JSON array of fallback fonts ({ key, path, … }) for glyphs a document’s own fonts are missing. |
See Fallback fonts.
Lifecycle & migrations#
| Variable | Default | Description |
|---|---|---|
CLOUDPDF_AUTO_MIGRATE | on for SQLite, off for Postgres | Apply pending migrations on boot. |
CLOUDPDF_FAIL_ON_PENDING | off | Refuse to start if migrations are pending. Recommended for multi-replica deploys. |
CLOUDPDF_AUTO_PROVISION_TENANT | off | Lazily create tenant rows. Dev convenience — leave off in production. |
See Migrations.
Shutdown & observability#
| Variable | Default | Description |
|---|---|---|
CLOUDPDF_SHUTDOWN_TIMEOUT_MS | 30000 | Budget for closing in-flight HTTP during shutdown before teardown proceeds anyway. Keep it below your orchestrator’s kill deadline. |
CLOUDPDF_SHUTDOWN_DRAIN_MS | 0 | Settle window after /readyz flips to 503 (and SSE streams end) before the listener closes — for probe-driven load balancers. |
CLOUDPDF_METRICS | off | 1 exposes an unauthenticated Prometheus /metrics endpoint (scrape it inside your private network). |
Optional adapters#
These are opt-in. You only need them for the corresponding feature.
| Variable | Default | Description |
|---|---|---|
CLOUDPDF_CDN_KIND | none | Sign delivery URLs via a CDN: bunny, cloud-cdn, cloudfront, azure-fd, custom-hmac. |
CLOUDPDF_KMS_KIND | static | Key management for encrypted-PDF sessions: aws-kms, gcp-kms, azure-kv. |
CLOUDPDF_SECRETS_PROVIDERS | env | Comma-separated registry of secret sources. |
See CDN, KMS & secrets.
The CLI prints this whole surface at any time:
cloudpdf-server —help.