Tutorial

This tutorial builds Shelf, a team asset library: members save links and notes, curators publish them, public links share them, a digest emails the news. Each chapter adds one backd feature because the app needs it, and ends in a working state with a checklist of what now works.

Short on time? The Quickstart runs one realm and a few curl calls on the backd template project stack. The Tutorial uses its own stack, downloaded from this site, so nothing from the Quickstart carries over.

You do not need a backd checkout: the app, the client and the released containers all download from this site. You need only Docker and a text editor.

Words used here#

The short list for this tutorial; the glossary covers the whole documentation.

• A realm is one application’s world — its users, roles, sessions and settings (shelf). A database groups collections inside it (main), and a collection holds documents (assets). The URLs say it: /v1/{realm}/{database}/{collection}.
• A function is a small TypeScript program backd runs in a sandbox when something calls it: a person, another function, a clock or the internet.
• A rule is an expression in the rules: of a collection’s collection.yaml that decides whether a read or write is allowed. A HOLE comment (chapter 3) marks the place where a rule can’t say what you mean and a function has to take over.
• An operator is the administrator of the realm; a curator is a member who may publish; a member is everyone else.

What you need#

• Docker with Compose v2 (docker compose version prints a version) and free ports 8080 (the app and the API) and, from chapter 13, 9000 (the files’ storage); the first start downloads about 1 GB of images.
• A text editor and a terminal with a POSIX shell (macOS, Linux, or WSL on Windows — the examples use curl, sed and $VARIABLES). Node 20 or newer only for chapter 11’s feed script (optional).
• This tutorial’s stack is a separate thing from the backd documentation you are reading: the docs may be at https://localhost:8443 or on GitHub Pages, the tutorial’s app is always http://localhost:8080.

To start over at any point: docker compose down -v (deletes the database), then up -d again.

What runs, and what you edit#

docker compose up -d starts these containers (and, from chapter 13, MinIO). You only ever edit files on your side of them:

Conventions#

• <angle brackets> in a command are values you substitute. $TOKEN is a session token from POST /_auth/login (chapter 3 shows how); $OP is the operator’s (chapter 4).
• A config/ path is relative to your starter folder: config/shelf/main/assets/schema.json is the assets collection of the main database in the shelf realm.
• The stack runs backd in dev mode: save a file under config/ (rules, realm.yaml, schemas, function code) and backd reloads in a moment, bundling a changed function itself. docker compose logs backd says config reloaded, or what is wrong with the file you saved; the previous config keeps serving until it loads.

The starter#

Create a folder and fetch the stack and the app:

mkdir shelf && cd shelf
mkdir -p app client config/shelf

# The stack: released backd images + MongoDB + executor + egress + nginx.
curl -fsSLO https://fernandezvara.github.io/backd/tutorial/compose.yaml
curl -fsSLO https://fernandezvara.github.io/backd/tutorial/nginx.conf

# The finished Shelf app: each chapter makes one more part of it work.
for f in index.html app.js style.css; do
  curl -fsSL "https://fernandezvara.github.io/backd/tutorial/app/$f" -o "app/$f"
done
mkdir app/lib
for f in pico.min.css alpine.min.js zip.js; do
  curl -fsSL "https://fernandezvara.github.io/backd/tutorial/app/lib/$f" -o "app/lib/$f"
done

# The JavaScript client the app imports (backd-js, as source).
for f in account admin auth buckets cache client config consents data errors expand files functions index oauth orgs push realtime sha256 storage typed xhr; do
  curl -fsSL "https://fernandezvara.github.io/backd/tutorial/client/$f.js" -o "client/$f.js"
done

Once chapter 1 has written the first config, docker compose up -d runs backd at http://localhost:8080: nginx serves app/ at /, proxies /v1 to the API and serves client/ at /example/client/, exactly like the app’s importmap expects. config/ is where you write the realm — chapter by chapter.

The chapters#

The three accounts#

From chapter 2 on you use three accounts, all created in chapter 2 while sign-up is open: operator@shelf.example (the administrator), curator@shelf.example (publishes) and one of your own (a member). Chapter 4 closes sign-up, so create them before it — the lock-out section there is the way back if you didn’t.

How a chapter reads#

Each chapter is a diff on the state the previous one left: the files to create or change (quoted from the same files the repository runs and tests; a fetch block lists them as a download loop when you’d rather not type), the commands to run, and a “you should see” list at the end — if every line holds, the chapter worked. Chapters follow each other: each starts from the state the previous one left, so do them in order (or start from the repository’s examples/config/shelf when you want the finished realm). A chapter that needs something extra says so in its first lines, like chapter 13’s storage, chapter 16’s authenticator app or chapter 11’s Node script.

When something is off#

• curl -s http://localhost:8080/readyz answers once MongoDB is a replica set and backd serves; for a minute after up it may not. docker compose ps shows which container is down.
• docker compose logs backd is the first place to look. A bad config file doesn’t stop backd in dev mode: the log names the file and line, and the last good config keeps serving; every request is logged with its request_id, which also appears in every error body.
• An error body is {"error": {"code", "message", "details"}}, and the status says what kind: 401 not signed in or the session ended (log in again; sessions last 30 days); 403 signed in but a rule or an invoke expression refuses it; 404 the thing doesn’t exist or you may not read it; 400 invalid input, with the failing fields in details; 409 a unique index or an already-used value; 412 the document changed since you read it; 503 a function call while the executor is still starting.
• A change that does nothing: docker compose logs backd says whether it reloaded (config reloaded) or why it refused (a TypeScript error in a function shows Deno’s output, with the file and line). The log also shows the function’s console.log lines and, when a call fails, its error.
• Start over: docker compose down -v, then up -d — and sign up the three accounts again (chapter 2).