backd

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

Core concepts:

realm realm.yaml settings; shared user pool with single sign-on
 └─ database one application's data → MongoDB database <realm>__<database>
 └─ collection documents validated by schema.json → one MongoDB collection
 └─ document JSON object with server-owned id and _meta

Quick start with docker compose

The repository includes a docker-compose.yml that runs backd and MongoDB with the sample config in examples/config, together with this documentation site and the JavaScript client’s example apps. nginx serves all of them over HTTPS on one origin, https://localhost:8443. Plain http://localhost:8080 redirects there. It also runs the functions executor, egress and (folded into backd) a worker: the blog realm’s sample stats function calls the executor for real (curl https://localhost:8443/v1/blog/main/_func/stats).

1. An empty shelf

Mon, 01 Jan 0001 00:00:00 +0000

A collection, a schema, and a page that lists documents. No users yet: anyone on localhost can read and write, which is exactly what you want while the shape of the data settles.

Warning

auth: disabled means anyone who can reach backd can read and modify its data. Keep this stack on localhost — chapter 2 turns authentication on and the checklist is what you run before anything faces the internet.

The realm

A realm is one application’s world: its users, roles and settings. A database inside it groups collections (main here), and a collection holds documents — the vocabulary the URLs use: /v1/{realm}/{database}/{collection}. They are directories under config/. Create config/shelf/realm.yaml:

Data model (CONFIG_DIR)

Mon, 01 Jan 0001 00:00:00 +0000

The data model is a directory tree under CONFIG_DIR, loaded once at startup. Directories define realms and databases, and a schema.json defines a collection.

$CONFIG_DIR/<realm>/
 realm.yaml # required — realm settings
 email/<kind>/ # optional — email templates (see Functions → Email)
 <database>/<collection>/
 schema.json # required — JSON Schema draft 2020-12
 indexes.json # optional — index declarations
 collection.yaml # optional — access rules, file fields, soft delete, erase policy
 rules.test.yaml # optional — tests of the rules (`backd rules test`)
 <database>/_functions/ # optional — server-side functions

Each directory under CONFIG_DIR is a realm. It must contain a realm.yaml.
Each directory inside a realm is a database, stored in the MongoDB database <realm>__<database>.
Each directory inside a database is a collection, stored in a MongoDB collection of the same name. It must contain a schema.json.
A realm’s email folder holds its email templates, and pages is reserved for the pages backd will serve; neither is a database, so they are never read as one and can’t be database names.
A database’s _functions directory holds its functions, not a collection.
Other plain files at the realm and database levels are ignored, as are hidden entries (names starting with .).
Changing the config requires a restart. There is no hot-reload.

Starting from a template

backd template writes commented starter files, so you don’t have to start from an empty directory. It only needs CONFIG_DIR.

Realm settings (realm.yaml)

Mon, 01 Jan 0001 00:00:00 +0000

Every realm directory must contain a realm.yaml. It holds the settings that apply to the whole realm: its users, how they sign in, and which browser origins may call it.

$CONFIG_DIR/<realm>/realm.yaml

If a realm has no realm.yaml, backd refuses to start and names the realm. Create a commented starter file with:

CONFIG_DIR=./config backd template realm --realm <realm>

Example

auth: enabled
signup: invite
sessions:
 idle_timeout: 14d
 max_lifetime: 60d
password:
 min_length: 14
cors:
 origins:
 - https://app.example.com
 - http://localhost:5173
roles:
 admin:
 description: Manages users and invitations
 admin: true
 users:
 - ops@example.com
 - email: lead@example.com
 editor:
 description: Can publish articles

An empty file, or one with only comments, is valid: every key has a default.

2. Members

Mon, 01 Jan 0001 00:00:00 +0000

Chapter 1’s realm was open to anyone on localhost. Now members sign up and sign in — and the app learns who you are: your gallery, your assets, your account page.

The realm grows

Replace config/shelf/realm.yaml:

auth: enabled
signup: open

roles:
 admin:
 description: "Operators: users, invitations and API keys"
 admin: true
 users:
 - operator@shelf.example
 curator:
 description: Publishes assets and manages share links (chapter 5)
 users:
 - curator@shelf.example

auth: enabled — users, sessions and roles exist; anonymous callers get 401.
signup: open — anyone may create an account (alternatives: invite, closed). It is open only for this chapter and the next: chapter 4 closes it, and from then on every new member needs an invitation — which only an existing administrator can create.
roles: — admin is the operator role (admin: true grants the admin API); curator matters from chapter 5. The users: lists are seed assignments: when someone signs up with a listed address, the role attaches. A shortcut for local stacks — never keep seeded users in a real realm.

Apply, and create the three accounts

docker compose restart backd

Open http://localhost:8080 and sign up (any password of 12 or more characters; the demo stack sends no email yet and account.require_verified_email is off, so nothing needs verifying — the verify-email and welcome messages only appear once chapter 10 wires email) as each of:

Schema validation

Mon, 01 Jan 0001 00:00:00 +0000

Every collection’s schema.json is enforced at two levels.

API level (authoritative). Every write is validated against the full JSON Schema draft 2020-12 before it reaches the database. Failures return 400 with one entry per failing field.
Database level (safety net). The same schema is translated into a MongoDB $jsonSchema collection validator. This protects the data from writes that bypass the API. MongoDB’s dialect is older and smaller, so the translation covers a subset of the schema.

Translation to MongoDB

JSON Schema	MongoDB `$jsonSchema`
`type: string` / `boolean` / `object` / `array` / `null`	`bsonType: string` / `bool` / `object` / `array` / `null`
`type: integer`	`bsonType: [int, long, double]` plus `multipleOf: 1`, unless the schema sets its own `multipleOf`
`type: number`	`bsonType: [int, long, double, decimal]`
`const: v`	`enum: [v]`
`exclusiveMinimum: n` / `exclusiveMaximum: n`	`minimum` / `maximum: n` plus `exclusiveMinimum` / `exclusiveMaximum: true`
`properties`, `required`, `enum`, `minimum`, `maximum`, `multipleOf`, `minLength`, `maxLength`, `pattern`, `items`, `minItems`, `maxItems`, `uniqueItems`, `additionalProperties`, `minProperties`, `maxProperties`, `allOf`, `anyOf`, `oneOf`, `not`	copied as-is (subschemas translated recursively)

Annotations (title, description, default, examples, $comment, …) are dropped silently.
Any other keyword (for example format, $ref/$defs, prefixItems, unevaluatedProperties or if/then/else) is left out of the database validator and logged at info level with its location. The API level still enforces it.

Finding documents that no longer match

A schema is enforced when a document is written. Documents stored before you changed the schema are not touched, and MongoDB is set to leave them alone (validationLevel: moderate): a collection can hold documents that would be refused today. A schema check lists them. It reads every stored document, validates it with the same full validator the API uses on a write (so it also sees the keywords MongoDB’s translation leaves out, such as format), and reports the ones that fail. It never writes anything.

3. Who may touch what

Mon, 01 Jan 0001 00:00:00 +0000

Until now every signed-in member could do anything to anything. The rules: section of a collection’s collection.yaml gives it four expressions — read, create, update, delete — evaluated per call. Operations without a rule are denied.

The assets rules

Replace config/shelf/main/assets/collection.yaml (chapter 2’s policy stays; the rules go above it):

rules:
 # Everyone in the workspace reads published assets; a member also reads
 # their own drafts.
 read: >
 user != nil
 && (document.published_at != nil || document._meta.owner == user.id)

 # Members write their own assets. HOLE: published_at is the client's word —
 # any member can publish, and pick the date.
 create: user != nil
 update: user != nil && document._meta.owner == user.id
 delete: user != nil && document._meta.owner == user.id

on_owner_delete:
 action: delete

Three names carry the context: user (the caller, or nil when anonymous — always check user != nil first), document (the stored asset), data (the asset being written). changed() lists the fields a write touches, and hasRole(user, 'curator') checks a realm.yaml role. The full language is in Access rules.

4. Invitations

Mon, 01 Jan 0001 00:00:00 +0000

A team’s library shouldn’t be open to whoever finds it. One word in realm.yaml closes the door; invitations are how people get in anyway.

Close the door

Before you change anything, check the three accounts of chapter 2 exist: operator, curator and your member. Then, in config/shelf/realm.yaml, change one line:

signup: invite # was: open

and docker compose restart backd. Existing accounts keep working — this only governs new sign-ups. From now on POST /_auth/signup without a valid invitation token answers 403:

5. The first function

Mon, 01 Jan 0001 00:00:00 +0000

Chapter 3 left two HOLE comments: members could write published_at themselves, and share links trusted the client’s asset_id and token. Rules can’t fix either — “a curator, at the server’s now” and “a token nobody chose” need code. This chapter writes it.

A function is three files

Create config/shelf/main/_functions/publish/ with three files:

function.yaml — the contract: who may call it (invoke), what it may do (admin, calls, network, secrets), how it runs.

examples/config/shelf/main/_functions/publish/function.yaml

6. Reaching the outside

Mon, 01 Jan 0001 00:00:00 +0000

Functions run in a sandbox with no network by default — fetch to anywhere is refused before a packet leaves. A function that needs the outside declares its hosts in function.yaml, and every request exits through the egress proxy that enforces the list.

preview

Pasting a link into the new-asset form is a chore; preview fetches the page’s title and description so the form can prefill itself:

examples/config/shelf/main/_functions/preview/function.yaml

# Fetches a link's title and description for the new-asset form. This is the
# first function that reaches outside: `network` is the whole allowlist —
# api.microlink.io answers, every other host is refused at the egress. It
# touches no collection, so no `admin:` either.
invoke: "user != nil"
network: [api.microlink.io]

Two things to notice:

7. Functions calling functions

Mon, 01 Jan 0001 00:00:00 +0000

publish works. Now the owner should hear about it — and the same “write a notification” will soon be wanted by the digest, the cleanup, the importer. That’s a building block, not an endpoint. internal: true makes it one.

The notifications collection

A member reads their own notifications and can flip exactly one field:

examples/config/shelf/main/notifications/collection.yaml

rules:
 # Notifications are written by functions only — there is no create rule.
 # A member reads their own and may set exactly one field, read_at.
 read: user != nil && document.to_user == user.id
 update: >
 user != nil && document.to_user == user.id
 && all(changed(), # in ['read_at'])

There is deliberately no create rule — nobody may write a notification directly. The only writer is a function.

8. Work that takes time

Mon, 01 Jan 0001 00:00:00 +0000

Fanning a notification out to every member doesn’t belong inside an HTTP request. mode: async moves it to a job: the call returns 202 with a job id immediately, the work runs on the executor, and the caller watches it finish.

The function

Create config/shelf/main/_functions/digest/. This chapter’s function.yaml:

mode: async
admin: true
invoke: "user != nil && hasRole(user, 'admin')"
calls: [notify]
retry:
 attempts: 3
 backoff: 5s
 max_backoff: 1m

(The repository’s file also has schedule: and email: true — chapters 9 and 10 add them.)

9. On a schedule

Mon, 01 Jan 0001 00:00:00 +0000

Some work shouldn’t wait for a person: the morning digest, the nightly sweep. One line in function.yaml and the function runs itself.

schedule

# digest/function.yaml — the same function as chapter 8, plus:
schedule: "@daily"

Cron expressions work too ("0 7 * * *", UTC unless you add a timezone). A scheduled run has no caller: ctx.user is null, ctx.input is null, ctx.db acts as an anonymous caller — and ctx.admin.db is always available, recorded as func:shelf/main/digest. Review a scheduled function as if it declared admin: true (Cron).

10. Email for real

Mon, 01 Jan 0001 00:00:00 +0000

Invitations emailed themselves? Not yet — chapter 4 handed you a token to pass along. This chapter gives the realm an email pipeline: a delivery function, templates for every flow backd sends, hosted pages the links open, and one custom kind of your own.

The realm side

Add to config/shelf/realm.yaml (keeping auth, signup and roles as they are):

email:
 function: mail/email-capture
 from: "Shelf <no-reply@shelf.example>"
 allowed_redirects: [http://localhost:8080]
 redirects:
 verify_email: http://localhost:8080/
 reset_password: http://localhost:8080/
 change_email: http://localhost:8080/
 invitation: http://localhost:8080/

account:
 allow_email_change: true

function: — one function (in the new mail database) delivers every email backd renders. email-capture stores them in the mail/outbox collection instead of sending — dev_only: true, it only runs under BACKD_DEV, which the tutorial’s compose.yaml sets (a real deployment doesn’t, and backd then refuses to start with it configured) (Email).
Templates — email/<kind>/<locale>.{subject.txt,txt,html}, one folder per kind backd sends (verify-email, reset-password, invitation, welcome, account-exists, change-email, email-changed, password-changed) plus custom kinds like shelf-digest. Every locale you list needs every kind — startup fails naming what’s missing.
Pages — pages/<kind>/<locale>.html: the hosted pages the email links open. GET shows a form, POST consumes the token — mail scanners can never spend your links.
allowed_redirects / redirects — after a flow’s page, the reader lands back at the app, and only at origins you list.

On a checkout, backd template realm --realm shelf writes all of email/ and pages/ for you, and backd template email-capture --realm shelf --database mail the delivery function and outbox; the tutorial’s config/ is mounted read-only into the container, so fetch the finished files instead:

11. Being called by the internet

Mon, 01 Jan 0001 00:00:00 +0000

So far everything called your functions for you — a page, a schedule, another function. A webhook reverses it: a partner feed pushes assets into the shelf, signed in to nobody. The function is the whole trust boundary.

The function

examples/config/shelf/main/_functions/import/function.yaml

# A webhook: a partner feed pushes assets into the shelf. The sender has no
# session, so invoke allows anonymous calls and the function itself is the
# only check — it verifies the signature before anything else.
#
# `admin: true` because creating assets is a member's right, not a stranger's.
# The signing secret is set with
# backd secret set --realm shelf --database main --name IMPORT_WEBHOOK_SECRET
mode: webhook
invoke: "true"
admin: true
secrets: [IMPORT_WEBHOOK_SECRET]

mode: webhook — ctx.input is gone; ctx.request holds the raw { body, headers }, and the function returns { status, body } itself.
invoke: "true" — anonymous calls must reach it; the sender has no session and never will.
secrets: — IMPORT_WEBHOOK_SECRET is shared with the sender out of band, stored per-database, never in git.

examples/config/shelf/main/_functions/import/index.ts

Documents

Mon, 01 Jan 0001 00:00:00 +0000

Every configured collection gets the same set of endpoints:

Method	Path	Behavior	Success
`POST`	`/v1/{realm}/{database}/{collection}`	Create a document	`201` + `Location` + `ETag`
`GET`	`/v1/{realm}/{database}/{collection}`	List documents	`200`
`GET`	`/v1/{realm}/{database}/{collection}/{id}`	Fetch one document	`200` + `ETag`
`PUT`	`/v1/{realm}/{database}/{collection}/{id}`	Replace the whole document	`200` + `ETag`
`PATCH`	`/v1/{realm}/{database}/{collection}/{id}`	Partial update (JSON Merge Patch)	`200` + `ETag`
`DELETE`	`/v1/{realm}/{database}/{collection}/{id}`	Delete the document	`204`
`POST`	`/v1/{realm}/{database}/_batch`	Create, replace, patch and delete atomically	`200`

An unknown realm, database, collection or id returns 404 not_found. PUT and PATCH never create documents: there are no upserts, so create with POST and let the server choose the id.
In a realm with auth: enabled, requests are decided by the collection’s access rules, or allowed outright with an API key in Authorization: Bearer ….
Request bodies must be a single JSON object. Anything else returns 400 invalid_json.

Document shape

Documents are returned as bare JSON objects:

12. Running it

Mon, 01 Jan 0001 00:00:00 +0000

The shelf works. The last chapter is about operating it: who acts without a session, who did what, and what to review before a real deployment.

API keys

(This chapter needs the Admin view, so sign in as operator@shelf.example.)

Sessions are for people; API keys are for machines — a CI job that reads the gallery, a monitor that calls a function. In the Admin view, type a name (say ci-reader) and press Create read:main key: it makes one scoped to read-only on main, expiring in 90 days:

Querying

Mon, 01 Jan 0001 00:00:00 +0000

The list endpoint, GET /v1/{realm}/{database}/{collection}, accepts these query parameters:

Parameter	Default	Meaning
`where`	—	JSON object with filter conditions
`order_by`	`id`	Comma-separated fields; prefix a field with `-` for descending
`limit`	`20`	Page size, `1`–`100`
`skip`	`0`	Number of documents to skip
`after`	none	The `next_cursor` of the previous page: continues the list after it (see Paging with a cursor). Can’t be combined with `skip`
`count`	`false`	`true` adds `total`, the number of documents matching `where`
`deleted`	none	In a collection with soft delete: `only` lists the deleted documents (the trash), `include` both. Needs the `restore` rule besides `read`

Each parameter may appear at most once. Any other parameter returns 400 invalid_query.

13. Files on assets

Mon, 01 Jan 0001 00:00:00 +0000

Until now an asset was a link or a note. Real shelves hold files: a PDF handbook, a picture of the office. backd keeps no files itself: a realm brings its own S3-compatible storage, and the tutorial’s stack gains a MinIO to be it. Every file belongs to a field of a document and is as private as that document: reading a file is reading the asset, and every upload or removal is an update checked before any byte is stored.

14. Big files and thumbnails

Mon, 01 Jan 0001 00:00:00 +0000

A 25 MiB limit and a trip through backd suit a handbook, not a conference recording. This chapter adds attachments: several files, up to a gigabyte each, that the browser sends straight to the bucket. Then a worker makes a small picture of each image, declared in one line.

Attachments, straight to the storage

attachments was declared with files: in the last chapter. What makes it different is one line, upload: direct:

15. Sharing and counting downloads

Mon, 01 Jan 0001 00:00:00 +0000

Shelf can hold files; this chapter makes them travel. Members will see how often an asset’s files were downloaded, a stranger holding a share link can download without an account, and the operator can see what it all costs.

Counting downloads

A plain download link tells backd nothing: the browser fetches the file from the storage. To count, the app asks a function for the link, and the function counts. That is the whole trick: a function is called with POST and answers JSON, so it can’t stream a file itself. It returns the link, and the app opens it.

Deploying config

Mon, 01 Jan 0001 00:00:00 +0000

Everything backd serves comes from CONFIG_DIR: realms, schemas, indexes, access rules and function code. Every instance of a deployment must run exactly the same config. If two instances ran different rules or different function code, the same request could be allowed on one and refused on the other.

So the config is treated like code:

it lives in one config repository per deployment;
CI builds it at one pinned tag into an immutable artifact: an image with backd and the config inside;
staging and production run that same artifact;
backd checks it (see what backd enforces).

The config repository

backd template project --dir <directory> --realm <realm> scaffolds this layout in one step — a sample database and function with tests, both Dockerfiles, compose.yaml and the CI workflow below — so you don’t have to assemble it by hand; see Starting from a template.

Production deployment

Mon, 01 Jan 0001 00:00:00 +0000

backd deliberately leaves some protections to the infrastructure around it: TLS, request rate limits and sign-up spam, body size limits at the edge, and database security. The repository ships a reference deployment that puts all of these in place. It lives in deploy/production/, and CI tests it end to end on every change.

It uses Docker Compose, but each part maps directly onto other platforms: a Kubernetes ingress, a cloud load balancer, a managed MongoDB.

Metrics

Mon, 01 Jan 0001 00:00:00 +0000

Every backd process can tell Prometheus how it is doing: requests, errors, database latency and, as the next steps land, functions, jobs and email. It is off by default.

Turning it on

Variable	Default	Meaning
`METRICS_ADDR`	empty (off)	Where this process serves `/metrics`, for example `:9090`. A listener of its own: it can’t be `HTTP_ADDR` or `BACKD_INTERNAL_ADDR`.
`METRICS_TOKEN`	empty	At least 32 characters. When set, every request needs `Authorization: Bearer <token>`. Needs `METRICS_ADDR`.

backd serve, backd worker, backd executor and backd egress each serve their own /metrics (the executor and egress read the same two variables); a process that runs both (serve --with-worker) serves one. The listener answers GET /metrics and nothing else (a request without the token gets 401 whatever the path), serves at most four scrapes at once, and is a separate server: a slow or flooding scraper never slows the API. If the port can’t be bound, the process refuses to start, so a mistake shows at once.

Backup and restore

Mon, 01 Jan 0001 00:00:00 +0000

backd keeps all state in MongoDB. The config directory describes the structure (collections, validators, indexes, rules), and provisioning can rebuild it at any time, but not the data. Back up MongoDB, and keep the config directory in version control.

What a backup must include

Database	Holds	Rebuilt from config?
`<realm>__<database>`	your documents	no
`<realm>___system`	the realm’s users (emails, roles, disabled flag), password hashes, sessions, API keys, invitations, failed-login counters, the audit trail, encrypted function secrets, invocation history, async jobs (queued, running or recently done) and idempotency claims (see system databases)	no, except role seeds

What the configuration can and can’t rebuild:

Hardening checklist

Mon, 01 Jan 0001 00:00:00 +0000

Go through this page before any realm faces the internet, and again after changing the configuration or the deployment. The production reference deployment implements the deployment items, and its test checks many of them.

Realms

No realm has auth: disabled. Such a realm is open to anyone who can reach backd. backd logs a WARN line for each one at startup.
The sample realms aren’t deployed as they are. blog, shop and expenses in examples/config, and the realms backd template realm --sample creates, are examples: shop has auth: disabled, blog and expenses let anyone sign up, and expenses has known holes. Start from them, then review every setting.
Each realm’s signup mode is the intended one. open lets anyone create an account (and needs the sign-up rate limit below), invite needs an invitation, closed leaves it to operators.
Every collection that users or anonymous callers need has a reviewed rules.yaml, with a rules.test.yaml that backd rules test --strict runs in CI: see Testing rules. A missing rule denies; a too-broad one (read: "true") publishes a collection. See access rules.
cors.origins lists exactly your web apps’ origins, and no * for realms with users. Browser apps can keep sessions in an HttpOnly cookie (sessions.cookie), which needs this list.
Someone can administer each realm: an admin role (admin: true) held by the right people, the first created with backd bootstrap. Startup warns when nobody holds an admin role.
Administrators hold only what they use: besides one or two people with admin: true, roles for the rest list their areas (admin: [users, invitations], admin: [audit]), so the person who invites teammates doesn’t hold the secrets and the API keys.
If you run functions: the executor and backd’s internal listener (BACKD_INTERNAL_ADDR) are reachable only from each other, never published; BACKD_EXECUTOR_TOKEN, BACKD_CALLBACK_KEY, BACKD_EGRESS_KEY and, if any function declares secrets, BACKD_SECRETS_KEY are random, 32+ characters, kept as secrets (never in CONFIG_DIR) — the production reference’s setup.sh generates all four; admin: true functions and network lists are reviewed.
The executor can reach only backd egress and backd’s internal listener — nothing else, including MongoDB, is on its network. This is layer 3 of the egress design: without it, a function can reach anything its container’s network reaches over raw TCP, bypassing both the per-function allowlist and the egress proxy. The production reference wires this up (its own test proves it from a real function call); if you assemble your own deployment instead, docker/egress-test/ in the repository proves the isolation and is the reference to reproduce.
Every function callable anonymously has a rate_limit. Startup warns, once, for any that don’t — a public function with no per-caller limit can be abused as a relay (e.g. one that sends email).
Every webhook function verifies its sender’s signature itself, before trusting the body. backd only enforces that its invoke rule allows anonymous callers (it has to — a webhook sender has no session or key); it can’t tell a genuine request from a forged one.
BACKD_SECRETS_KEY (the master key) is backed up separately from database backups, never alongside them: losing it loses every stored function secret, and storing it with a backup defeats that backup’s own encryption. See Backup and restore.
functions.log_retention and functions.job_retention (function logs, async jobs) match your privacy policy: both keep a function’s own console output, and a job additionally keeps its input and output, in the realm’s system database until they expire.
Someone reviews the audit trail (backd audit --realm <realm> --since 7d, or the "msg":"audit" log lines in your log pipeline), and audit.retention matches your privacy policy.
Operators’ machines protect the CLI’s sessions (~/.config/backd/credentials): log out with backd logout on shared machines, and prefer short session lifetimes for realms with administrators.

Credentials

Every API key has an expiry (backd apikey create … --expires 90d), is used by one service, lives in a secret store, and is rotated before it expires. See the expiry and rotation policy. Startup warns about keys without an expiry.
API keys never reach browsers or mobile apps.
Internet-facing instances serve no admin API when an internal instance does: BACKD_ADMIN_API=false on the public ones (the production reference runs the split), and the CLI’s BACKD_URL points at the internal instance.
The admin UI, if used, is served only by the internal instance (BACKD_ADMIN_UI=true there, nothing on the public one), on its own origin, over TLS, with the proxy passing its Content-Security-Policy and other headers through unchanged. BACKD_ADMIN_UI_IDLE is short and the realm’s sessions.admin_idle_timeout and admin_max_lifetime are shorter still: the page’s timer is a convenience, the server’s is the limit. See its security review.
Developers who only look hold admin: read, not admin: true, and admin.read_access.users / .data stay false unless they need personal data. See The read-only level.
Admin sessions are short: sessions.admin_idle_timeout and sessions.admin_max_lifetime in each realm’s realm.yaml (for example 1h and 12h), so a stolen administrator’s session is worth little. See Sessions.
Keys are scoped to what their service does (--scopes read:main/posts,call:main/contact): a leaked key then exposes that and nothing more. See Scopes.
Services use data keys; admin keys (--role admin) exist only for management tooling.
Secrets (MongoDB passwords, TLS keys, the CA key, .env) are outside version control and readable only by the services that need them.

The edge

TLS everywhere: the edge terminates TLS with a trusted certificate that renews automatically, and plain HTTP only redirects. MongoDB connections use TLS too (below).
Rate limits: sign-up, login and the account flows (emailed links, password and address changes) have a strict per-address limit, and the rest of /v1/ a general one. Requests over a limit get 429.
Body size: the edge caps request bodies at MAX_BODY_BYTES.
Client addresses: the edge overwrites X-Forwarded-For, and TRUSTED_PROXIES names exactly the edge’s addresses, never whole private ranges. backd’s access log shows real client addresses.
Only the edge is reachable: backd isn’t published directly, and /healthz and /readyz aren’t public.
The admin API is only reachable from your operators’ network: admin.allowed_networks in each realm.yaml (and admin_networks per admin where useful), plus ADMIN_ALLOW_FROM at the edge in the reference.
The metrics port is private (METRICS_ADDR is never published or proxied, and METRICS_TOKEN is set if anything but Prometheus can reach it).
API keys of services with fixed addresses are pinned to them with --networks.

MongoDB

MongoDB requires TLS and authentication, and isn’t reachable from the internet.
backd runs with PROVISION_MODE=verify as a user limited to the configured collections; admin credentials are only available to the provisioning step. See least-privilege provisioning.
Encrypted backups of every data and <realm>___system database run on a schedule, are copied off the server, and a restore has been practised. The decryption key isn’t on the server. See Backup and restore.

Operations

LOG_LEVEL is info (the default). debug logs every access denial with its reason, which is useful while writing rules but noisy and revealing in production.
Logs are collected and kept, and startup WARN lines are reviewed: realms with auth: disabled, realms without rules, API keys without an expiry or about to expire, anonymous-callable functions with no rate_limit, and (if you run functions) an executor that isn’t configured or doesn’t answer.
The container runs hardened: read-only filesystem, no Linux capabilities, CPU and memory limits (they also bound password hashing), and a stop grace period longer than SHUTDOWN_TIMEOUT.
You know how to report and receive security fixes: see SECURITY.md. Only the latest release gets them.

Command-line administration

Mon, 01 Jan 0001 00:00:00 +0000

The backd binary is also the command-line client for administering a realm. backd user and backd apikey don’t touch MongoDB: they call the realm’s admin API on a running backd, as an administrator. They never need database credentials, and every change they make goes through the same checks as any other admin request, including network restrictions.

Two commands write to MongoDB directly instead: backd bootstrap, which creates a realm’s first administrator, and backd secret rotate-key, which re-encrypts every realm’s secrets under a new master key (see Secrets).

Users and passwords

Mon, 01 Jan 0001 00:00:00 +0000

The backd user commands manage the users of a realm with auth: enabled. They call the realm’s admin API on a running backd, so you first log in as an administrator (or set BACKD_API_KEY to an admin API key). The realm’s first administrator is created with backd bootstrap. Server-side services can call the admin API directly.

backd login --realm blog --url https://api.example.com
backd user list --realm blog

Every command also takes --url, to pick the server for that command.

Sign-up, login and sessions

Mon, 01 Jan 0001 00:00:00 +0000

What a signed-in user may do with data is decided by each collection’s access rules. Server-side services use API keys instead.

Every realm with auth: enabled has its authentication endpoints under /v1/{realm}/_auth. A realm that doesn’t exist or has auth: disabled answers 404 not_found on all of them.

Sessions and tokens

Signing up or logging in returns a session token:

{
 "token": "bds_mxamh1_afbN3BMzfXqDWhxYpXKF58FhWQ4r9eaLc9ew",
 "token_type": "Bearer",
 "session_id": "dars2ql90v6000bbohr0",
 "expires_at": "2026-10-26T12:58:18.988Z",
 "user": {
 "id": "dars2ql90v600434mf0g",
 "email": "ada@example.com",
 "email_verified": false,
 "roles": [],
 "locale": "en",
 "created_at": "2026-09-26T12:58:18.838Z"
 }
}

Send it on every request that needs a signed-in user:

API keys

Mon, 01 Jan 0001 00:00:00 +0000

API keys let server-side services (a backend, a worker, a script) call a realm’s data routes. A key belongs to one realm and gives full access to all of that realm’s data, in every database.

Access rules (rules:)

Mon, 01 Jan 0001 00:00:00 +0000

Each collection of a realm with auth: enabled can have a rules: section in its collection.yaml, next to its schema.json. Rules decide, per operation, whether a caller may act on a whole document. There are no per-field permissions: data that needs different visibility belongs in a separate collection with its own rules.

$CONFIG_DIR/<realm>/<database>/<collection>/
 schema.json
 indexes.json # optional
 collection.yaml # optional — its `rules:` section is the access rules
 rules.test.yaml # optional — tests for the rules

The same file holds the collection’s other policy: files:, soft_delete: and on_owner_delete: (see the collection file). This page is about the rules: key.

Admin API

Mon, 01 Jan 0001 00:00:00 +0000

The admin API manages the users and API keys of a realm. backd user and backd apikey are command-line clients of it (see Command-line administration), and server-side services can call it directly. It lives under /v1/{realm}/_admin in every realm with auth: enabled.

Every request needs one of the realm’s API keys with the admin role, acting as itself, or the session of a user holding one of the realm’s admin roles:

Credential	Answer
API key with the `admin` role	Allowed
Session of a user holding an admin role (`admin: true` in `realm.yaml`)	Allowed
Session of a user whose admin role opens only some areas	Allowed for those areas; `403 forbidden` naming the missing one for the rest
API key with the `data` role	`403 forbidden`
None, or an invalid key	`401 unauthenticated`
Session of a user without an admin role	`403 forbidden`
`X-Backd-On-Behalf-Of` with any credential	`400 invalid_header`: admin calls never act as another user

Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

You will create a config repository with a working sample function, run it locally, call it three ways, write your own, see what it did, and test it. You need Docker (or Podman) and the backd binary; Deno is optional, because the build can run in Deno’s own image.

1. Create a project

backd template project --dir ./shop --realm shop
cd shop

This writes a complete repository: the shop realm with a sample database, a sample function with a test, Dockerfiles, a compose.yaml for local development (MongoDB, backd, the functions executor and the egress proxy) and a CI workflow. Everything you need is in the generated README.md; the parts below follow it.

Admin UI

Mon, 01 Jan 0001 00:00:00 +0000

The admin UI is a web interface for realm administrators and developers. It is a client of the Admin API and nothing more: it can do nothing the CLI can’t, and every call it makes is authenticated, network-checked and audited by the server like any other. This page is the start of its guide; each area of the interface (users, keys, secrets, audit, functions, data, configuration) is added to it as the area ships.

Writing a function

Mon, 01 Jan 0001 00:00:00 +0000

Layout

Each database may have one _functions directory: a Deno project for that application’s functions.

<realm>/<database>/
 posts/ collections, as usual
 _functions/
 deno.json the project's Deno config (imports), optional
 deno.lock pinned dependency versions, written by Deno
 lib/ code shared by the functions (not a function)
 stats/ one folder per function, named like collections
 function.yaml how the function runs (all keys optional)
 index.ts the code: index.ts or index.js
 input.schema.json optional JSON Schema of the input
 output.schema.json optional JSON Schema of the output
 .build/ bundles, written by `backd functions build`

Function names follow the same rules as collection names; lib is reserved for shared code.
The module’s default export is the function: it receives the call’s context and returns the output (any JSON value).

type Context = {
 input: unknown;
 user: { id: string; email: string; email_verified: boolean; roles: string[] } | null;
};

export default async function handler(ctx: Context) {
 return { hello: ctx.user?.email ?? "anonymous" };
}

Create a starter with:

Calling functions

Mon, 01 Jan 0001 00:00:00 +0000

Calling a function

curl -X POST https://api.example.com/v1/shop/orders/_func/checkout \
 -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
 -d '{"cart": "c1"}'
# → 200 {"order": "o7", "total": 1250}

The body is the function’s input (ctx.input), any JSON value; an empty body is null. The answer is its output. webhook functions are different: see Webhooks — the raw body reaches ctx.request.body unparsed, Content-Type isn’t required to be JSON, and the function’s own response is returned as-is.
In realms with auth: enabled, API keys may always call; other callers need the function’s invoke rule (webhook always needs one that allows anonymous callers). With X-Backd-On-Behalf-Of, an API key calls as that user.
With input.schema.json, invalid input answers 400 validation_error; with output.schema.json, an output that doesn’t match answers 500 invalid_output (and is logged). Neither applies to webhook.
An Idempotency-Key header reaches the function as ctx.idempotencyKey, and also deduplicates the call itself (see Idempotency).
sync functions run immediately and answer with their output, as above. async functions (below) answer 202 with a job to poll. webhook functions (below) set their own response.

Answer	When
`200`	A `sync` function returned; the body is its output
`202`	An `async` function was queued; poll `Location` for its result (see Async jobs)
(the function’s own choice)	A `webhook` function’s own response (see Webhooks)
`4xx` with the function’s code	The function threw `ctx.error(status, code, message)` (for `async`, this lands in the job’s `result` instead; `webhook` functions answer errors through their own response, not `ctx.error`)
`400 validation_error`	The input doesn’t match `input.schema.json`
`400 idempotency_key_required`	`function.yaml` has `idempotency: required` and the call has no `Idempotency-Key`
`401`, `403`	The `invoke` rule doesn’t allow the caller
`404 not_found`	No such function
`409 request_in_progress`	A call with this `Idempotency-Key` is still running (see Idempotency)
`422 idempotency_key_reused`	This `Idempotency-Key` was already used with different input
`429 too_many_requests`	A `sync` or `async` function, or its realm, is at its concurrency limit on this instance (`Retry-After: 1`); or the caller is over the function’s rate limit (`Retry-After` set to when it resets)
`500 function_failed`	The function threw another error, crashed, or went over its memory or CPU limit. The stack trace is in `backd`’s log only
`500 invalid_output`	The output is larger than `max_output`, or doesn’t match `output.schema.json`
`500 secret_missing`	The function declares a secret that isn’t set for its database or realm
`503 unavailable`	The executor isn’t configured, doesn’t answer, or runs its maximum of functions (`Retry-After: 1`); or a `webhook` function is at its concurrency limit (`Retry-After: 1` — `503`, not `429`, since webhook senders retry on 5xx)
`504 function_timeout`	The function didn’t finish within its `timeout`; it was stopped

From the JavaScript client and the command line

The same call, three ways:

function.yaml reference

Mon, 01 Jan 0001 00:00:00 +0000

function.yaml

Every key is optional. backd reads the file strictly: an unknown key or an invalid value stops startup, naming the file.

Key	Default	Meaning
`mode`	`sync`	`sync`: the caller waits for the output. `async`: the caller gets a job to check later. `webhook`: for callbacks from other services (see Webhooks) — needs `invoke` set to a rule that allows anonymous callers
`timeout`	`10s` (`sync`, `webhook`), `15m` (`async`)	The function is stopped after this long. At least `1s`; at most `60s` for `sync` and `webhook`, `24h` for `async`
`memory`	`128MB`	Memory for the function’s JavaScript heap, from `32MiB` to `4GiB`
`max_output`	`1MiB`	The largest output accepted, from `1KiB` to `64MiB` (`15MiB` for `async`)
`concurrency`	`10`	How many calls of the function may run at once on each `backd` instance (1–1000). With several instances, up to that many times this value run at once
`rate_limit`	none	Calls allowed per caller, counted across instances: `{per: user \| ip, limit: <n>, window: <duration>}`, window from `1s` to `24h`
`idempotency`	`optional`	Whether calls must send an `Idempotency-Key` header: `optional` or `required`
`invoke`	none	Who may call the function (see below). Without it, only API keys may call it
`admin`	`false`	`true` gives the function full access to the realm’s data, whatever the caller may do. Keep it off unless the function needs it
`internal`	`false`	`true` removes the function’s HTTP route: `_func/<name>` answers `404` to everyone, like a function that doesn’t exist. Only `backd` and scheduled runs may call it (see Internal functions). Can’t be combined with `invoke` or `mode: webhook`
`dev_only`	`false`	`true` makes `backd` refuse to start with the function unless `BACKD_DEV=true`: for development helpers such as the email capture function, which must never run in production
`email`	`false`	`true` gives the function `ctx.email.send()`: custom emails through the realm’s templates and delivery function, to any recipient, within the caps of `email.limits`. Needs `email` in `realm.yaml`; read the warning on that page first
`calls`	none	The functions of the same database this one lists as callable (see Internal functions); startup rejects unknown names, cycles and chains longer than 4 functions
`retry`	none	Tries a failed `async` function again: `{attempts, backoff, max_backoff}` (see Retrying a failed job). A single attempt unless `attempts` is above 1
`on_complete`	none	For an `async` function: `{function, on?}` queues that async function of the same database when a job of this one ends, with the outcome as its input; `on` narrows it to `ok`, `failed`, `cancelled`. See Be told when it ends
`schedule`	none	A cron expression: the function runs on a schedule. Needs `mode: async` and at least one running worker
`timezone`	`UTC`	For a scheduled function: the IANA time zone the schedule is read in, such as `Europe/Madrid`. Daylight saving changes are handled (documented there). Needs `schedule`
`overlap`	`allow`	For a scheduled function: `skip` doesn’t run a scheduled time while the function’s previous job hasn’t finished, and records the time as a `skipped` job. Needs `schedule`
`secrets`	none	Secrets the function may read: `NAME` (its own database’s) or `realm.NAME` (the realm’s). Names are upper-case letters, digits and `_`
`network`	none	Hosts the function may call: `host` or `host:port`, lower case, no scheme, path or wildcard. Without a list, a function can only call `backd`

Durations are written as in realm.yaml (30s, 15m, 1d). Sizes need a unit: B, KB, MB, GB (powers of 1000) or KiB, MiB, GiB (powers of 1024).

Async jobs

Mon, 01 Jan 0001 00:00:00 +0000

mode: async runs a function in the background instead of within the request. The call answers 202 at once with a job, and a worker runs the function later, on its own schedule and for as long as its timeout allows.

Use it when the work:

takes more than a few seconds (a sync call is capped at 60 s, and a caller shouldn’t be made to hold a request open for anything close to that);
must survive the caller going away (a browser tab closed, a mobile app suspended);
can be retried safely if something goes wrong;
fans out (a batch of emails, a report over many documents, a slow third-party call).

Use a sync function when the caller needs the answer to continue and it’s quick. Use cron when nobody asks for the work: it just has to happen on a schedule.

Scheduled functions

Mon, 01 Jan 0001 00:00:00 +0000

Add schedule to an async function and it runs by itself, with no caller: nightly cleanups, daily digests, hourly syncs, monthly reports.

examples/config/workshop/main/_functions/nightly_cleanup/function.yaml

# A scheduled function: `schedule` (cron, UTC) on an async function. There is
# no caller, so ctx.input is empty, ctx.user is null, and ctx.admin.db (full
# access, recorded as this function) is always available in a scheduled run.
# Needs at least one running worker: `backd worker`, or
# `backd serve --with-worker`.
#
# `internal: true`: nobody can call it over HTTP. An administrator can still
# run it by hand to test it, as its schedule would run it:
# backd functions invoke --function workshop/main/nightly_cleanup
internal: true
mode: async
schedule: "0 3 * * *" # every day at 03:00 UTC
timeout: 10m

examples/config/workshop/main/_functions/nightly_cleanup/index.ts

Internal functions

Mon, 01 Jan 0001 00:00:00 +0000

Some functions must never be reachable from the internet: a clean-up that deletes data, a helper shared by several public functions, a scheduled job nobody should trigger by hand. An internal function has no HTTP route at all.

Marking a function internal

# _functions/cleanup/function.yaml
internal: true
mode: async

POST /v1/<realm>/<database>/_func/cleanup now answers 404 not_found, exactly like a function that doesn’t exist, to every caller: anonymous, signed in, API keys of either role. Nothing reaches the executor, and the answer doesn’t reveal that the function exists.

Email

Mon, 01 Jan 0001 00:00:00 +0000

backd never talks to a mail server. A realm names one delivery function: an internal, async function that receives a finished message and hands it to whatever provider you chose (Postmark, SES, Resend, Mailgun, SendGrid, …). backd does everything else: the templates, the tokens and links, the retries, the limits.

Note

backd sends no mail from its own servers or addresses, so deliverability is your responsibility, handled with your provider: a verified sending domain (SPF, DKIM, DMARC), a dedicated sender address, the provider’s bounce and complaint handling and suppression lists. Watch your provider’s bounce and complaint rates before sending real email, and try the flows with a test mailbox first.

Configuration

Email is configured in realm.yaml; backd template realm writes the section commented, with every key explained. A realm without email sends no email at all.

Webhooks

Mon, 01 Jan 0001 00:00:00 +0000

mode: webhook receives a callback from another service — Stripe, GitHub, and the like — and answers it directly: ctx carries the raw request instead of parsed input, and the function sets the response’s status, headers and body itself instead of returning a JSON value backd interprets.

Warning

A webhook function is callable by anyone on the internet (invoke must allow anonymous callers), so the function itself is the only check. Verify the sender’s signature against the raw body before doing anything, and deduplicate by the sender’s event id: providers retry.

Payment provider example: payment_webhook verifies the sender’s HMAC signature, deduplicates the provider’s retries by event id, and marks the order paid.

Audit trail

Mon, 01 Jan 0001 00:00:00 +0000

Each realm with auth: enabled keeps an audit trail: one record per security-sensitive action or event, with who did it, to what, when and from where. It answers questions such as “who gave Bob the admin role?” or “which key created this user?”. Records can be read, but not changed or deleted: they expire after the realm’s retention period.

What is recorded

Action	When	Details
`user.create`	An administrator (or `backd bootstrap`) creates a user	`password` (whether one was set), `roles` (seeded from `realm.yaml`)
`user.signup`	A user signs up	`invited`, `roles`
`user.password`	An administrator sets a user’s password
`user.password_change`	A user changes their own password
`user.verify_email`	An administrator marks an email as verified, or not; or a user verifies it with the link in their email	`verified`
`user.password_reset`	A user sets a new password with a reset link	`verified_address`
`user.email_changed`	A user’s address changes: confirmed by the new address, or set by an administrator	`by` (`self` or `admin`)
`user.email_change_reverted`	The old address undid a change
`user.purged_unverified`	A worker deletes accounts that never verified their address	`count`, `older_than`
`function.invoke_manual`	An administrator runs a function by hand (admin API)	`as` (the user’s id, never their email, or null)
`files.versions.regenerate`	An administrator runs `backd files regenerate` (admin API)	`version`, `missing_only`, `job_id`
`storage.reconcile`	An administrator runs `backd storage reconcile` (admin API)	`delete`, `orphans` (how many were found), `deleted`
`storage.check`	An administrator runs a storage check (admin API); never the keys or anything stored	`ok`, `provider`, `bucket`
`data.check`	An administrator starts a schema check (admin API); the target is `data:<database>/<collection>`, `data:<database>` or `data:*`; never the report	`collections`, `limit`, `job_id`
`schedule.pause`, `schedule.resume`	An administrator pauses or resumes a function’s schedule (admin API); only a change is recorded; the target is `schedule:<database>/<function>`	none
`job.cancel`, `job.rerun`	An administrator cancels a job, or queues a finished one again (admin API); the target is `job:<id>`	`function`; for a re-run also `new_job`
`user.disable`, `user.enable`	An administrator disables or re-enables a user
`user.delete`	An administrator erases a user (the tombstone is made; the data work is in the job)	`job_id`
`user.erased`	The erase job finished, or failed for good	`job_id` and `counts` per `database/collection/operation`; `needs_attention` and `error` when it failed. Never content
`user.delete_account`	A user deletes their own account (it is deactivated, not erased)
`user.networks`	A user’s network restrictions change, through the API or from `realm.yaml`	`admin_networks`, `login_networks`
`role.add`, `role.remove`	A role is assigned or taken away, through the API or from `realm.yaml` seeds	`role`
`apikey.create`, `apikey.revoke`	An API key is created or revoked	`role`, `networks`, `expires_at`
`invitation.create`, `invitation.revoke`	An invitation is created or revoked	`bound_to_email` (whether it is), `expires_at`
`invitation.sent`	An invitation is emailed to its address	`expires_at`
`admin.login`	A user holding an admin role logs in	`session_id`
`data.create`, `data.update`, `data.delete`, `data.restore`, `data.purge`	A document is written through the admin data route (a batch audits each operation)	`database`, `collection`, `id`; the target is `doc:<database>/<collection>/<id>`; never content
`session.revoke`	An administrator ends a user’s session (admin API)	`session`
`admin.refused`	An admin API request is refused: by a network restriction, or because the administrator’s roles don’t open the area or hold the rights of the user or role involved	`reason`, `method`, `path`
`realm.bootstrap`	`backd bootstrap` creates the realm’s first administrator	`role`

Failed logins aren’t recorded here: they are throttled and counted, and every request is in the access log.

Secrets

Mon, 01 Jan 0001 00:00:00 +0000

A function that needs a third-party API key, or any value it shouldn’t hold in its own code, declares it in function.yaml’s secrets list and reads it from ctx.secrets, decrypted, at call time — never from an environment variable, which the function’s process doesn’t have.

Outbound network

Mon, 01 Jan 0001 00:00:00 +0000

Calling an outside API

A function reaches the outside world only for hosts it declares. Say it needs to email a digest through a provider’s HTTP API: declare the host, declare the key as a secret, and use fetch:

# function.yaml
mode: async
schedule: "@daily"
network: [api.mailer.example]  # host or host:port, lower case; no scheme, path or wildcard
secrets: [MAILER_KEY]

const res = await fetch("https://api.mailer.example/v1/send", {
 method: "POST",
 headers: { "content-type": "application/json", authorization: `Bearer ${ctx.secrets.MAILER_KEY}` },
 body: JSON.stringify({ to: "ops@example.com", subject: `Digest ${day}`, text: `${orders} orders, ${revenue / 100} in revenue` }),
});
if (!res.ok) throw ctx.error(424, "mailer_failed", `the mail provider answered ${res.status}`);

A request to any host not in network fails, and so does one to a private, loopback or link-local address, even for a declared host name that resolves to one.
Without a network list, a function can only call backd itself (through ctx.db).
This is how the cookbook’s daily_digest would send its result by email instead of storing it.
Send an idempotency key to the provider when the call has side effects and the function can run twice (Async jobs).

Egress: the network allowlist, completed

Why this exists. A function runs code you may not have written yourself (an npm dependency, a library update). If its outbound network were left to a single hostname allowlist, a bug or a compromised dependency could still: connect to MongoDB or another private service directly; reach your cloud provider’s metadata endpoint (169.254.169.254) and steal the credentials your infrastructure runs as (SSRF); or reach the executor’s or backd’s own internal endpoints. A hostname allowlist alone doesn’t stop any of this, because it checks names, not the addresses they resolve to — an allowed name can resolve to a private or loopback address (by mistake, by DNS rebinding, or because an attacker controls that DNS record) — and a raw TCP connection (Deno.connect, used directly instead of fetch) never goes through an HTTP proxy at all, so a proxy-based check alone can’t see it either.

Build, dev and test

Mon, 01 Jan 0001 00:00:00 +0000

Building

Functions are bundled before backd starts: each function, with everything it imports (lib/, npm and JSR packages), becomes one JavaScript file.

CONFIG_DIR=./config backd functions build
# bundled blog/main/stats → stats-3f2a9c0d1e4b5a6c.js (1843 bytes)

On Windows and macOS, backd itself runs, but its executor doesn’t (see what runs where): develop with the local stack’s containers, which include one.
The build runs deno bundle and needs Deno 2.9.7 on the PATH (or the binary named by DENO); it refuses any other version, because bundles must match the Deno that runs them. Without Deno installed, run it in the official Deno image with a Linux backd binary (from the release archives):

Running in production

Mon, 01 Jan 0001 00:00:00 +0000

What runs where

Functions add up to four kinds of process. All are the same backd binary (the executor’s image adds Deno), each in its own role:

Process	Command	Needed for	How many
API	`backd serve`	calling functions over HTTP	as many as you like, all with the same config
Executor	`backd executor`	running any function	one or more, reachable only from `backd` and workers
Worker	`backd worker`, or `backd serve --with-worker`	async jobs and cron schedules	one or more; each job and each scheduled run is done by exactly one
Egress	`backd egress`	functions that declare `network`	one or more; the executor’s only way out

Function logs

Mon, 01 Jan 0001 00:00:00 +0000

Every function call — sync, webhook, and once an async job finishes — is recorded in <realm>___system.invocations: what happened, not what was sent or returned. backd is a short debugging window, not a log archive — plan to ship logs elsewhere for anything you need to keep.

What’s recorded

The function (<database>/<name>), who called it, its mode, status and duration.
The function’s own console output (console.log, console.error, …), already masked of any declared secrets’ exact values.
The steps the function reported with ctx.step(), closed when the call ended (at most 100).
The request id, so a record can be matched to backd’s own JSON log line for the same call.
Never the input or output. If you need to reproduce what a specific call did, log what matters yourself with console.log inside the function.

{
 "id": "d3c9ljp8hc2g00b6s1m0",
 "at": "2026-09-29T12:00:03.500Z",
 "function": "orders/checkout",
 "actor": "user:d3c9lg38hc2g00b6s1lg",
 "mode": "sync",
 "status": "ok",
 "code": null,
 "duration_ms": 118,
 "request_id": "darf9mq5mh5g00aq9df0",
 "job_id": null,
 "parent_id": null,
 "origin": "http",
 "logs": [{ "level": "log", "line": "charging card for 1250" }],
 "steps": [],
 "steps_omitted": 0
}

status is one of ok, function_error, timeout, memory, cpu, crash, output_too_large, busy, bundle or cancelled (an async job’s attempt that an administrator cancelled while it ran) — the same reasons a call can end that show up in backd’s own log and in the error table. code is the function’s own error code (ctx.error’s second argument) when status is function_error. For an async call, mode is async and job_id names the job; the record is written once the job finishes, not when it’s queued.

Cookbook

Mon, 01 Jan 0001 00:00:00 +0000

Every recipe here is a function of the workshop realm (examples/config/workshop in the repository): a tiny shop with orders, refunds, reports, digests and events. The code on this page is read straight from those files, and TestWorkshopExample runs every function for real (MongoDB, a real executor, a real worker), so what you read is what runs.

Run the workshop

The repository’s local stack serves the realm, and its backd runs a worker (serve --with-worker), so jobs and schedules work:

Deleting and erasing users

Mon, 01 Jan 0001 00:00:00 +0000

backd separates two things people call “deleting an account”:

What	Who	Effect	Reversible
Deactivate	the user (`DELETE /_auth/me`, with their password), or an administrator (`PATCH /_admin/users/{id}` with `disabled`, `backd user disable`)	the user is disabled and every session ends; all data is kept	yes: an administrator reactivates (`backd user enable`)
Erase	an administrator (`DELETE /_admin/users/{id}`, `backd user delete --yes`)	the user becomes a tombstone, and the policies of your collections are applied (below)	no

Files in functions

Mon, 01 Jan 0001 00:00:00 +0000

A function reaches the files of a document through the same client it uses for data: files(id, field) on a collection of ctx.db or ctx.admin.db. It makes the same requests as any client, to the _files routes, so the same limits, type detection, journal and usage totals apply.

const photos = ctx.db("main").collection("people").files(personId, "photo");

const doc = await photos.put(bytes, { name: "ada.png", type: "image/png" }); // the updated document
const file = await photos.get(); // { file, response, bytes(), text() }
const link = await photos.link(); // { url, expires_at }
await photos.delete(); // the field's files; delete(fileId) removes one


`put(data, { name, type, ifMatch })`	Stores a file (a string, bytes, a `Blob` or a stream): it replaces a single field’s file and is added to a `multiple` field’s. Resolves with the document, which now holds the file’s details. `type` is a hint: backd detects the real one from the content
`get(fileId?)`	Downloads a file. Without `fileId`, the one a single field holds; a field with several needs one. The bytes come through backd, even where downloads are redirects for everyone else, because a function can’t reach the bucket
`link(fileId?)`	`{ url, expires_at }`, exactly like `?link=json`: for the app to open. A link of the storage is for the bucket; a backd link needs `BACKD_URL`, so it can name backd’s public address
`delete(fileId?, { ifMatch })`	Removes one file, or every file of the field. Resolves with the document

As the caller, or as the function

ctx.db acts as the caller: put and delete are asked of the document’s update rule (with data and changed() as for an upload), get and link of the read rule, and an upload is recorded as theirs. A document the caller can’t read is a NotFoundError.

Connecting storage

Mon, 01 Jan 0001 00:00:00 +0000

A realm connects its storage with a storage: section in its realm.yaml. It needs auth enabled, like everything that keeps secrets in the realm’s system database.

storage:
 provider: minio  # aws | minio | r2 | digitalocean
 endpoint: https://files.example.com
 region: us-east-1
 bucket: acme-files
 prefix: prod  # required; unique per backd instance sharing the bucket
 access_key: secret:STORAGE_ACCESS_KEY
 secret_key: secret:STORAGE_SECRET_KEY
 download: presigned  # presigned | proxy
 presigned_ttl: 5m
 pending_ttl: 1h
 quota:
 realm: 10GiB  # optional
 user: 1GiB  # optional

Setting	Meaning
`provider`	Required. One of `aws`, `minio`, `r2`, `digitalocean`. Anything else stops `backd` at startup.
`endpoint`	Only the scheme and host, `https://<host>[:port]`; the bucket goes in `bucket`, never in the endpoint. Required for `minio` and `r2`; `aws` and `digitalocean` derive it from `region`. It must have the shape the provider’s page says, or startup stops and names the setting.
`public_endpoint`	`minio` only. The address signed links are made for when browsers can’t reach `endpoint` (`backd` at `http://minio:9000`, browsers at `http://localhost:9000`). `backd` never connects to it: it is only written into links.
`region`	`aws` and `digitalocean` read it from the endpoint (and refuse one that disagrees); `r2` is always `auto`; `minio` accepts any (default `us-east-1`).
`bucket`	The bucket’s name, which must already exist.
`prefix`	Required. Starts every object key (`<prefix>/<realm>/…`). See below.
`access_key`, `secret_key`	Required, written `secret:NAME`: the names of two realm secrets, never the keys themselves.
`download`	The realm’s default for how files are delivered: `presigned` (a redirect to a signed link, the default) or `proxy` (streamed through `backd`).
`presigned_ttl`	How long a signed link works: `10s` to `7d`, default `5m`.
`pending_ttl`	How long an upload nobody attached to a document is kept: `1m` to `7d`, default `1h`.
`quota.realm`, `quota.user`	Optional limits on the bytes documents reference: for the whole realm, and for the documents one user owns. Sizes like `500MiB` or `10GiB`. See Quotas.

There is no path_style setting (the provider decides how a bucket is addressed) and no sse (encryption at rest is the bucket’s default). backd template realm writes the section commented, with an example for each provider.

AWS S3

Mon, 01 Jan 0001 00:00:00 +0000

storage:
 provider: aws
 region: eu-west-1  # the bucket's region; the endpoint is derived
 bucket: acme-files
 prefix: prod
 access_key: secret:STORAGE_ACCESS_KEY
 secret_key: secret:STORAGE_SECRET_KEY


Endpoint	`https://s3.<region>.amazonaws.com` (derived from `region`; if you write it, `region` must agree)
Addressing	virtual-hosted (`<bucket>.s3.<region>.amazonaws.com`)
Signed SHA-256 (direct uploads)	supported
Largest single PUT	5 GiB
Multipart uploads (files above 5 GiB)	supported, with a SHA-256 per part
`backd storage check` reads	CORS and default encryption

Setting it up

Create the bucket in the region you will name, with Block all public access on. The bucket is always private.

MinIO

Mon, 01 Jan 0001 00:00:00 +0000

storage:
 provider: minio
 endpoint: https://minio.internal.example:9000  # http://minio:9000 only with BACKD_DEV=true
 # public_endpoint: http://localhost:9000 # when browsers reach MinIO at another address
 bucket: acme-files
 prefix: prod
 access_key: secret:STORAGE_ACCESS_KEY
 secret_key: secret:STORAGE_SECRET_KEY


Endpoint	any `https://<host>[:port]` (plain `http` only when `BACKD_DEV=true`, for development)
Addressing	path style (`<endpoint>/<bucket>/…`)
Region	any; default `us-east-1`
Signed SHA-256 (direct uploads)	supported
Multipart uploads (files above 5 GiB)	supported, with a SHA-256 per part
Oldest version tested	`RELEASE.2025-09-07T16-13-09Z` (the repository’s tests run against Chainguard’s current build as well)
`backd storage check` reads	neither CORS nor encryption (MinIO doesn’t expose them to an S3 client): it says so

Development

Images: the MinIO project no longer publishes container images (the old minio/minio and quay.io/minio/minio repositories stopped being pullable). The repository’s stacks use Chainguard’s build (cgr.dev/chainguard/minio and cgr.dev/chainguard/minio-client); both have no shell, so the server can’t run a health check and one-shot jobs call mc directly. You can also build MinIO from its source. backd storage check tells whether whatever you run behaves.

Cloudflare R2

Mon, 01 Jan 0001 00:00:00 +0000

storage:
 provider: r2
 endpoint: https://<account id>.r2.cloudflarestorage.com  # no bucket in it
 bucket: acme-files
 prefix: prod
 access_key: secret:STORAGE_ACCESS_KEY
 secret_key: secret:STORAGE_SECRET_KEY


Endpoint	`https://<account id>.r2.cloudflarestorage.com` (also `.eu.` and `.fedramp.` for those jurisdictions). R2’s console shows it with the bucket’s name after it: write only the host, and the name in `bucket`.
Addressing	virtual-hosted
Region	always `auto`
Signed SHA-256 (direct uploads)	supported: R2 rejects an upload whose digest differs (confirmed by the provider smoke test)
Largest single PUT	5 GiB
Multipart uploads (files above 5 GiB)	supported, with a SHA-256 per part (confirmed by the provider smoke test)
`backd storage check` reads	neither CORS nor encryption: it says so

Setting it up

Create the bucket in the Cloudflare dashboard (R2 → Create bucket). Keep it private: don’t enable public access or a public domain.
Create an API token (R2 → Manage API tokens) with Object Read & Write limited to that bucket. R2 shows an Access Key ID and a Secret Access Key once: those are the two secrets.
Encryption at rest: R2 encrypts all objects at rest; there is nothing to set.
CORS, needed for direct uploads and cross-origin downloads: set it on the bucket (Settings → CORS policy) for your app’s origin, with GET, PUT and HEAD and the allowed headers Content-Type and x-amz-checksum-sha256. backd storage check can’t read it: try an upload from the app.
Set the secrets and run backd storage check --realm <realm>.

R2’s tokens limit the bucket, not a prefix: the prefix still keeps each backd instance’s files apart, but a key can reach the whole bucket, so give each instance sharing a bucket a token of its own only if you must trust no instance with another’s files; otherwise use a bucket per instance.

DigitalOcean Spaces

Mon, 01 Jan 0001 00:00:00 +0000

storage:
 provider: digitalocean
 region: nyc3  # the Space's region; the endpoint is derived
 bucket: acme-files
 prefix: prod
 access_key: secret:STORAGE_ACCESS_KEY
 secret_key: secret:STORAGE_SECRET_KEY


Endpoint	`https://<region>.digitaloceanspaces.com` (derived from `region`; if you write it, `region` must agree)
Addressing	virtual-hosted
Signed SHA-256 (direct uploads)	supported (documented in the Spaces API reference)
Largest single PUT	5 GiB
Multipart uploads (files above 5 GiB)	not enabled until the provider smoke test confirms a SHA-256 per part: `max_size` stays at 5 GiB
`backd storage check` reads	neither CORS nor encryption: it says so

Setting it up

Create the Space in the region you will name, with File listing restricted (private).
Create a Spaces access key (API → Spaces Keys), scoped to that Space with Read, Write and Delete. The key and its secret are the two realm secrets.
Encryption at rest: Spaces encrypts data at rest; there is nothing to set.
CORS, needed for direct uploads and cross-origin downloads: set it in the Space’s Settings for your app’s origin with GET, PUT and HEAD, and allow the headers Content-Type and x-amz-checksum-sha256. backd storage check can’t read it: try an upload from the app.
Set the secrets and run backd storage check --realm <realm>.

A Spaces key is scoped to a Space, not to a prefix: use a Space per backd instance, or keep prefix distinct and accept that a key can reach every prefix of its Space.

File fields

Mon, 01 Jan 0001 00:00:00 +0000

A collection says which fields of its documents carry files under files: in its collection.yaml. The realm needs a storage: section.

files:
 avatar:
 max_size: 2MiB
 types: [image/png, image/jpeg, image/webp]
 receipts:
 multiple: true
 max_files: 5
 max_size: 10MiB
 types: [application/pdf, image/*]
 manual:
 max_size: 20MiB
 download: proxy
 cache: 1h

Key	Default	Meaning
`max_size`	required	The largest one file may be (`512KiB`, `10MiB`, `1GiB`). Checked while the bytes stream in
`types`	any	Allowed content types, `image/png` or a family such as `image/`. Checked against the type detected from the file’s content*, never the one the client claims. A family never admits SVG, HTML or XML: name them to accept them
`multiple`	`false`	The field is a list of files instead of one
`max_files`	`10`	With `multiple`: how many files the field may hold (1 to 1000)
`upload`	`proxy`	`proxy` streams the bytes through backd; `direct` has the client send them straight to the bucket with a signed link, which backd verifies afterwards (Direct uploads). `max_size` is at most 5GiB for `direct`, or 4TiB with a provider that takes uploads in parts
`download`	the realm’s	`presigned` redirects to a short-lived link of the storage; `proxy` streams the file through backd
`presigned_ttl`	the realm’s	How long this field’s links last (at most 7 days)
`cache`	none	With `download: proxy`: how long shared caches may keep the file, only when anyone may read the document
`keep_metadata`	`false`	By default the metadata of JPEG and PNG pictures is removed when they are stored. `true` stores them exactly as sent
`max_pixels`	the instance’s	For images: the most pixels (width × height) the field gets versions for. It can only lower `BACKD_IMAGE_MAX_PIXELS`; a higher value stops startup
`versions`	none	Resized copies of an image, declared by name: see Image versions

A field name is lower-case letters, digits and underscores. A file field is declared only here: one that is also in schema.json is a startup error, because backd adds its schema itself, to the validators in MongoDB, to the rules and to the queries.

Uploads and downloads

Mon, 01 Jan 0001 00:00:00 +0000

Every file operation is an operation on a document and follows its access rules: the update rule for uploads and removals, the read rule for downloads. A document the caller can’t read answers 404, never revealing its files. API keys and the admin data route skip rules, as everywhere.

Operation	Request
Upload	`POST /v1/{realm}/{database}/{collection}/{id}/_files/{field}`
Download	`GET …/{id}/_files/{field}/{file id}`
Remove one	`DELETE …/{id}/_files/{field}/{file id}`
Clear the field	`DELETE …/{id}/_files/{field}`

The same four exist under /v1/{realm}/_admin/data/…. There is no PUT: a file is replaced by uploading another.

Rules for files

Mon, 01 Jan 0001 00:00:00 +0000

Files have no rules of their own: they follow the rules of their document.

Operation	Rule
Upload, remove one, clear a field	`update`
Download, `?link=json`, `?file_links=true`	`read`

File fields are known to the rules like any other field of the collection, so a rule can read them from document and data. For a file operation:

document is the document as stored; data is the document as it would be after the change; changed() lists the changed fields, which includes the file field.
The rule runs before any byte is stored: a refused upload costs nothing and leaves nothing behind.
API keys and ctx.admin.db in functions skip rules.

Reserving a field for functions

A field only a function may set, such as a generated thumbnail, is a file field the rule refuses to clients:

Keeping storage tidy

Mon, 01 Jan 0001 00:00:00 +0000

backd never lists the bucket while it runs. Instead, every change that stops a document referencing a file queues that file’s object for deletion, and the workers (backd worker, or backd serve --with-worker) delete it, retrying with a growing wait when the storage fails. An upload that never became part of a document is journaled, and the workers delete its object after a grace period (one hour), or when a pending or direct upload expires.

Files in apps

Mon, 01 Jan 0001 00:00:00 +0000

An app reaches files through the JavaScript client, which makes the requests described in Uploads and downloads. This page is about what to do with them in a page.

Uploading

uploadFile(id, field, file, { onProgress }) puts a file in a document, and prepareUpload(field, file) makes one for a document that doesn’t exist yet: name its ref in the create. Both work whether the field takes uploads through backd or straight to the bucket; the client asks the field (fileField(field)), which also tells the page max_size, types and max_files to check a file before sending it.

Security of files

Mon, 01 Jan 0001 00:00:00 +0000

The files feature was reviewed as a whole before this page: rules on file operations, storage credentials and the endpoint restriction, both upload modes, type detection, links, proxied downloads, pending uploads and their tokens, the journal and deletion queue, reconcile, erasure and the functions API. This page says what came out of it.

How files are protected

The bucket is private, and only backd reaches it. Files are served through backd, or through a link backd signed for one file. backd connects only to the realm’s declared endpoint (checked after DNS resolution, with no redirects and no proxy); public_endpoint is only written into links and is never connected to.
A file is as private as its document. An upload, a removal and a direct-upload start are update operations; a download, a link and ?file_links=true are read operations; a document the caller can’t read answers 404 for all of them, never revealing its files. The rule runs before any byte is stored, with data as the document will be, and again when the file is attached. See Rules for files.
Clients never write what describes a file. The id, name, size, detected type, SHA-256 and time are backd’s: a client’s write drops them, and a PUT keeps the stored files. The object key is <prefix>/<realm>/<database>/<collection>/<file id>: no name, and no part of a request, ever reaches it.
The type is what the bytes say. It is detected from the content, never the client’s claim, and types is checked against it. A family such as image/* or text/* does not admit active content (SVG, HTML, XML, scripts): a field takes one only when it names it. A field with no types takes anything, and serves it only as a download.
Downloads can’t run in your origin. A presigned link comes from the storage’s origin, never backd’s, and forces attachment. A proxied download carries Content-Disposition: attachment, X-Content-Type-Options: nosniff and Content-Security-Policy: sandbox. Names are cleaned (no path, no control or direction characters, 255 bytes) and quoted, so a name can’t add a header or leave its quotes.
Direct uploads are verified, not trusted. The link has the length, the type and the SHA-256 signed in, so the storage refuses another body; completing then checks the size and the checksum the storage computed (a missing one fails) and detects the type from the first bytes. A mismatch deletes the object. A file sent in parts is verified the same way, part by part and as a whole: every part has its own SHA-256 signed in, and the composite checksum the storage computes is checked against the declared parts. The sha256 recorded for it is that composite’s digest, not the SHA-256 of its bytes.
Tokens are secrets. An upload token is 256 random bits, only its SHA-256 is stored, it is compared in constant time, used once, bound to a collection and field and, when a signed-in user made it, to that user, and never logged. An upload id alone attaches or completes nothing, and every wrong, used, expired or foreign reference answers the same 400.
backd’s own links are an HMAC over the realm, database, collection, document, field, file and expiry, with a per-realm key, verified in constant time: a link can’t be moved to another file or kept past its time. Rotating the key (setting or deleting the secret BACKD_FILES_LINK_KEY) invalidates every one.
Backd’s keys are not a function’s to read. A function can’t declare the realm’s storage secrets or the link key as its own secrets: the configuration is refused at startup.
Cleanup never touches what a document holds. A worker checks that no document references an upload before it deletes it, and reconcile only considers objects named like files, older than 24 hours, with no open upload record, and that no declared field references.
Metadata is removed from pictures. The GPS position, camera and comments of a JPEG, and the text and time of a PNG, are dropped as it is stored, unless the field sets keep_metadata: true: see Metadata and the GPS risk.
Limits bound what a caller can store: max_size and max_files per field, BACKD_MAX_UPLOAD_BYTES for proxy uploads, 20 unused uploads per caller (IPv6 callers counted per /64) and a rate for starting them.

What you are responsible for

The bucket and its key. Keep it private, give the key only what your provider’s page lists, on the realm’s prefix; encryption at rest is the bucket’s setting. Give each backd instance its own prefix: two instances on one prefix collide, and a reconcile on one deletes the other’s files.
Links outlive rules. A storage link and a backd link both work for anyone who has them until they expire, even if the document’s rules change meanwhile. Keep presigned_ttl short on sensitive fields; the default is five minutes.
Caches outlive rules too. With download: proxy and cache, a shared cache may keep a file of a document anyone can read, and keeps it after you tighten the rule. Use cache only for files meant to be public.
Set BACKD_URL in production. backd-signed links name backd’s public address; without it they are built from the request’s Host header, which a caller chooses.
Anonymous uploads cost storage. Where a collection’s create rule admits anonymous callers, each address may hold 20 unused uploads of up to max_size for an hour. Keep max_size small on such fields and let the edge rate-limit by address. Nothing scans files for malware.
A removed file field leaves trusted-looking data. If you take a field out of files: and later declare it again, what the documents still hold in it is read as file details again. Don’t re-use a field name for something else; clear it first.
Functions with ctx.admin.db skip the rules, files included: review them as privileged code.
Backups. MongoDB backups don’t include files: back the bucket up at the provider and run reconcile after a restore.

Security model

Mon, 01 Jan 0001 00:00:00 +0000

This page summarizes how backd protects data in realms with auth: enabled, and what the operator is responsible for. To report a vulnerability, see SECURITY.md.

Who can do what

Caller	Proves identity with	Can
Anonymous	nothing	What access rules allow `user == nil`
User	session token (`bds_…`)	What access rules allow that user; manage their own account and sessions
Server-side service	API key (`bdk_…`) with the `data` role	Everything in the realm’s data; act as a user with `X-Backd-On-Behalf-Of`
Management tooling	API key with the `admin` role	The same, plus the admin API: users, roles, invitations, API keys
Administrator	session of a user holding an admin role, for example through `backd login`	What access rules allow that user, plus the admin API
Operator	access to `CONFIG_DIR` and MongoDB	Everything, including creating a realm’s first administrator with `backd bootstrap`

Credentials belong to one realm and are unknown in every other realm. Invalid, expired or revoked credentials are always refused (401), never downgraded to anonymous access.

JavaScript client

Mon, 01 Jan 0001 00:00:00 +0000

backd-js is a small JavaScript library for backd. It is plain ES modules with no dependencies and no build step, and it runs wherever fetch does: browsers, Node 20+, Deno, Bun and edge runtimes. It ships TypeScript declarations, so editors autocomplete it in JavaScript and TypeScript projects alike.

Install

npm install backd-js

It has no dependencies, needs no build step and works with any bundler. Without one, import it in a browser with an import map pointing at the package’s src/index.js (from a CDN such as https://cdn.jsdelivr.net/npm/backd-js/src/index.js, or from your own server), as the example app does.

Blog

Mon, 01 Jan 0001 00:00:00 +0000

A small blog. Anyone can read published posts. Signed-in users write posts, keep drafts, and edit, publish, unpublish and delete their own. Each post shows when and by whom it was written, and its category. Clicking an author or a category lists only those posts, and both filters combine.

It shows the everyday use of backd: public and private documents in one collection, ownership, and posts signed with the writer’s own identity, all decided on the server by access rules. Unlike the expenses example, it doesn’t share documents between users, so rules cover everything it needs: it has no known holes, only the limits below. One page, above the post list, does need a server-side function: a count of every published post, and of the caller’s own, neither computable from what a reader may list.

Expenses without functions

Mon, 01 Jan 0001 00:00:00 +0000

A small group-expenses tracker in the style of Tricount or Splitwise. People create a group, invite others by email, record what they paid, and see who owes whom.

Unlike the blog, where each post belongs to its writer, here documents are shared between users, and some of the checks it needs involve more than one document. It is also a lesson in the limits of access rules. Its rules are as strict as rules can be today, and they still leave holes, because some checks need data from another document or logic on the server. Those holes are documented here on purpose: this is deliberately the “before” half of a pair. Expenses with functions is the “after” — the same app, same layout, with holes 1–4 closed by server-side functions, compared side by side with what changed and why. Hole 5 is closed by email verification in both: access here is by email address, so the address has to be the user’s own.

Expenses with functions

Mon, 01 Jan 0001 00:00:00 +0000

The same group-expenses tracker as expenses without functions, with the same layout, the same data model’s spirit, and the same rules where nothing needed to change — but holes 1 through 4 are closed, by five small functions instead of client-trusted copies. Hole 5 (signing up with someone else’s email) is closed too, but by email verification, not by functions: the realm requires a verified address, and rules and functions check user.email_verified.

Read expenses without functions first if you haven’t: this page assumes you know the five holes it documents, and spends its time on what’s different here and why.

Workshop tour

Mon, 01 Jan 0001 00:00:00 +0000

The functions cookbook explains each function of the workshop realm. The workshop tour lets you use them: one page, one panel per feature, and an inspector beside it that shows every call the page makes, so you see what the browser sent and what backd answered.

It is part of the local stack (make example, then https://localhost:8443/example/workshop/). The page is plain JavaScript on backd-js, with no build step, in clients/js/examples/workshop; the realm is examples/config/workshop.

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

backd is a single stateless Go service. Apart from the registry built at startup, all state lives in MongoDB, so several identical instances can run side by side.

CONFIG_DIR ──load──▶ registry ──▶ provisioner ──▶ MongoDB
 │ ▲
HTTP ──▶ handlers ──────┴──▶ storage.Repository ───┘

Layers

Package	Role
`internal/settings`	Environment variables → `Settings`
`internal/registry`	Immutable realm → database → collection tree, with realm settings (`realm.yaml`), compiled schemas and field index
`internal/templates`	Embedded starter files written by `backd template`
`internal/rules`	Compiles the `rules:` of `collection.yaml`: expr-lang rules and runs the static checks (guards, roles, fields, `now`, read rules as filters)
`internal/auth`	Storage-neutral identity model (users, identities, sessions), password policy, argon2id hashing with a concurrency cap, sign-up, login and session handling; persistence behind `auth.Store` (in-memory fake in `internal/auth/authtest`)
`internal/query`	Parses the list query language into `storage.Condition`s, checking every field and value against the schema
`internal/storage`	Backend-neutral `Repository` interface, `Document`/`Query`/`Page`/`Condition`/`Filter` types, `Fetch` (single reads under a read rule), and the errors `ErrNotFound`, `ErrVersionMismatch`, `ErrConflict` and `ErrUnavailable`
`internal/httpapi`	Router, middleware, error envelope, document, `/_auth` and `/_admin` handlers, CORS
`internal/jsonnum`	Normalizes JSON numbers to int64 or float64
`internal/mongodb`	Everything MongoDB-specific: connection, validator translation, provisioner (including realm system databases), `Repository` and `auth.Store` implementations

No MongoDB driver types cross the storage interface. Another document store (for example Amazon DocumentDB) can be added as a new implementation without touching handlers or validation.

API contract

Mon, 01 Jan 0001 00:00:00 +0000

api/openapi.yaml is the contract of the HTTP API, in OpenAPI 3.1. Clients, such as the JavaScript client, are written against it, so the server must never drift from it.

What it covers

Every route: health probes, /_auth, /_admin and the generic document routes.
Every status an operation documents explicitly, plus a default for errors that can happen anywhere (404 for an unknown realm, 413, 415, 500, 503).
Response bodies, including the error envelope and its closed list of code values.
Response headers clients rely on: ETag, Location, Retry-After, WWW-Authenticate, X-Request-ID, and Cache-Control: no-store on account data.
Documents as open objects. Their fields depend on each collection’s schema.json, but id and _meta are described exactly.

How it’s enforced

Two checks keep the spec honest, and both run in CI.

backd

Getting started

Quick start with docker compose#

1. An empty shelf

The realm#

Data model (CONFIG_DIR)

Starting from a template#

Realm settings (realm.yaml)

Example#

2. Members

The realm grows#

Apply, and create the three accounts#

Schema validation

Translation to MongoDB#

Finding documents that no longer match#

3. Who may touch what

The assets rules#

4. Invitations

Close the door#

5. The first function

A function is three files#

6. Reaching the outside

preview#

7. Functions calling functions

The notifications collection#

8. Work that takes time

The function#

9. On a schedule

schedule#

10. Email for real

The realm side#

11. Being called by the internet

The function#

Documents

Document shape#

12. Running it

API keys#

Querying

13. Files on assets

14. Big files and thumbnails

Attachments, straight to the storage#

15. Sharing and counting downloads

Counting downloads#

Deploying config

The config repository#

Production deployment

Metrics

Turning it on#

Backup and restore

What a backup must include#

Hardening checklist

Realms#

Credentials#

The edge#

MongoDB#

Operations#

Command-line administration

Users and passwords

Sign-up, login and sessions

Sessions and tokens#

API keys

Access rules (rules:)

Admin API

Quickstart

1. Create a project#

Admin UI

Writing a function

Layout#

Calling functions

Calling a function#

From the JavaScript client and the command line#

function.yaml reference

function.yaml#

Async jobs

Scheduled functions

Internal functions

Marking a function internal#

Email

Configuration#

Webhooks

Quick start with docker compose

The realm

Starting from a template

Example

The realm grows

Apply, and create the three accounts

Translation to MongoDB

Finding documents that no longer match

The assets rules

Close the door

A function is three files

preview

The notifications collection

The function

schedule

The realm side

The function

Document shape

API keys

Attachments, straight to the storage

Counting downloads

The config repository

Turning it on

What a backup must include

Realms

Credentials

The edge

MongoDB

Operations

Sessions and tokens

1. Create a project

Layout

Calling a function

From the JavaScript client and the command line

function.yaml

Marking a function internal

Configuration

What is recorded

Calling an outside API

Egress: the network allowlist, completed

Building

What runs where

What’s recorded

Run the workshop

As the caller, or as the function

Setting it up

Development

Setting it up

Setting it up

Reserving a field for functions

Uploading

How files are protected

What you are responsible for

Who can do what

Install

Layers

What it covers

How it’s enforced