README
¶
backd
backd is an open-source (MIT), config-driven backend: one stateless Go service over MongoDB. You declare realms, databases and collections as files on disk — a JSON Schema, access rules and indexes per collection — and backd serves a schema-validated REST API for them, with users, sessions, API keys and server-side functions built in.
Documentation → fernandezvara.github.io/backd · Getting started · Quickstart · Tutorial
Features
- Data model as files — a directory per realm, database and collection, each collection with a
schema.json, access rules and indexes;backd config checkruns the startup validation in CI. Configuration - REST API — CRUD and an allowlisted query language (
where,order_by, pagination, counts), optimistic concurrency withETag/If-Match, batch writes, references withexpand, aggregations and full-text search. HTTP API - Auth built in — users, sessions and API keys per realm; sign-in with Google, Microsoft or Apple, a second factor, magic links, per-document access rules, consents and an audit trail. Authentication
- Organizations — groups of users for B2B apps: roles, teams, team roles with time windows, documents scoped to an organization or team, invitations and company email templates. Organizations
- Functions and triggers — isolated Deno processes for privileged logic: sync calls, background jobs, cron schedules, webhooks, encrypted secrets, and functions that run when documents change. Functions, Triggers
- Realtime — subscribe to a collection's changes over one server-sent event stream, with the caller's rules applied, resumable and bounded. Realtime
- Files and push — documents carry files in your own S3-compatible storage with image versions and quotas; push notifications reach FCM, APNs and browsers. Files, Push
- Clients and types —
backd-json npm (browsers, Node and edge runtimes, admin API included) andpackage:backdon pub.dev (Flutter and standalone Dart);backd typesgenerates TypeScript or Dart per realm andbackd openapian OpenAPI 3.1 document for everything else. Clients - A production path — tested reference deployment (TLS, least-privilege MongoDB, encrypted backups), a config fingerprint every instance enforces, and signed releases. Operate
Quick start
The shortest path to a realm you can build against — see the Quickstart for the full walkthrough. Get backd from GitHub Releases (binaries for Linux, macOS and Windows) or the image ghcr.io/fernandezvara/backd, then generate a project and run its compose stack:
backd template project --dir ./my-app --realm demo
cd my-app
export EXECUTOR_TOKEN=$(openssl rand -base64 32)
export CALLBACK_KEY=$(openssl rand -base64 32)
export EGRESS_KEY=$(openssl rand -base64 32)
docker compose up --build -d # MongoDB + backd + the functions executor
docker compose exec backd /backd bootstrap --realm demo --email me@example.com
backd login --realm demo --url http://127.0.0.1:8080 --email me@example.com
KEY=$(backd apikey create --realm demo --name local --expires 1d)
curl -X POST http://127.0.0.1:8080/v1/demo/main/posts \
-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-d '{"title": "Hello", "published": true}'
curl http://127.0.0.1:8080/v1/demo/main/posts -H "Authorization: Bearer $KEY"
(backd login asks for the bootstrap password and enrolls an authenticator app — the template's admin role requires a second factor.)
To explore instead, this checkout ships example realms and applications on a local HTTPS stack:
make dev-build && make dev-examples # https://localhost:8443 — the apps index is at /example/
The stack creates (and renews) a local CA in docker/certs/ and prints how to trust it. Under examples/config, the shop realm needs no key (auth: disabled — never expose such a realm) and blog answers reads to anyone while writes want a user or an API key; make dev-backd ARGS='bootstrap --realm blog --email <email>' creates the first administrator.
Documentation
| I want to… | Go to |
|---|---|
| Understand what backd is | Getting started |
| Run a realm end to end | Quickstart |
| Build a complete app, chapter by chapter | Tutorial |
| Reference: API, auth, functions, files, push, clients | Build |
| Deploy, administer, monitor and back up | Operate |
| See complete applications | Examples |
| Work on backd itself | Contribute |
Security
Report vulnerabilities per SECURITY.md. The security model explains what backd protects, and the hardening checklist what to check before exposing a realm; deploy/production is a tested reference for a public deployment (TLS, rate limits, least-privilege MongoDB).
Development
make test # full test suite in docker (same as CI)
make test-local # tests that need no external services
make build # binary in bin/backd
make docs-serve # documentation site at http://localhost:1313/backd/
make example # backd's own stack, built from your checkout: API, docs (live reload), example apps
Other targets cover the development stack (make dev), the production end-to-end test (make prod-test), release archives (make release-check), and the attack and tour scripts (make hack-expenses*, make workshop-tour, make shelf-tour). The workflow is documented in Contribute → Local development. Documentation lives in docs/ and is built with Hugo.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
Package api embeds backd's HTTP API contract, which per-realm documents are derived from.
|
Package api embeds backd's HTTP API contract, which per-realm documents are derived from. |
|
clients
|
|
|
js
Package jsclient embeds the JavaScript client's sources, so the functions runner can give each function a real client as ctx.db.
|
Package jsclient embeds the JavaScript client's sources, so the functions runner can give each function a real client as ctx.db. |
|
cmd
|
|
|
backd
command
Command backd serves a config-driven REST API over MongoDB.
|
Command backd serves a config-driven REST API over MongoDB. |
|
internal
|
|
|
adminui
Package adminui serves the admin web interface under /_ui/.
|
Package adminui serves the admin web interface under /_ui/. |
|
appconfig
Package appconfig keeps a realm's app configuration: the values admins and functions set over the declared defaults, with optimistic concurrency, an audited history and rollback.
|
Package appconfig keeps a realm's app configuration: the values admins and functions set over the declared defaults, with optimistic concurrency, an audited history and rollback. |
|
auth
Package auth holds backd's identity model: users, their sign-in identities and password handling.
|
Package auth holds backd's identity model: users, their sign-in identities and password handling. |
|
auth/authtest
Package authtest provides an in-memory auth.Store for tests.
|
Package authtest provides an in-memory auth.Store for tests. |
|
changefeed
Package changefeed reads a database's change history for the two features built on it: triggers (a dispatcher with a durable position) and realtime (consumers that open when a client subscribes).
|
Package changefeed reads a database's change history for the two features built on it: triggers (a dispatcher with a durable position) and realtime (consumers that open when a client subscribes). |
|
cron
Package cron parses five-field cron expressions and computes their schedule, in UTC or in a time zone.
|
Package cron parses five-field cron expressions and computes their schedule, in UTC or in a time zone. |
|
egress
Package egress runs backd's egress role: the only way a function process reaches the network.
|
Package egress runs backd's egress role: the only way a function process reaches the network. |
|
email
Package email holds what backd knows about the emails it asks a realm's delivery function to send: the kinds, the templates (loaded from <realm>/email/ into memory at startup and rendered per message), and the shape of the message handed to the function.
|
Package email holds what backd knows about the emails it asks a realm's delivery function to send: the kinds, the templates (loaded from <realm>/email/ into memory at startup and rendered per message), and the shape of the message handed to the function. |
|
executor
Package executor runs server-side functions: `backd executor` is a supervisor that runs each invocation in its own Deno process, with only the function's permissions and limits, and returns its output.
|
Package executor runs server-side functions: `backd executor` is a supervisor that runs each invocation in its own Deno process, with only the function's permissions and limits, and returns its output. |
|
functions
Package functions builds server-side functions: `backd functions build` bundles each function of a database's Deno project into one file with `deno bundle`, and records the bundles in a manifest that startup checks.
|
Package functions builds server-side functions: `backd functions build` bundles each function of a database's Deno project into one file with `deno bundle`, and records the bundles in a manifest that startup checks. |
|
httpapi
Package httpapi is backd's HTTP layer: routing, middleware, error envelope, the generic document handlers and the /_auth endpoints.
|
Package httpapi is backd's HTTP layer: routing, middleware, error envelope, the generic document handlers and the /_auth endpoints. |
|
imaging
Package imaging turns one image into resized copies, safely: pure Go (no cgo, no external library), the pixel count checked from the header before anything is decoded, the orientation flag applied, a time limit per image, and output that never carries metadata.
|
Package imaging turns one image into resized copies, safely: pure Go (no cgo, no external library), the pixel count checked from the header before anything is decoded, the orientation flag applied, a time limit per image, and output that never carries metadata. |
|
jsonnum
Package jsonnum converts json.Number values into concrete Go numbers.
|
Package jsonnum converts json.Number values into concrete Go numbers. |
|
metrics
Package metrics is backd's Prometheus instrumentation (design/metrics.md).
|
Package metrics is backd's Prometheus instrumentation (design/metrics.md). |
|
mongodb
Package mongodb holds everything MongoDB-specific: the $jsonSchema validator translation, the repository implementation and the provisioner.
|
Package mongodb holds everything MongoDB-specific: the $jsonSchema validator translation, the repository implementation and the provisioner. |
|
oauth
Package oauth talks to external identity providers (Google, Microsoft, Apple): the authorize URL, the code exchange, the verification of ID tokens and Apple's client secret.
|
Package oauth talks to external identity providers (Google, Microsoft, Apple): the authorize URL, the code exchange, the verification of ID tokens and Apple's client secret. |
|
oauth/oauthtest
Package oauthtest is a small identity provider for tests: it signs ID tokens with its own key, publishes them, and plays the parts of a provider's authorize, token and keys endpoints, so the sign-in flow can be run end to end without a real one.
|
Package oauthtest is a small identity provider for tests: it signs ID tokens with its own key, publishes them, and plays the parts of a provider's authorize, token and keys endpoints, so the sign-in flow can be run end to end without a real one. |
|
openapigen
Package openapigen derives an OpenAPI 3.1 document for one realm from the generic contract (api/openapi.yaml) and the realm's loaded config: its collections with their schemas and features, its enabled authentication methods, its functions, and what its clients can reach.
|
Package openapigen derives an OpenAPI 3.1 document for one realm from the generic contract (api/openapi.yaml) and the realm's loaded config: its collections with their schemas and features, its enabled authentication methods, its functions, and what its clients can reach. |
|
push
Package push holds what backd knows about push notification messages that doesn't depend on the realm's settings or its store: the templates they are written from, the portable message and its validation, and the payloads each provider receives (design: design/push-notifications.md §6).
|
Package push holds what backd knows about push notification messages that doesn't depend on the realm's settings or its store: the templates they are written from, the portable message and its validation, and the payloads each provider receives (design: design/push-notifications.md §6). |
|
pushsend
Package pushsend holds backd's built-in push senders: FCM (HTTP v1), APNs (HTTP/2, token authentication) and Web Push (VAPID, RFC 8291).
|
Package pushsend holds backd's built-in push senders: FCM (HTTP v1), APNs (HTTP/2, token authentication) and Web Push (VAPID, RFC 8291). |
|
query
Package query parses and checks the list query language (where, order_by) against a collection's schema, producing backend-neutral storage conditions.
|
Package query parses and checks the list query language (where, order_by) against a collection's schema, producing backend-neutral storage conditions. |
|
realtime
Package realtime serves subscriptions to document changes as server-sent events (design/triggers-and-realtime.md §17 and §20).
|
Package realtime serves subscriptions to document changes as server-sent events (design/triggers-and-realtime.md §17 and §20). |
|
registry
Package registry loads the realm/database/collection tree from CONFIG_DIR into an immutable, validated registry used by routing, validation and provisioning.
|
Package registry loads the realm/database/collection tree from CONFIG_DIR into an immutable, validated registry used by routing, validation and provisioning. |
|
rules
Package rules checks and compiles a collection's rules (the `rules:` section of its collection.yaml): expr-lang expressions deciding, per operation, whether a caller may act on a whole document.
|
Package rules checks and compiles a collection's rules (the `rules:` section of its collection.yaml): expr-lang expressions deciding, per operation, whether a caller may act on a whole document. |
|
rulestest
Package rulestest runs the fixtures of `backd rules test`: it decides who may read, create, update and delete which documents of a collection, with the collection's real rules (the `rules:` of its collection.yaml) and schema.json and no database, and compares the decisions with what the fixture expects.
|
Package rulestest runs the fixtures of `backd rules test`: it decides who may read, create, update and delete which documents of a collection, with the collection's real rules (the `rules:` of its collection.yaml) and schema.json and no database, and compares the decisions with what the fixture expects. |
|
settings
Package settings reads backd's runtime configuration from environment variables.
|
Package settings reads backd's runtime configuration from environment variables. |
|
storage
Package storage defines the backend-neutral data access contract.
|
Package storage defines the backend-neutral data access contract. |
|
storage/storagetest
Package storagetest is a small in-memory S3 server for tests that need an object storage but not a real one: path-style addressing, the operations backd uses (bucket HEAD, PUT, GET with Range, HEAD, DELETE, ListObjectsV2) and the signed SHA-256 check a PUT carries.
|
Package storagetest is a small in-memory S3 server for tests that need an object storage but not a real one: path-style addressing, the operations backd uses (bucket HEAD, PUT, GET with Range, HEAD, DELETE, ListObjectsV2) and the signed SHA-256 check a PUT carries. |
|
templates
Package templates writes commented starter files for realms and databases into CONFIG_DIR (`backd template`).
|
Package templates writes commented starter files for realms and databases into CONFIG_DIR (`backd template`). |
|
triggers
Package triggers dispatches the changes of a database to the functions collections declare (design/triggers-and-realtime.md §9): one dispatcher per deployment holds a lease, reads the change stream from a durable position, evaluates each trigger's condition and queues one async job per match.
|
Package triggers dispatches the changes of a database to the functions collections declare (design/triggers-and-realtime.md §9): one dispatcher per deployment holds a lease, reads the change stream from a durable position, evaluates each trigger's condition and queues one async job per match. |
|
typegen
Package typegen turns a realm's loaded config into TypeScript types: documents, queries, functions, configuration, templates and roles.
|
Package typegen turns a realm's loaded config into TypeScript types: documents, queries, functions, configuration, templates and roles. |
Click to show internal directories.
Click to hide internal directories.