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. |
Instance identity
Section titled “Instance identity”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. |
Logs, metrics and traces
Section titled “Logs, metrics and traces”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. |
Certifying PDFs
Section titled “Certifying PDFs”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. |
Sign-in
Section titled “Sign-in”| 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. |
Storage
Section titled “Storage”| 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.
Image only
Section titled “Image only”| 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.
Proxies and load balancers
Section titled “Proxies and load balancers”Anything in front of the app or API must:
- Serve the app and
/apion the same origin, the one inBETTER_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_MSplus a margin: 120 seconds with the default, as the app image’s nginx uses. - Pass the
Originheader through unchanged. Auth requests from another origin are rejected. - Append to
X-Forwarded-For, withTRUST_PROXYset to the number of proxies in front of the API, counting the app container’s nginx.