Environment variables
Every environment variable, grouped by the application that reads it, with examples, sources and production requirements.
Reviewed 2026-11-13 against apps/api/src/config.ts, apps/scanner/src/app.ts, the Vite configs, scripts and infrastructure templates. Values below are placeholders; never put real secrets in documentation, Git, images or logs.
apps/api/src/config.ts validates the API's variables at startup and reports names only, never values. With NODE_ENV=production it also refuses non-TLS URLs, a missing database CA, a missing scanner (when storage is configured), provider mocks and ADMIN_DEV_EMAIL. Use NODE_ENV=production for staging too; LYNKORIA_ENVIRONMENT says which environment it is.
Where the values live: .env.example is the local template (copy to .env, gitignored). In staging and production, OpenTofu sets every API variable on App Platform (infra/opentofu/platform/app.tf): generated secrets come from secrets.tf and the zone stack, connection strings from the managed databases, and account-specific values from GitHub environment variables (step 4). Nothing is filled in by hand.
Generate secrets with: openssl rand -base64 32 (32-byte secrets), openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 (messaging key), or pnpm --filter @lynkoria/api exec tsx scripts/gen-secrets.ts (local development only).
API (apps/api)
Runtime and network
| Name | Required | Description | Example | Source | Production requirement |
|---|---|---|---|---|---|
NODE_ENV | No (development) | development, test or production; production enables the strict checks above | production | Deployment | production in staging and production |
LYNKORIA_ENVIRONMENT | No (staging) | Which environment this deployment serves; keys/environments of the other kind are rejected | production | Deployment | Matches the deployment; lynk_live_ keys only work with production |
PORT | No (3001) | HTTP and Socket.IO port | 8080 | Platform | App Platform http_port |
METRICS_PORT | No (9464) | Prometheus metrics listener | 9464 | Platform | Internal port only; never routed publicly |
LOG_LEVEL | No (info) | pino level | info | Operator | info or warn; logs redact tokens and secrets at any level |
PUBLIC_API_ORIGIN | No (http://localhost:3001) | Public API origin (OpenAPI servers, links) | https://api.example.com | DNS | HTTPS |
CONSOLE_ORIGIN | Production | Exact console origin for CORS and the cross-origin mutation check | https://console.example.com | DNS | HTTPS, required |
ALLOWED_ORIGINS | No (empty) | Comma-separated exact browser origins for sockets and CORS; each project also has its own list | https://app.example.com | Product teams | Exact HTTPS origins only, no wildcards |
WEBHOOK_ALLOWED_ORIGINS | No (empty) | Operator-approved product webhook origins; empty disables production webhook delivery | https://hooks.example.com | Product teams | HTTPS only; the worker re-checks and never follows redirects |
TRUST_PROXY | No (false) | Read the client IP from CLIENT_IP_HEADER instead of the socket address | true | Deployment | true only behind an ingress that overwrites that header |
CLIENT_IP_HEADER | No (do-connecting-ip) | The one header the trusted ingress sets; x-forwarded-for uses its last entry | cf-connecting-ip | Ingress documentation | do-connecting-ip on App Platform; cf-connecting-ip behind Cloudflare |
CF_ORIGIN_SECRET | With cf-connecting-ip | Origin lock: every route except /health/*, and socket upgrades, need header x-lynkoria-origin-secret with this value | 48 random bytes, base64 | Cloudflare Transform Rule | 32+ characters; required in production when CLIENT_IP_HEADER=cf-connecting-ip |
Database and Redis
| Name | Required | Description | Example | Source | Production requirement |
|---|---|---|---|---|---|
DATABASE_URL | Yes | Pooled connection as the runtime role | postgresql://lynkoria_app:…@pool-host:25061/lynkoria | Managed PostgreSQL pool | Private endpoint; runtime role (no DDL) |
DATABASE_URL_DIRECT | Production | Direct runtime-role session for LISTEN (the pooler cannot hold it) | postgresql://lynkoria_app:…@db-host:25060/lynkoria | Managed PostgreSQL | Required; never the migration role |
DATABASE_CA_CERT | Production | PEM CA; enables verified TLS (URL sslmode is ignored when set) | CA certificate PEM text | Provider "Download CA" | Required; literal \n escapes accepted |
DATABASE_POOL_MAX | No (10) | Pool size per API instance | 10 | Capacity planning | Below the pooler's per-user limit |
REDIS_URL | Yes | Redis/Valkey for presence leases, rate limits and worker locks | rediss://default:…@valkey-host:25061 | Managed Valkey | rediss:// (TLS, verified) |
LiveKit
| Name | Required | Description | Example | Source | Production requirement |
|---|---|---|---|---|---|
LIVEKIT_URL | Yes | Client signaling URL returned with every join token | wss://rtc.example.com | Media DNS | wss:// |
LIVEKIT_API_URL | No | Server API URL; defaults to LIVEKIT_URL with http(s) | https://rtc.example.com | Media DNS | HTTPS if set |
LIVEKIT_KEYS_JSON | Yes | Key reference → {apiKey, apiSecret}; environments pick a reference in the console | {"prod-vibelynk":{"apiKey":"API…","apiSecret":"…"}} | LiveKit keys: you generate | One key per project environment; secrets ≥32 characters |
LIVEKIT_WEBHOOK_KEY | Yes | Key id LiveKit signs webhooks with | lk_platform_webhook | LiveKit webhook.api_key | Dedicated to webhooks |
LIVEKIT_WEBHOOK_SECRET | Yes | Matching secret (≥32 characters) | 32+ random characters | Generated, mirrored in LiveKit | Secret manager |
Secrets and tokens
| Name | Required | Description | Example | Source | Production requirement |
|---|---|---|---|---|---|
SERVICE_KEY_PEPPER | Yes | HMAC pepper for service-key digests (≥32 bytes, base64) | output of openssl rand -base64 32 | Generated | Changing it invalidates every service key |
WEBHOOK_SECRET_MASTER | Yes | Master for derived product webhook secrets (≥32 bytes, base64) | output of openssl rand -base64 32 | Generated | Must differ from the pepper; changing it rotates every webhook secret |
MESSAGING_JWT_PRIVATE_KEY | Yes | ES256 (P-256) PKCS8 key that signs messaging tokens | PKCS8 PEM text | openssl genpkey | Secret manager; escaped newlines accepted |
MESSAGING_JWT_KID | Yes | Key id for the current signing key | msg-2026-11 | Operator | Unique per key |
MESSAGING_JWT_PREVIOUS_KEYS_JSON | No ({}) | Retired kid → public PEM, accepted until their tokens expire | {"msg-2026-10":"<public key PEM>"} | Previous key | Keep at least one token TTL (10 min) after rotation, then remove |
Console
| Name | Required | Description | Example | Source | Production requirement |
|---|---|---|---|---|---|
CF_ACCESS_TEAM_DOMAIN | No | Cloudflare Access team; when set with CF_ACCESS_AUD, every console request also needs a matching Access identity | team.cloudflareaccess.com | Cloudflare Zero Trust | Both or neither; recommended as defense in depth |
CF_ACCESS_AUD | No | Access application audience tag | 64-hex audience | Cloudflare Zero Trust | Both or neither |
ADMIN_DEV_EMAIL | No | Local only: treat every console request as this user | dev@example.com | Developer | Refused in production |
CONSOLE_LOGIN_RATE_LIMIT | No (20) | Sign-in attempts per client IP per minute (each email is also capped at 10) | 20 | Operator | Depends on a trustworthy CLIENT_IP_HEADER |
Object storage and recording
| Name | Required | Description | Example | Source | Production requirement |
|---|---|---|---|---|---|
SPACES_REGION | No (sgp1) | S3 region | sgp1 | Provider | Matches the bucket |
SPACES_ENDPOINT | With storage | S3 endpoint | https://sgp1.digitaloceanspaces.com | Provider | HTTPS; all four storage variables or none |
SPACES_BUCKET | With storage | Private bucket for attachments and recordings | lynkoria-prod-attachments | Bucket you create | Private, CORS and lifecycle applied |
SPACES_ACCESS_KEY_ID | With storage | Access key | DO00… | Spaces key (not an API token) | Scoped to the bucket where supported |
SPACES_SECRET_ACCESS_KEY | With storage | Secret key | (secret) | Spaces key | Secret manager |
SPACES_FORCE_PATH_STYLE | No (false) | Path-style addressing for local S3-compatible stores | true | Local only | false |
EGRESS_S3_ENDPOINT | No | Storage endpoint as reachable from Egress, if different | https://sgp1.digitaloceanspaces.com | Egress network | Only when Egress uses another route |
RECORDING_RETENTION_DAYS | No (30) | Finished recordings and files are deleted after this many days | 30 | Product/legal decision | Agree per product (ADR 009) |
Malware scanning
| Name | Required | Description | Example | Source | Production requirement |
|---|---|---|---|---|---|
SCANNER_URL | Production with storage | Private scanner endpoint | https://10.104.0.5:3344 | Scanner host | VPC-private address; https: unless the scanner is on the same host |
SCANNER_TOKEN | With SCANNER_URL | This API's consumer token (≥32 characters) | (secret) | Same value as in SCANNER_TOKENS_JSON | Secret manager; rotate by listing the new token next to the old one on the scanner first |
SCANNER_CA_CERT | With an https: scanner on a private CA | PEM of the CA that issued the scanner certificate; the only CA trusted for the scanner | CA PEM | OpenTofu (secrets.tf); scripts/scanner-pki.sh locally | Literal \n escapes accepted; concatenate old and new during a CA rotation (ADR 023) |
ATTACHMENT_SCANNING | No (required) | required or disabled | required | Operator | disabled only with a recorded decision; attachments are then unscanned |
Push notifications
| Name | Required | Description | Example | Source | Production requirement |
|---|---|---|---|---|---|
PUSH_CREDENTIALS_JSON | No ({}) | Credential reference → {fcm?, apns?}; environments reference one | {"vibelynk":{"fcm":{"projectId":"…","clientEmail":"…","privateKey":"…"}}} | Firebase service account, APNs .p8 key | Secret manager; one entry per product |
PUSH_FCM_BASE_URL | No | Test mock for FCM | http://127.0.0.1:9100 | Tests | Refused in production |
PUSH_FCM_TOKEN_URL | No | Test mock for the Google OAuth token endpoint | http://127.0.0.1:9100/token | Tests | Refused in production |
PUSH_APNS_BASE_URL | No | Test mock for APNs | https://127.0.0.1:9101 | Tests | Refused in production |
Limits, workers and observability
| Name | Required | Description | Example | Source | Production requirement |
|---|---|---|---|---|---|
MAX_MESSAGE_BYTES | No (16384) | Maximum message body size | 16384 | Operator | |
MESSAGE_RATE_LIMIT | No (120) | Messages per user per minute | 120 | Operator | |
SERVICE_RATE_LIMIT | No (6000) | Requests per service key per minute | 6000 | Operator | |
SHUTDOWN_DRAIN_SECONDS | No (0) | Seconds /health/ready reports draining before connections close on SIGTERM | unset on App Platform (its termination.drain_seconds drains first); 5–15 behind other ingresses | Operator | Keep below the platform's kill timeout minus 15 s |
WORKERS_ENABLED | No (true) | Outbox, push delivery, retention, usage and reconciliation workers | true | Operator | Keep true on every instance (ticks coordinate through Redis locks) |
OTEL_EXPORTER_OTLP_ENDPOINT | No | OTLP trace collector; tracing is off when unset | http://otel-collector:4318 | Monitoring | Collector on the private network |
OTEL_SERVICE_NAME | No (lynkoria-api) | Service name on traces | lynkoria-api | Monitoring |
Malware scanner (apps/scanner)
| Name | Required | Description | Example | Source | Production requirement |
|---|---|---|---|---|---|
SCANNER_TOKENS_JSON | Yes | Consumer → bearer token (≥32 characters each) | {"lynkoria-api":"…","fidescript":"…"} | Generated | One token per consumer, or a list of up to 4 during rotation ({"lynkoria-api":["new…","old…"]}) |
PORT | No (3344) | Listener | 3344 | Compose | Bound to the private interface (SCANNER_BIND) |
LOG_LEVEL | No (info) | pino level | info | Operator | |
CLAMD_HOST / CLAMD_PORT | No (127.0.0.1/3310) | clamd INSTREAM endpoint | clamd / 3310 | Compose | Internal network only |
SCANNER_MAX_BYTES | No (50 MiB) | Largest accepted file | 52428800 | Operator | ≥ the largest project attachment limit |
SCANNER_TIMEOUT_MS | No (30000) | Per-scan timeout | 30000 | Operator | |
SCANNER_MAX_CONCURRENCY | No (4) | Concurrent scans; excess requests get 429 | 4 | Capacity | Size to clamd CPU and memory |
SCANNER_MAX_SIGNATURE_AGE_HOURS | No (48) | Refuse to scan with older signatures (fail closed) | 48 | Operator | |
SCANNER_ARCHIVE_MAX_UNCOMPRESSED | No (200 MiB) | ZIP/GZIP total uncompressed size limit | 209715200 | Operator | |
SCANNER_ARCHIVE_MAX_ENTRIES | No (5000) | ZIP entry limit | 5000 | Operator | |
SCANNER_ARCHIVE_MAX_RATIO | No (100) | Compression-ratio limit | 100 | Operator | |
SCANNER_TLS_CERT_FILE / SCANNER_TLS_KEY_FILE | Both or neither | Serve HTTPS (TLS 1.3) with this certificate and key; reloaded on SIGHUP | /tls/tls.crt / /tls/tls.key | OpenTofu cloud-init; scripts/scanner-pki.sh locally | Required by infra/scanner/compose.yaml |
infra/scanner/compose.yaml also reads SCANNER_IMAGE (image reference), SCANNER_BIND (private IP to publish on) and SCANNER_TLS_DIR (directory with tls.crt, tls.key and ca.crt).
Console build (apps/admin)
| Name | Required | Description | Example | Production requirement |
|---|---|---|---|---|
VITE_API_ORIGIN | Production | API origin compiled into the console (public value) | https://api.example.com | Matches PUBLIC_API_ORIGIN; add it to the console CSP |
VITE_DOCS_URL | No | Documentation link in the sidebar; hidden when unset in builds | https://lynkoria.com/docs | |
LYNKORIA_API_PROXY | No | Dev server only: where /v1 is proxied | http://127.0.0.1:3011 | Not used in builds |
Playground (apps/playground, development only)
| Name | Required | Description | Example |
|---|---|---|---|
PLAYGROUND_SERVICE_KEY | For the demo | Staging service key used by the dev-server demo backend; never in a build | lynk_test_… from pnpm db:seed |
VITE_API_ORIGIN | No | API origin for the browser | http://localhost:3001 |
Landing page and documentation (apps/docs)
| Name | Required | Description | Example | Production requirement |
|---|---|---|---|---|
NEXT_PUBLIC_SITE_URL | No | Public origin for canonical URLs, sitemap.xml and robots.txt (build time) | https://lynkoria.com | Defaults to https://lynkoria.com; set the staging origin for staging builds |
Local infrastructure (infra/local/compose.yaml)
LYNKORIA_PG_PORT, LYNKORIA_REDIS_PORT, LYNKORIA_VALKEY_PORT and LYNKORIA_CLAMD_PORT override host ports when the defaults collide with other services; update DATABASE_URL/REDIS_URL to match.
Scripts and tooling
| Name | Used by | Description |
|---|---|---|
SEED_OWNER_EMAIL | dist/bootstrap.js, pnpm db:seed | First console owner (seed falls back to ADMIN_DEV_EMAIL) |
MIGRATIONS_DIR | dist/migrate.js | Override the migrations folder (defaults to the bundled drizzle/) |
SEED_LIVEKIT_KEY_REF | pnpm db:seed | LiveKit key reference for sample products |
TOFU_STATE_BUCKET, SPACES_ACCESS_KEY_ID, SPACES_SECRET_ACCESS_KEY, DIGITALOCEAN_ACCESS_TOKEN, CLOUDFLARE_API_TOKEN, TF_VAR_* | infra/opentofu/run.sh, .github/workflows/deploy.yml, infra.yml | OpenTofu backend, provider credentials and stack variables; the full list is in step 4 |
PUBLIC_API_ORIGIN, LYNKORIA_SERVICE_KEY | scripts/verify-production.mjs | Deployed API and a disposable scoped key |
BASE_URL, SERVICE_KEY, VUS, DURATION, RATE, RECEIVERS, MESSAGES, RUN_ID | loadtest/, apps/api/scripts/load-messaging.ts | Load-test targets and shape |
LK_URL, LK_KEY, LK_SECRET, LK_CONTAINER, LK_NETWORK, STEPS, RES | loadtest/livekit/run.sh | LiveKit load-test inputs |
I_HAVE_PRODUCTION_AUTHORIZATION | Load tests | Must be yes to target a lynkoria.com host; get written authorization first |
S3_TEST_ENDPOINT, S3_TEST_ACCESS_KEY, S3_TEST_SECRET_KEY, SCANNER_TEST_CLAMD, TEST_LOG_LEVEL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET | API tests | Test infrastructure overrides; tests always use a _test database |
Consistency notes
- Project features, quotas, origins and retention are database settings managed in the console, not environment variables.
CLIENT_IP_HEADERis set tocf-connecting-ipininfra/opentofu/platform/app.tf, since the API is proxied;CF_ORIGIN_SECRETcomes from the zone stack.- The migration job gets its own
DATABASE_URL_DIRECT(thelynkoria_migraterole); the API service never receives migration credentials. - GitHub Actions secrets and variables for deployment are listed in step 4.
Manual deployment with OpenTofu
Deploy Lynkoria to production from your own machine with the repository's OpenTofu stacks, step by step — prerequisites, the docs and console sites first, then the realtime platform.
Cloudflare zone
Every Cloudflare record and setting for lynkoria.com, which OpenTofu stack manages it, and the few items that stay manual.