Configuration

Every environment variable the control plane reads, what it defaults to, and what happens if you get it wrong.

The control plane's configuration is one validated schema. Values are read in configuration factories only — nothing else in the codebase touches process.env.

On a self-hosted install these live in /etc/sthora/.env, written by the installer at mode 0600. In development they live in apps/backend/.env; only .env.example is ever committed.

Two values have no safe default

DATABASE_URL and AUTH_SECRET. Generate the secret with openssl rand -hex 32 and never reuse a placeholder.

Service

Variable	Default
`NODE_ENV`	`development`	`development` \| `test` \| `production`
`APP_NAME`	`cloud-api`	Reported by `/health` and in the OpenAPI document
`APP_VERSION`	`0.0.1`	Same
`PORT`	`4600`	HTTP port
`APP_ROLE`	`all`	`all` \| `api` \| `worker`. One container runs both on a small box; the cloud deployment scales them separately from the same image.

Database and Redis

Variable	Default
`DATABASE_URL`	—	Required. Must use `postgresql://` or `postgres://`.
`REDIS_URL`	`redis://localhost:6379`	BullMQ, the live metric cache, and the log bus.

Redis maxmemory-policy must be noeviction

BullMQ stores job state in Redis. An LRU policy silently evicts it and deployments disappear with no error anywhere. If you want a caching Redis with eviction, that is a second instance or a second logical database with its own policy — never the queue's.

Authentication and sessions

Variable	Default
`AUTH_SECRET`	—	Required, minimum 32 characters. Signs sessions and one-time tokens, and keys API-token digests.
`AUTH_SESSION_TTL_HOURS`	`720`	Absolute session lifetime.
`AUTH_SESSION_RENEW_AFTER_HOURS`	`24`	How old a session must be before a request slides its expiry forward.
`AUTH_RESET_TOKEN_TTL_MINUTES`	`60`	Password reset. Capped at 60 by the schema.
`AUTH_VERIFICATION_TOKEN_TTL_MINUTES`	`1440`	Email verification.
`AUTH_INVITATION_TTL_HOURS`	`168`	Invitation validity.
`AUTH_COOKIE_NAME`	`cloud.session`	The `__Host-` prefix is applied automatically in production.
`AUTH_TRUSTED_ORIGINS`	Empty	CSRF allow-list — origins whose unsafe-method requests carrying the session cookie the API will act on. Empty means same-origin only, which is the self-hosted default.
`SIGNUP_ENABLED`	`false`	Self-service signup. Off answers `404`, not `403`. See signup.

HTTP surface

Variable	Default
`CORS_ALLOWED_ORIGINS`	Empty	Comma-separated. Empty disables CORS, correct for a self-hosted install serving the dashboard and API on one origin.
`THROTTLE_TTL_SECONDS`	`60`	Global rate-limit window.
`THROTTLE_LIMIT`	`120`	Requests per window per client.
`TRUSTED_PROXY_HOPS`	`0`	How many reverse proxies sit in front. Set to `1` for the shipped compose topology, which puts Traefik in front.

TRUSTED_PROXY_HOPS matters more than it looks

It configures Express's trust proxy, which is what makes the rate limiter and every audit record key on the real client's address rather than the proxy's — or, left at 0, protects against a client forging its own address via X-Forwarded-For.

Secret encryption

Variable	Default
`SECRET_ENCRYPTION_KEY_FILE`	Unset	Preferred. Path to the 32-byte hex master key.
`SECRET_ENCRYPTION_KEY`	Unset	The key inline. Readable through `/proc`, through `docker inspect`, and out of any crash dump — prefer the file.

With neither set, the API starts and every route that does not touch a secret keeps working. The ones that do say exactly what is missing.

Metrics and monitoring

Variable	Default
`HOST_PROC_PATH`	Unset	Where the host's `/proc` is mounted.
`HOST_SYS_PATH`	Unset	The host's `/sys`.
`HOST_ROOT_PATH`	Unset	The host's `/`.
`DOCKER_SOCKET_PATH`	`/var/run/docker.sock`
`LOCAL_SERVER_NAME`	`local`	Name the control plane's own machine is registered under on first boot.
`METRICS_SAMPLE_INTERVAL_SECONDS`	`15`
`METRICS_MINUTE_RETENTION_DAYS`	`7`	Minute rows before hourly rollup.
`METRICS_RETENTION_DAYS`	`90`

Leave the three HOST_* paths unset outside a container. Unset inside one means every metric describes that container rather than the machine — which looks entirely plausible on a dashboard and is wrong.

Platform database backup

Variable	Default
`PLATFORM_DATABASE_CONTAINER`	Unset	Container name of the platform's own PostgreSQL. Unset means the database is external and its backups are its owner's job.
`PLATFORM_DATABASE_USER`	`sthora`
`PLATFORM_BACKUP_RETENTION_COUNT`	`7`

Deploy pipeline

Variable	Default
`DEPLOY_DATA_ROOT`	`/var/lib/sthora`	Where the platform writes on the managed server: source trees, staged archives, capped build logs.
`DEPLOY_UPLOAD_STAGING_PATH`	`/var/lib/sthora/uploads`	Where uploads land on the control plane before the driver moves them.
`DEPLOY_MAX_ARCHIVE_BYTES`	`209715200`	200 MB.
`DEPLOY_MAX_ARCHIVE_ENTRIES`	`20000`
`DEPLOY_MAX_EXTRACTED_BYTES`	`2147483648`	2 GB.
`DEPLOY_LOG_MAX_BYTES`	`16777216`	Build log cap on disk.
`DEPLOY_LOG_TAIL_BYTES`	`4096`	How much of the tail the history list keeps on the row.
`DEPLOY_MIN_FREE_DISK_FRACTION`	`0.15`	Refuse to start a build below this.
`DEPLOY_BUILD_TIMEOUT_SECONDS`	`1800`
`DEPLOY_PROXY_NETWORK`	`sthora-proxy`	The external network. The installer creates it; Compose never does.
`DEPLOY_HOST_PORT_MIN`	`30000`
`DEPLOY_HOST_PORT_MAX`	`32000`
`DEPLOY_CONTAINER_LOG_MAX_SIZE_MB`	`10`	Written into every rendered compose file.
`DEPLOY_CONTAINER_LOG_MAX_FILES`	`3`
`DEPLOY_BUILD_CONCURRENCY`	`1`	Leave it at 1. Two builds at once on a 4 GB box is an OOM kill.
`DEPLOY_DEPLOY_CONCURRENCY`	`2`
`DEPLOY_LIFECYCLE_CONCURRENCY`	`4`
`DEPLOY_NIXPACKS_ENABLED`	`true`	See build types.
`DEPLOY_NIXPACKS_IMAGE`	`ghcr.io/railwayapp/nixpacks:v1.39.0`	Pinned.
`DEPLOY_BLUE_GREEN_MIN_FREE_MEMORY_MB`	`512`	Free memory a blue/green deployment needs beyond the running version's usage.

Ingress and TLS

Variable	Default
`PROXY_ENABLED`	`false`	Off by default so a developer's laptop does not bind port 80. The installer turns it on.
`PROXY_IMAGE`	`traefik:v3.6`	Pinned — `latest` on a reverse proxy is a change nobody scheduled.
`PROXY_PROJECT_NAME`	`sthora-proxy`
`PROXY_HTTP_PORT`	`80`
`PROXY_HTTPS_PORT`	`443`
`PROXY_ACME_EMAIL`	Unset	Certificates are not issued at all until this is set, and the CA rejects reserved domains such as `example.com`.
`PROXY_ACME_STAGING`	`false`	Staging issues untrusted certificates from a directory with far looser limits.
`PROXY_HTTPS_REDIRECT`	`true`	Only takes effect once ACME is configured.
`PROXY_BASE_DOMAIN`	Unset	Wildcard base domain. See domains and TLS.
`SERVER_PUBLIC_IP`	Detected	Checked against a hostname's DNS before a router is attached. Detection is wrong behind NAT — set it explicitly there.

Git sources

Variable	Default
`GIT_CLONE_TIMEOUT_SECONDS`	`600`
`PUBLIC_BASE_URL`	Unset	Public address of this control plane. Without it the portal shows webhook paths only, and server enrolment refuses rather than generating a command containing `undefined`.

GitHub App

Optional. Deploy keys work against every host with nothing registered anywhere.

Variable	Default
`GITHUB_APP_ID`	Unset
`GITHUB_APP_PRIVATE_KEY_FILE`	`/etc/sthora/github-app.pem`
`GITHUB_APP_WEBHOOK_SECRET`	Unset
`GITHUB_API_BASE_URL`	`https://api.github.com`

Alerts and notifications

Variable	Default
`ALERT_DISK_USED_FRACTION`	`0.85`
`ALERT_MEMORY_USED_FRACTION`	`0.9`
`ALERT_MEMORY_SUSTAINED_MINUTES`	`5`
`ALERT_RESTART_COUNT`	`3`
`ALERT_RESTART_WINDOW_MINUTES`	`5`
`ALERT_CERTIFICATE_EXPIRY_DAYS`	`14`
`NOTIFY_MAX_ATTEMPTS`	`4`
`NOTIFY_BACKOFF_MS`	`10000`
`NOTIFY_CONCURRENCY`	`4`
`NOTIFY_WEBHOOK_TIMEOUT_MS`	`10000`

Outbound email

With no transport configured the platform still runs: sends are skipped and logged, and alerts remain in-app and by webhook.

Variable	Default
`EMAIL_TRANSPORT`	`smtp`
`EMAIL_FROM_ADDRESS`	Unset	Must align with the DKIM signing domain, or DMARC fails even when both records exist.
`EMAIL_FROM_NAME`	`Sthora`
`EMAIL_LIST_ID`	Unset
`EMAIL_SMTP_HOST`	Unset
`EMAIL_SMTP_PORT`	`587`
`EMAIL_SMTP_SECURE`	`false`	`true` for port 465; 587 upgrades with STARTTLS and wants `false`.
`EMAIL_SMTP_USER`, `EMAIL_SMTP_PASSWORD`	Unset	Optional — an unauthenticated relay on a private network is a configured transport.
`EMAIL_SMTP_POOL`	`true`
`EMAIL_SMTP_MAX_CONNECTIONS`	`2`
`EMAIL_BATCH_SIZE`	`25`
`EMAIL_BATCH_DELAY_MS`	`1000`
`EMAIL_MAX_ATTEMPTS`	`3`
`EMAIL_RETRY_BACKOFF_MS`	`5000`

Managed services

Variable	Default
`BACKUP_TIMEOUT_SECONDS`	`3600`	Ceiling on one backup step. Killing a dump halfway produces a file that looks like a backup and is not one.
`SERVICES_CONCURRENCY`	`1`

Agent channel

Variable	Default
`AGENT_CHANNEL_ENABLED`	`true`	Off turns the channel away entirely — correct for an install that manages only its own machine.
`AGENT_CALL_TIMEOUT_SECONDS`	`300`	Ceiling on one agent call. Builds carry `DEPLOY_BUILD_TIMEOUT_SECONDS` instead.
`AGENT_UPLOAD_CHUNK_BYTES`	`262144`	base64 inflates by a third, so the wire cost is this times 1.34.
`AGENT_OFFLINE_AFTER_SECONDS`	`90`	Must comfortably exceed the agent's heartbeat interval.
`AGENT_IMAGE`	`ghcr.io/asynccoders/agent:latest`	What the enrolment command tells an operator to run.

Plans and limits

Variable	Default
`BILLING_ENFORCE_LIMITS`	`false`	Whether limits refuse anything. Usage is metered either way.
`BILLING_DEFAULT_PLAN`	`self-hosted`	Must match a slug in the seeded catalogue.

See plans and limits.

The other apps

The dashboard, the marketing site, and this documentation site each own their own .env.example. Only VITE_-prefixed variables reach a browser bundle, and none of the three holds a secret.

App	Key variables
Dashboard	`PORT`, `VITE_APP_TITLE`, `VITE_API_URL` (empty on a self-hosted install, where the dashboard and API share an origin)
Marketing site	`PORT`, `VITE_SITE_NAME`, `VITE_SITE_URL`, `VITE_PORTAL_URL`, `VITE_API_URL`
Documentation	`PORT`, `VITE_SITE_NAME`, `VITE_SITE_URL`, `VITE_PORTAL_URL`, `VITE_WEBSITE_URL`, `VITE_REPOSITORY_URL`

VITE_-prefixed values are inlined at build time. Supplying one at runtime does nothing — they are build arguments to the image, not runtime environment.

On this page