--- title: "Configuration reference" description: "Every CLOUDPDF_* environment variable the CloudPDF server reads, with defaults and where each one matters." source: "https://www.cloudpdf.com/docs/server/configuration" --- # Configuration reference The server is configured entirely through environment variables. The same variables work whether you run it via [npm](https://www.cloudpdf.com/docs/server/deployment/npm), [Docker](https://www.cloudpdf.com/docs/server/deployment/docker), [Compose](https://www.cloudpdf.com/docs/server/deployment/docker-compose), or [Helm](https://www.cloudpdf.com/docs/server/deployment/helm) — only *how* you set them differs. > Only one variable is strictly required: > **`CLOUDPDF_LICENSE_KEY`** (see > [Licensing](https://www.cloudpdf.com/docs/server/configuration/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](https://www.cloudpdf.com/docs/server/configuration/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](https://www.cloudpdf.com/docs/server/operations/health-and-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](https://www.cloudpdf.com/docs/server/operations/health-and-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](https://www.cloudpdf.com/docs/server/configuration/authentication), and [Encrypted-PDF secrets](https://www.cloudpdf.com/docs/server/configuration/authentication#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](https://www.cloudpdf.com/docs/server/configuration/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](https://www.cloudpdf.com/docs/server/configuration/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](https://www.cloudpdf.com/docs/server/configuration/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](https://www.cloudpdf.com/docs/server/configuration/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](https://www.cloudpdf.com/docs/server/operations/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](https://www.cloudpdf.com/docs/server/configuration/adapters). > The CLI prints this whole surface at any time: > `cloudpdf-server --help`. ## Where to set these - [npm](https://www.cloudpdf.com/docs/server/deployment/npm) — Shell environment or a process-manager unit file. - [Docker](https://www.cloudpdf.com/docs/server/deployment/docker) — -e flags, or an --env-file. - [Docker Compose](https://www.cloudpdf.com/docs/server/deployment/docker-compose) — The environment: block and a .env file. - [Helm](https://www.cloudpdf.com/docs/server/deployment/helm) — config: (ConfigMap) and existingSecret (Secret).