docs(slice-1): BOOTSTRAP.md localhost bring-up runbook (BUC-5)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-10 08:42:00 -07:00
parent 886da73eb6
commit cd951cca2c
1 changed files with 64 additions and 0 deletions
@@ -0,0 +1,64 @@
+# Bootstrapping ecomm
+
+Bringing an environment from **empty persistence** to "first merchant, first
+storefront" through the product flows alone (SD-0001 BUC-5). Empty is a working state
+(INV-1): the app applies its own schema migrations at startup; there is no seed step.
+
+This document grows per environment. SLICE-1 ships the **localhost** section; the
+pre-production and production sections land with SLICE-4.
+
+## Localhost
+
+### Prerequisites
+
+- **Docker** (Desktop or Engine) with Compose v2 — the one external prerequisite. The
+  dev datastore is a single PostgreSQL container; the app itself runs natively for a
+  fast dev loop (D-7).
+- **Python 3.13** and **Node 20+** on your PATH. `scripts/dev.sh` creates the backend
+  venv and installs frontend deps on first run.
+
+### Bring-up
+
+From a clean checkout:
+
+```bash
+scripts/dev.sh
+```
+
+This:
+
+1. starts the dev Postgres container and waits for it to report healthy (the script
+   owns the container's lifecycle);
+2. creates the backend virtualenv and installs dependencies (first run only);
+3. installs the frontend's npm dependencies (first run only);
+4. runs the FastAPI backend on **:8000** — which connects to the empty database and
+   applies all pending migrations itself (INV-7) — and the Vite dev server on
+   **:5173**, proxying `/api` to the backend.
+
+Press **Ctrl-C** to stop the backend and Vite. The database container keeps running.
+
+### Verify
+
+```bash
+curl http://localhost:8000/healthz
+```
+
+Expected: `{"status":"ok"}` (HTTP 200) — the process is up, the database is reachable,
+and migrations are current. Open <http://localhost:5173> to see the app shell.
+
+### Reset to empty (rehearse the bootstrap)
+
+```bash
+docker compose down -v
+```
+
+This removes the container and its named volume, returning persistence to empty. The
+next `scripts/dev.sh` re-migrates from scratch — exactly the day-one state every
+environment starts from (BUC-5a).
+
+### Configuration
+
+`scripts/dev.sh` sets `ECOMM_DATABASE_URL` to the local compose DSN
+(`postgresql://ecomm:ecomm@localhost:5432/ecomm`). No deployment shape is baked into
+the app (INV-8); deployed environments supply this and other config from Secret
+Manager (SLICE-4).