wiggleverse-ecomm/docs/BOOTSTRAP.md

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:

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

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)

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).