Environment Variables

Complete reference for all Weavestream environment variables.

All runtime configuration is environment-driven. The .env.example file in the repository is the authoritative template. This page explains every variable and its operational impact.

Release Pinning

Variable	Default	Notes
`WEAVESTREAM_VERSION`	`latest`	Image tag pulled from `ghcr.io/weavestream/weavestream-`. Always pin in production.*

Host Ports

The default compose.yml only exposes the web UI. Postgres and Redis stay internal.

Variable	Default	Service
`WEB_HOST_PORT`	`3000`	Next.js web UI

Core URLs

Variable	Example	Notes
`APP_URL`	`https://docs.example.com`	Public web origin. Used for cookie domain and CORS allowlisting.
`API_URL`	`https://docs.example.com/api`	Public API origin. Must be reachable from browsers.
`NODE_ENV`	`production`	`development` enables verbose errors and disables some hardening.

Postgres

Variable	Notes
`POSTGRES_USER`	Database role name. Default: `weavestream`.
`POSTGRES_PASSWORD`	Must match the password embedded in `DATABASE_URL`.
`POSTGRES_DB`	Database name.
`DATABASE_URL`	Full connection string. Inside compose, host is `postgres:5432`.

Redis

Variable	Notes
`REDIS_PASSWORD`	Must match the password embedded in `REDIS_URL`.
`REDIS_URL`	Full Redis URL. Inside compose: `redis://:<password>@redis:6379/0`.

Authentication & Sessions

Generate all signing keys with ./scripts/keygen.sh. Each key is 32 random bytes in base64.

Variable	Notes
`JWT_SIGNING_KEY`	HS256 signing key for access tokens.
`JWT_SIGNING_KEY_KID`	Key ID embedded in the JWT header. Bump on rotation.
`JWT_PREVIOUS_KEYS`	Comma-separated `kid:key` pairs kept valid during rotation.
`SESSION_COOKIE_NAME`	Cookie name. Default: `ws_session`.
`SESSION_MAX_AGE_DAYS`	Session cookie lifetime in days.
`ACCESS_TOKEN_TTL_MIN`	Access JWT TTL in minutes. Default: `15`.
`MFA_ENCRYPTION_KEY`	AES-256 key for TOTP secrets at rest.
`COOKIE_SIGNING_KEY`	HMAC key for signed cookies.
`CSRF_SIGNING_KEY`	HMAC key for double-submit CSRF tokens.

Argon2 (Password Hashing)

Variable	Default	Notes
`ARGON2_MEMORY_KB`	`65536`	Memory cost. Do not lower below `65536` in production.
`ARGON2_ITERATIONS`	`3`	Time cost (iterations).
`ARGON2_PARALLELISM`	`1`	Parallelism factor.

Rate Limiting

Variable	Default	Notes
`GLOBAL_RATE_LIMIT_PER_MIN`	`600`	Requests per minute per authenticated user ID (falls back to client IP for unauthenticated requests).
`AUTH_RATE_LIMIT_PER_MIN`	`5`	Login attempts per minute, per IP and per email.
`LOCKOUT_MAX_FAILURES`	`5`	Failed login attempts before account soft-lock.
`LOCKOUT_WINDOW_MIN`	`15`	Soft-lock duration in minutes.

note Proxy-aware rate limiting

The global throttler keys on req.user.id for authenticated requests. For unauthenticated requests, it falls back to the real client IP. The API trusts one X-Forwarded-For hop (set by the Next.js web tier or an upstream proxy). If you run behind two reverse proxies (e.g. Cloudflare → Nginx → api), bump the trust-proxy hop count in apps/api/src/main.ts.

Password Vault Encryption

Variable	Notes
`PASSWORD_ENCRYPTION_KEY`	AES-256-GCM key for credential encryption. 32 bytes, base64-encoded.
`PASSWORD_ENCRYPTION_KEY_KID`	Key ID stamped on each ciphertext blob (e.g. `2026-01`). Bump on rotation.
`PASSWORD_PREVIOUS_KEYS`	Comma-separated `kid:key` pairs from previous rotations.

HaveIBeenPwned

Variable	Default	Notes
`HIBP_ENABLED`	`true`	Set to `false` to disable the outbound breach check. Useful for air-gapped deployments.

File Storage

Uploaded files (attachments, thumbnails, logos, export PDFs) live on the local filesystem under a single host-bind-mounted directory, isolated per tenant by directory:

${FILE_STORAGE_DIR}/<companyId>/uploads/<uploadId>/<filename>
${FILE_STORAGE_DIR}/<companyId>/thumbs/<uploadId>.webp
${FILE_STORAGE_DIR}/<companyId>/exports/<exportId>.pdf

Variable	Default	Notes
`FILE_STORAGE_DIR`	`./data/files`	Storage root, defaults to a path under `DATA_DIR` so files sit alongside `./data/postgres` and `./data/redis`. `compose.yml` bind-mounts `${DATA_DIR}/files` into the api+worker containers and sets this env var for you, so leave it unset for the standard install. Browsers never read the directory directly — every access streams through the API.

Uploads

Variable	Notes
`MAX_UPLOAD_MB`	Server-enforced upload size cap in megabytes. Default: `25`.
`NEXT_PUBLIC_MAX_UPLOAD_MB`	Client-side mirror. Keep in sync with `MAX_UPLOAD_MB`.
`ALLOWED_UPLOAD_MIME`	Comma-separated MIME allowlist. The default includes images, PDFs, documents, archives, scripts, and data files. Add cautiously.

Data Directory

Variable	Default	Notes
`DATA_DIR`	`./data`	Host path for persistent data. Set to an absolute path for NAS deployments (e.g. `/volume1/docker/weavestream`).

Logging

Variable	Default	Notes
`LOG_LEVEL`	`info`	One of: `trace`, `debug`, `info`, `warn`, `error`, `fatal`.

Integrations

Settings for the integration sync engine and provider drivers. Generate encryption keys with ./scripts/keygen.sh.

Credential Encryption

Integration credential bundles (API tokens, secrets) are encrypted with the same kid-tagged envelope scheme as the password vault, but under a separate key so each can be rotated independently.

Variable	Notes
`INTEGRATION_SECRET_KEY`	AES-256-GCM key for integration credentials. 32 bytes, base64-encoded.
`INTEGRATION_SECRET_KEY_KID`	Key ID stamped on each ciphertext blob (e.g. `2026-01`). Bump on rotation. Default: `2026-01`.
`INTEGRATION_PREVIOUS_KEYS`	Comma-separated `kid:key` pairs from previous rotations. Old blobs decrypt seamlessly and re-encrypt on next mutation.

Sync Scheduling

Variable	Default	Notes
`INTEGRATION_SYNC_DEFAULT_CRON`	`0 /4 * *`	5-field cron expression used as the global default sync schedule. Set to `off` to disable all scheduled syncs workspace-wide (manual runs from Admin → Integrations still work). Integrations with a per-record `syncCron` override this value.

Concurrency

Variable	Default	Notes
`INTEGRATION_SYNC_ORCHESTRATOR_CONCURRENCY`	`2`	Parallel orchestrator (fan-out) jobs. Valid range: 1–50.
`INTEGRATION_SYNC_MAPPING_CONCURRENCY`	`5`	Parallel per-mapping (fetch + upsert) jobs. Valid range: 1–100.

HTTP Behaviour

These settings apply to every outbound HTTP call made by integration drivers (e.g. Action1 API requests). Retries use exponential backoff on 429 and 5xx responses.

Variable	Default	Notes
`INTEGRATION_HTTP_TIMEOUT_MS`	`30000`	Socket timeout per request in milliseconds. Valid range: 1,000–120,000.
`INTEGRATION_HTTP_MAX_RETRIES`	`5`	Maximum retry attempts after a retriable failure. Valid range: 0–10.
`INTEGRATION_HTTP_BACKOFF_MS`	`1000`	Base backoff in milliseconds. Each retry sleeps `backoffMs × 2ⁿ`. Valid range: 100–60,000.