Repository navigation
ADR 0037
Status: accepted · Built: planned · Date: 2026-11-19 · Supersedes: 0017
Built: a Compose project per repository (root: the nearest .git or pnpm-workspace.yaml) with Postgres, the user pool from the Spotcraft image of the CLI's version (SPOTCRAFT_DEV_IMAGE overrides it) and Mailpit; ports, the pool's secret and the project name kept in .spotcraft/dev.json; the project is spotcraft-dev--<6 hex of a hash of the root's path>, since two worktrees with the same folder name shared one stack (stacks from 0.6.0 keep spotcraft-dev-); spotcraft dev, env, db reset, migrate, status, stop, ls. Found while building: a local pool trusts any http://localhost: origin (AUTH_LOCAL_ORIGINS), since dev servers run on any port. Not yet: CI using the same command instead of its Postgres service, and Umami (with analytics).
ADR 0017 runs one local Postgres for every app on a machine, so they share data and a reset of one can affect another. Apps now also need the user pool (ADR 0035) and, later, email, so a database alone no longer matches what an app gets on the server.
-
One stack per repository: a Compose project
spotcraft-dev-<repo slug>with Postgres (the version pinned for the server), the auth service with amainpool, and Mailpit to catch email. It has its own volume. Free ports are picked on first start and kept in.spotcraft/dev.json, which is not committed. All deployables in a monorepo share the stack. -
Same as the server: the
appsdatabase with theauthschema and a schema and role per app (app_<slug>), their limits and grants, the provisioning code, the reserved env var names, JWT claims and JWKS (docs/contracts.md). In a monorepo, every deployable has its own schema in the one database, so their tables can point at the same users. -
Commands:
-
spotcraft devstarts the stack if needed, creates the app's schema, writes the missing reserved variables to.env(overwriting nothing), and runs themigratecommand fromspotcraft.json. -
spotcraft dev envprints the variables. -
spotcraft dev db resetrecreates the app's schema after asking, then runsmigrate. -
spotcraft dev status,stopandls(every stack on the machine).
-
- CI uses the same command before tests, instead of its own Postgres service.
- Still no Studio and no copying production data down.
- Repositories don't share local data, and CI runs what developers run.
- Several stacks running at once use more memory.
- The local pool only knows the repository's own users. Testing one account across apps from different repositories needs a staging instance.
Published from docs/. Edit the files there; changes here are overwritten.