Environment variables

boatramp reads its configuration from three places, in precedence order: command-line flag > environment variable > config file. Every variable below overrides the corresponding config field and is itself overridden by an explicit flag. Secrets (tokens, signing keys) belong in the environment rather than in a config file on disk.

Client commands

Read by sync, build, bundle, and the other project commands. See project.cfg.

Server (serve)

Read by boatramp serve. Each maps to a serve.* field in boatramp.cfg; the flag of the same name wins over both.

Upload limits

Authentication & tokens

See Bootstrap authentication and Authentication & authorization.

An external signer (KMS/HSM/Vault) replaces BOATRAMP_AUTH_ROOT_PRIVATE_KEY with its own credentials — see Hold the signing key in a KMS/HSM/Vault.

OIDC federation

For exchanging an identity-provider JWT for a boatramp token. See Federate CI auth with OIDC.

Cluster & shared-store frontends

Compute backend

Map to the [compute] section in boatramp.cfg. Set any of these and the section is enabled even without a config file (a set variable wins over its file value; an unset one defers to the file/default). See Run compute workloads.

Security-critical: BOATRAMP_COMPUTE_KERNEL_SIGNING_PUBKEYS and BOATRAMP_COMPUTE_KERNEL_ALLOWED_HASHES are the kernel trust anchors for the posture-scaled kernel bar — a value here decides which kernels a multi-tenant node will boot. In a 12-factor deployment the environment is the operator’s trusted config source (a fly.toml [env] is committed the same as a file), so they are settable here; but the environment is more visible than a file (it leaks through /proc/<pid>/environ and is inherited by subprocesses), so prefer a config file for them when one is available.

Security posture

Map to the [security] section in boatramp.cfg. Setting any of these materialises the posture even without a config file: an unset section resolves to the strict multi-tenant default and each variable layers over it exactly as a file overrides block would (a set variable wins over the file). See boatramp.cfg and boatramp security explain. Byte caps take 0 = unlimited; booleans accept true/false, 1/0, yes/no, on/off.

The four tenancy/capability variables above set the fleet posture; a per-project override of the same knobs is config-file only (see security.projects). Guest-admin surface knobs (allow_guest_admin_*) and allow_guest_email are file-only — not env-settable.

Handler backends

The [handlers.bindings.sql] knobs (the single managed-SQL backend) map to these; set any and the section is created even without a config file (env wins over the file value; secrets stay indirected via the *_TOKEN_ENV names, never the token itself). See Handler bindings.

External SQL databases ([handlers.bindings.sql.databases])

The bring-your-own / managed-compute database map is env-settable too, so a managed co-located Postgres needs no config file. Each database <NAME> is declared by setting one or more BOATRAMP_HANDLERS_SQL_DB_<NAME>_<FIELD> variables; the member names are discovered from the environment (there is no file to enumerate them). An env-declared database is merged over — per field, by key — whatever the file declared under that name.

The default database (the empty-string map key, opened as sql.open("")) is addressed by the reserved name token DEFAULT: BOATRAMP_HANDLERS_SQL_DB_DEFAULT_KIND populates the "" key.

<FIELD> is one of KIND, URL_ENV, READ_URL_ENV, COMPUTE, DATABASE, USER, PASSWORD_ENV, POOL_MAX, READ_ONLY, ALLOW_PREVIEW, CONNECT_TIMEOUT_SECS, IMAGE, VOLUME_SIZE_MIB, STARTUP_GRACE_SECS (each mirrors a field of the RON databases entry; secrets stay indirected via the *_ENV names). STARTUP_GRACE_SECS sets how long a freshly launched managed-DB replica may take to become healthy before the reconcile treats it as a broken launch; omit it for the per-engine default (Postgres 60 s, MySQL 120 s). See Startup grace. Example — a managed Postgres as the default database, with boatramp managing the credential (no PASSWORD_ENV):

BOATRAMP_HANDLERS_SQL_DB_DEFAULT_KIND=postgres
BOATRAMP_HANDLERS_SQL_DB_DEFAULT_COMPUTE=pg
BOATRAMP_HANDLERS_SQL_DB_DEFAULT_DATABASE=appdb
BOATRAMP_HANDLERS_SQL_DB_DEFAULT_USER=app

For a managed co-located database (COMPUTE set, no PASSWORD_ENV), boatramp auto-registers the backing compute workload — so the four lines above are enough to boot a Postgres; no separate compute set / apply step. IMAGE overrides the stock image (default pgvector/pgvector:pg16 for postgres, mysql:8.0 for mysql) and VOLUME_SIZE_MIB the persistent data-volume size (default 10240 = 10 GiB). An operator-declared workload of the same name always wins over the auto-registered one.

Handler secrets are injected by reference: the site config names a host env-var, and the server resolves it at instantiation so the literal never lands in a manifest. See Handler host bindings.

Secrets envelope

Map to the [secrets] section in boatramp.cfg — envelope encryption for private keys at rest. Set any and the section is created even without a config file. kek_file holds a path (never key material); the Vault token stays indirected via token_env (a variable name, not the token).

Cluster section ([cluster])

Map to the [cluster] section in boatramp.cfg — the self-hosted cluster mode’s own config, distinct from the founding/joining action flags in the Cluster & shared-store frontends table above (BOATRAMP_CLUSTER_INIT / BOATRAMP_CLUSTER_JOIN / BOATRAMP_CLUSTER_ADVERTISE_ADDR). A BOATRAMP_CLUSTER_LISTEN materialises an absent section (a node must know where to bind its mesh); the other fields then layer on. List-valued vars are comma-separated.

TLS / ACME (incl. wildcard DNS-01)

The listener’s TLS mode and the ACME issuance parameters — previously serve flags only — are env-settable too, so wildcard DNS-01 can be configured with no config file (e.g. a fly [env]). The DNS provider credentials are already env-only (below).

An exact host (an apex/www/console site or cert) always wins over a wildcard, in both host→site routing and SNI cert selection — so *.example.com never shadows a declared exact host.

DNS provider credentials

Auto-DNS and --tls acme-dns read provider credentials (CLOUDFLARE_API_TOKEN, AWS_KEY, HETZNER_DNS_TOKEN, …) from the environment. Each provider’s exact variables are listed in DNS providers & credentials.

Test-only variables

Variables prefixed BOATRAMP_TEST_ gate #[ignore] live integration tests (cloud KMS, SoftHSM, libsql, Docker, S3). They have no effect on a running server and are not part of the operational surface.