Configuration
Environment variables that control backd at runtime.
All runtime configuration comes from environment variables. At startup backd-server checks all of them and reports every problem at once, then exits with a non-zero status if any are invalid. The table is backd-server’s; the CLI reads only a few (which binary reads them).
| Variable | Required | Default | Purpose |
|---|---|---|---|
CONFIG_DIR | yes | — | Root of the realm/database/collection tree |
MONGO_URI | yes | — | MongoDB connection string. MongoDB must run as a replica set (a single node is fine; see MongoDB) |
HTTP_ADDR | no | :8080 | Listen address |
PROVISION_MODE | no | apply | apply creates or updates collections, validators and indexes; verify only compares them and refuses to start on differences |
LOG_LEVEL | no | info | debug, info, warn or error (case-insensitive) |
BACKD_MONGO_DEBUG | no | off | 1 or true logs every MongoDB server heartbeat (the address the driver contacts, ok or failed), to see which cluster members it discovers and reaches. Diagnostics only; leave it off otherwise |
MAX_BODY_BYTES | no | 1048576 | Maximum request body size, bytes or a size such as 1MiB; larger bodies get 413 |
BACKD_MAX_UPLOAD_BYTES | no | 104857600 | Largest file a proxy upload may carry (100 MiB), bytes or a size. A field’s own max_size applies as well; the smaller wins |
BACKD_IMAGE_MAX_PIXELS | no | 40000000 | Most pixels (width × height) an image may have to get versions: 40 megapixels. Read from the file’s header, so a larger image is refused without being decoded. A field’s max_pixels may only lower it, and a higher one stops startup |
BACKD_EXPAND_MAX_DEPTH | no | 2 | Levels of references an expand follows: 1 or 2 |
BACKD_EXPAND_MAX_PATHS | no | 5 | Entries of one expand parameter |
BACKD_EXPAND_MAX_ARRAY | no | 100 | Most ids of one many reference that an expansion follows; the rest is returned as truncated. A reference’s max_expand may only lower it, and a higher one stops startup |
BACKD_EXPAND_MAX_DOCS | no | 2000 | Most expanded documents in one response; more is 400 expand_too_large, before any partial data. The four values are logged at startup |
BACKD_ENV | no | none | What this instance is for: production, staging… (1 to 32 characters of a-z, 0-9, -, _). Only imports use it, to warn about a package that doesn’t fit: one that isn’t anonymized into staging, or an anonymized one into production |
BACKD_DEPLOYMENT_ID | no | default | Names this backd deployment (1 to 32 characters of a-z, 0-9, -, _). Only needed when several backd deployments share one MongoDB cluster: it keeps their trigger dispatchers apart |
BACKD_TRIGGER_MAX_CHAIN | no | 16 | How deep a chain of writes caused by trigger runs may go (1 to 64). A realm’s triggers.max_chain may only lower it, and a higher one stops startup |
BACKD_AGGREGATE_TIME | no | 5s | The most time one aggregation may run (100ms to 1m). A collection’s aggregate.limits.time may only lower it, and a higher one stops startup |
BACKD_AGGREGATE_MAX_GROUPS | no | 1000 | The most groups one aggregation may return (1 to 10000). A collection may only lower it |
BACKD_IMAGE_TIMEOUT | no | 30s | How long a worker may take to decode one image and make all its versions; over it, the versions fail with timeout |
BACKD_IMAGE_CONCURRENCY | no | derived | How many images one worker process makes versions of at once. Derived from the container’s limits: half the CPUs, and no more than fit in half the memory at 4 bytes per pixel of the largest allowed image (at least 1); the value in effect is logged at startup. See sizing the worker |
MONGO_OP_TIMEOUT | no | 10s | Deadline for the storage work of each document request; exceeding it returns 503 |
SHUTDOWN_TIMEOUT | no | 15s | How long in-flight requests may take to finish after SIGTERM |
TRUSTED_PROXIES | no | none | Comma-separated IP addresses or CIDR networks of your reverse proxies; only they may set X-Forwarded-For (see client addresses behind a proxy) |
PASSWORD_HASH_CONCURRENCY | no | GOMAXPROCS (which follows a container’s CPU limit), capped by half the memory limit / 64 MiB | Maximum password hashes running at once in one process (see Users and passwords) |
BACKD_URL | when the realms send email or use sign-in providers | none | backd’s public address (https://api.example.com), the base of the links in emails and of the providers’ callback URLs. A realm’s email.public_url replaces it. Startup stops, naming the realm, when it needs one and has neither |
BACKD_EXECUTOR_URL, BACKD_EXECUTOR_TOKEN, BACKD_EGRESS_KEY, BACKD_INTERNAL_ADDR, BACKD_CALLBACK_URL, BACKD_CALLBACK_KEY | with functions | — (:8081 for the address) | The functions executor and the internal listener: see Running the executor |
BACKD_SECRETS_KEY (or BACKD_SECRETS_KEY_FILE) | with functions that declare secrets | — | The master key functions’ secrets are encrypted under |
BACKD_ADMIN_API | no | true | false makes this instance serve no /v1/{realm}/_admin route: they answer 404 like any unknown route. For public instances when an internal instance has the admin API (see Production deployment) |
BACKD_EVENTS | no | true | false stops this instance from reading MongoDB’s change stream for realtime: set it on API replicas when dedicated instances serve subscriptions. Nothing is read until there is something to serve, so true costs an idle instance nothing |
BACKD_TRIGGERS | no | true | false keeps this instance from holding the lease of the trigger dispatcher (triggers); false on instances that only serve requests |
BACKD_REALTIME_MAX_SUBSCRIPTIONS_PER_STREAM | no | 20 | Subscriptions one realtime stream may hold. A realm may lower it |
BACKD_REALTIME_MAX_STREAMS_PER_USER | no | 5 | Open streams per user or API key (anonymous callers: per address). A realm may lower it |
BACKD_REALTIME_MAX_STREAMS | no | 10000 | Open realtime streams on this instance |
BACKD_REALTIME_BUFFER | no | 262144 | Bytes a stream may have waiting to be sent (and at most 1,000 events) before it is reset with slow_consumer |
BACKD_REALTIME_MEMORY | no | 268435456 | Bytes (or a size such as 256MiB) all streams’ buffers may hold on this instance; over it, the largest buffers are reset |
BACKD_REALTIME_HEARTBEAT | no | 25s | How often an idle stream sends a comment so proxies keep it open (at least 1s) |
BACKD_ADMIN_UI | no | false | true serves the admin web interface at /_ui/ when the binary was built with it (release images are); it needs the admin API on the same instance, or startup fails |
BACKD_ADMIN_UI_IDLE | no | 30m | how long the admin interface may sit untouched before it signs out and revokes its session |
BACKD_DEV | no | false | true reloads the config and rebuilds function sources automatically as the files change (see Dev mode); serve refuses to start unless HTTP_ADDR is bound to localhost. Local development only |
BACKD_DEV_LINKS | no | none | Extra links on the dev-mode landing page (only while BACKD_DEV=true), as Label=URL pairs separated by ;, for the tools next to the API, for example MinIO console=http://127.0.0.1:9001 |
BACKD_DEV_ANY_ADDR | no | false | true lets BACKD_DEV=true run on an address that isn’t localhost, for a container whose ports are published on the host’s localhost only (the local development stack). Never set it where anything else can reach backd |
WORKER_CONCURRENCY | no | 10 | Async jobs one worker process runs at once, on backd-server worker or backd-server serve --with-worker |
METRICS_ADDR, METRICS_TOKEN | no | — | Where this process serves /metrics, and the bearer token it may require (see Metrics) |
backd-server functions build also reads DENO, the Deno binary to bundle with (default: deno on the PATH); BACKD_DEV reads the same variable. backd-server executor and backd-server egress have their own variables (see Running the executor and Egress); backd-server worker reuses BACKD_EXECUTOR_URL/BACKD_EXECUTOR_TOKEN/BACKD_CALLBACK_URL/BACKD_CALLBACK_KEY (see Running the worker).
Which binary reads them
Everything in the table is read by backd-server, the binary that runs the server roles. The backd CLI reads only:
| Variable | What for |
|---|---|
CONFIG_DIR | The project tools (template, config check, rules test, types, openapi, databases, functions types) |
BACKD_URL, BACKD_API_KEY, BACKD_CA_CERT | The server its admin commands talk to, an admin API key instead of a stored session, and extra CAs to trust (Logging in) |
BACKD_CREDENTIALS, XDG_CONFIG_HOME, HOME (USERPROFILE on Windows) | Where the stored sessions are kept: BACKD_CREDENTIALS, else $XDG_CONFIG_HOME/backd/credentials, else .config/backd/credentials in the home directory |
BACKD_IMAGE_MAX_PIXELS, BACKD_EXPAND_MAX_DEPTH, _PATHS, _ARRAY, _DOCS, BACKD_AGGREGATE_TIME, BACKD_AGGREGATE_MAX_GROUPS, BACKD_TRIGGER_MAX_CHAIN | backd config check applies the same instance limits startup does, so set them as the server has them |
DENO is backd-server’s (functions build, the executor and dev mode).
The pages of this section show YAML in pieces: a snippet of collection.yaml assumes the schema fields, roles and secrets it names exist in the rest of the configuration. backd config check is the judge of a whole tree. The complete, tested trees are under examples/config.
Durations use Go syntax, for example 500ms, 10s or 1m30s.
Sizes and units
Every limit measured in bytes is written as a number and a unit, with no space between them: 512KiB, 10MiB, 1.5GB. The units come in two families that differ by about 7% at TB/TiB:
| Family | Units | Each step is |
|---|---|---|
| Decimal | B, KB, MB, GB, TB | 1,000 times the one before: a KB is 1,000 bytes |
| Binary | B, KiB, MiB, GiB, TiB | 1,024 times the one before: a KiB is 1,024 bytes |
- Both families are accepted unless a field says otherwise.
memoryof a function takes binary units only, because the runtime counts in MiB. - Units are case-sensitive and follow the number directly:
1mb,1 MiBand1Mibare refused. - Decimals are fine (
1.5MiBis 1,572,864 bytes) as long as the result is a whole number of bytes:0.1KiBis refused. - Environment variables that end in
_BYTESor_MEMORYalso take a bare number of bytes:1048576and1MiBare the same value. - A size is never negative and has no sign, exponent or thousands separator. Each setting says its smallest value.
Example:
CONFIG_DIR=./config MONGO_URI='mongodb://localhost:27017/?replicaSet=rs0' backd-server serve
Data model (CONFIG_DIR)
Declare realms, databases and collections with schema.json and indexes.json.
App configurationFeature flags, maintenance switches and limits for your apps: declared with JSON Schema, changed by admins and functions, read with caching.
Realm settings (realm.yaml)Configure authentication, sign-up, sessions, passwords, CORS and roles for a realm.
Custom idsLet clients choose the id of the documents they create: when to, how to keep it safe, and what it means for probing, personal data and change.
Field keys and encrypted fieldsEncrypt fields before they reach MongoDB, with a key you hold a copy of: creating and saving the key, marking fields, rotating the key instantly, and what encrypted fields can’t do.
Schema validationHow schemas are enforced by the API and mirrored in MongoDB.