Skip to content

Configuration

The API and worker read their configuration from the environment and validate it at start (apps/api/src/env.ts, storage/config.ts). An invalid or missing value stops the process with an error naming the variable.

Variable Default Description
DATABASE_URL required Postgres connection URL.
BETTER_AUTH_SECRET required At least 32 characters. Signs sessions. Changing it signs everyone out, and voids download links unless DOWNLOAD_SIGNING_SECRET is set.
BETTER_AUTH_URL required The public URL people open, e.g. https://necodoc.example.com. The app and /api must be served from it.
PORT 3000 HTTP port. Workers listen too, for health checks.
ROLE all api serves HTTP and enqueues renders; worker renders queued jobs; all does both. See Roles and scaling.
RENDER_CONCURRENCY 2 Render jobs one worker process runs at once (1–32).
RENDER_WAIT_MS 30000 How long a synchronous render call waits for its job before answering 202 with the generation id.
PREVIEW_CONCURRENCY 2 Live previews one API process renders at once (1–32). Previews skip the queue.
APP_VERSION dev Reported in worker heartbeats, to spot mixed versions mid-deploy. The image sets it from the APP_VERSION build arg; the chart sets it from the image tag.
DOWNLOAD_SIGNING_SECRET BETTER_AUTH_SECRET At least 32 characters. Signs download links. Changing it voids live links.
TRUST_PROXY false The number of reverse proxies in front of the API; true means 1. The client address is the Nth X-Forwarded-For hop from the end. The app container’s nginx counts as one, so a TLS proxy in front of it makes 2. Used by API key IP allowlists, share-link rate limits and trusted-header SSO. Too high a count, or any value when clients can reach the API directly, lets clients spoof their address.
WEBHOOK_ALLOW_LOCALHOST false Development only. true lets webhooks use http:// and loopback URLs, for a receiver on the same machine. Never set it in production.
STORAGE_REDIRECT off presigned answers downloads with a redirect to a short-lived S3 presigned URL or Azure SAS instead of streaming through the API. Browsers must reach the bucket.

A label at the top of the app’s sidebar and on the login page, so people can tell which installation they’re in. It’s a label only: each installation is one organisation.

Variable Default Description
INSTANCE_NAME unset The installation’s name, e.g. Harbour Surety (up to 60 characters). Unset hides the label.
INSTANCE_ENV unset prod, staging, dev or demo, shown after the name in red, amber, green or blue.

See Observability.

Variable Default Description
LOG_LEVEL info fatal, error, warn, info, debug, trace or silent.
LOG_FORMAT json (image), pretty (development) json writes one object per line; pretty is for a terminal.
METRICS_PORT unset Serves Prometheus metrics on /metrics on this port, on every role. No authentication: never publish it.
OTEL_EXPORTER_OTLP_ENDPOINT unset Turns on OpenTelemetry tracing to this OTLP endpoint. The other standard OTEL_* variables (protocol, headers, sampler, service name) apply.

Workers certify PDFs whose template or request asks for it (Archival, accessible and certified output). Without a certificate those generations fail.

Variable Default Description
CERTIFY_P12_PATH unset A PKCS#12 (.p12/.pfx) file with the private key and its certificate chain.
CERTIFY_CERT_PATH, CERTIFY_KEY_PATH unset Instead of PKCS#12: PEM files, the certificate (followed by its chain) and the private key (RSA or EC P-256/384/521).
CERTIFY_PASSWORD unset Opens the PKCS#12 file or an encrypted PEM key.
CERTIFY_TSA_URL unset An RFC 3161 timestamp server, e.g. http://timestamp.digicert.com. With it signatures are PAdES B-T; without, B-B. Workers need outbound access to it.

AI features (AI template assistant, AI field detection on overlay templates, suggested descriptions and version notes) exist only with a key. Template content goes to Anthropic when someone uses them.

Variable Default Description
ANTHROPIC_KEY unset An Anthropic API key. Unset or empty turns every AI control off and the AI routes answer 404.
AI_MODEL claude-sonnet-5-5 The Claude model AI features call.
Variable Default Description
AUTH_PASSWORD_ENABLED true false hides and refuses email/password sign-in and registration. Needs at least one SSO provider.
DEMO_MODE false Public demo only. Every visitor is signed in as one shared admin, [email protected] (created on start), with a banner saying the data is public. Turns off password sign-in, registration, SSO and sign out; refuses user management, API key creation, retention, bulk log deletion and queue pause; records webhooks as skipped instead of sending them; and applies the DEMO_* limits below, per client address. Set it on the workers too. Never set it on an installation with real data.
DEMO_RESET_TIME unset Public demo only. When the scheduled pnpm demo:reset runs, as HH:MM in DEMO_RESET_TZ; the banner counts down to it. Keep it in step with the schedule that runs the reset. Unset: no countdown.
DEMO_RESET_TZ America/Toronto The IANA time zone DEMO_RESET_TIME is in, and where the demo’s AI day starts.
DEMO_RENDERS_PER_MINUTE 30 Public demo only. Renders, previews, test runs, re-runs and document PDFs per client address: a burst of this many, refilled evenly. Over it: 429 with Retry-After.
DEMO_UPLOADS_PER_HOUR 30 Public demo only. Asset and PDF uploads per client address.
DEMO_BATCHES_PER_HOUR 10 Public demo only. Batches started per client address.
DEMO_BATCH_MAX_ROWS 25 Public demo only. Rows in one batch.
DEMO_UPLOAD_MAX_MB 5 Public demo only. The largest request body, uploads included (1 to 20).
DEMO_SIGNINS_PER_HOUR 30 Public demo only. Demo sessions created per client address.
DEMO_AI_PER_IP_PER_DAY 20 Public demo with ANTHROPIC_KEY only. AI requests per client address per day; 0 turns AI off in the demo. Counters are in memory and restart with the API.
DEMO_AI_PER_DAY 300 Public demo with ANTHROPIC_KEY only. AI requests per day for the whole demo.
SSO_PROVIDERS none Comma-separated SSO provider ids. Each reads SSO_<ID>_*: TYPE (oidc, saml, header), LABEL, ROLE_MAP, DEFAULT_ROLES, LINK_EXISTING, EMAIL_DOMAINS, plus the protocol’s settings. Full list and IdP guides: Single sign-on.
Variable Default Description
STORAGE_DRIVER disk disk, s3 or azure. See Storage.
STORAGE_DIR /data/files in the image disk: where outputs are written. Relative paths resolve from the working directory.
STORAGE_PREFIX none s3, azure: key prefix, e.g. necodoc/outputs. The disk driver ignores it.
S3_BUCKET required for s3 Bucket name.
S3_REGION us-east-1 Region. Cloudflare R2 uses auto.
S3_ENDPOINT none For MinIO, R2 and other S3-compatible stores. Leave unset for AWS.
S3_FORCE_PATH_STYLE false true for MinIO and most self-hosted stores.
S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY none Static keys; set both or neither. Unset uses the AWS default credential chain (env, profile, IAM role).
S3_SESSION_TOKEN none With temporary keys.
S3_SSE none AES256 or aws:kms server-side encryption.
S3_KMS_KEY_ID none With S3_SSE=aws:kms; unset uses the AWS-managed key.
AZURE_STORAGE_CONTAINER required for azure Container name.
AZURE_STORAGE_CONNECTION_STRING none One way to authenticate.
AZURE_STORAGE_ACCOUNT none Account name. With AZURE_STORAGE_KEY, shared-key auth; alone, DefaultAzureCredential (managed or workload identity).
AZURE_STORAGE_KEY none Account key.
AZURE_STORAGE_ACCOUNT_URL https://<account>.blob.core.windows.net Override for sovereign clouds or Azurite.

Blank values (S3_ENDPOINT=) count as unset.

Variable Image Description
MIGRATE_ON_START necodoc-api true runs migrations before the server starts. Off by default; for single-container installs only, because several replicas would race.
API_URL necodoc-app Where the app’s nginx proxies /api. Default http://api:3000. nginx doesn’t use DNS search domains, so on Kubernetes use the Service’s full name (the chart does).

The necodoc-api image’s command is one of serve (default), migrate or storage-migrate. Anything else runs as a plain command.

Anything in front of the app or API must:

  • Serve the app and /api on the same origin, the one in BETTER_AUTH_URL.
  • Allow request bodies of 25 MB. Uploads and request bodies are capped at 20 MB, plus multipart overhead.
  • Allow upstream reads of RENDER_WAIT_MS plus a margin: 120 seconds with the default, as the app image’s nginx uses.
  • Pass the Origin header through unchanged. Auth requests from another origin are rejected.
  • Append to X-Forwarded-For, with TRUST_PROXY set to the number of proxies in front of the API, counting the app container’s nginx.