141 lines
5.6 KiB
Markdown
141 lines
5.6 KiB
Markdown
# 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 shipped the **localhost** section;
|
|
SLICE-4 adds **pre-production (PPE)**. The production section lands with the prod
|
|
stand-up.
|
|
|
|
## 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 (see PPE below).
|
|
|
|
## Pre-production (PPE)
|
|
|
|
PPE is stood up and deployed through the **launch-app / flotilla-core** suite only
|
|
(handbook §8.5 — provisioning is an operator-run gesture). The app's deployment
|
|
record is `deployment.toml` at this repo's root; flotilla-core consumes it.
|
|
|
|
### One-time provisioning (operator-run, in order)
|
|
|
|
1. **Cloud foundation** — `scaffold-gcp-project`: the GCP project, its dedicated
|
|
`--no-activate` gcloud config, billing, core APIs, ADC quota pin.
|
|
2. **Managed database** — `provision-datastore` (launch-app §6.6a, built for ecomm's
|
|
D-7/D-8): Cloud SQL for PostgreSQL 16, private-IP-only, automated backups +
|
|
point-in-time recovery; writes the full DSN to Secret Manager as
|
|
`<project>/ecomm-ppe-database-url`. Bound on the deployment record as
|
|
`ECOMM_DATABASE_URL`.
|
|
3. **Secrets** (references only — bytes go in via stdin, never through a session):
|
|
`ECOMM_SESSION_SECRET` (fresh random), `ECOMM_SMTP_PASSWORD` (the shared
|
|
Wiggleverse relay credential), and flotilla's own Gitea read token for this
|
|
private repo.
|
|
4. **VM + edge** — `provision-vm`: the e2-micro, IAP-only SSH, nginx + Cloudflare
|
|
origin TLS, the systemd unit, DNS for `ecomm-ppe.wiggleverse.org`.
|
|
5. **Deployment record** — `flotilla-core deployment scaffold ecomm … -o
|
|
deployment.toml`, validate, commit it here, `deployment import --reconcile`.
|
|
|
|
### Deploy
|
|
|
|
Each release is a git tag `v<VERSION>` matching the repo-root `VERSION` file (the
|
|
pin). The one gesture, from the flotilla-core repo's venv:
|
|
|
|
```bash
|
|
CLOUDSDK_ACTIVE_CONFIG_NAME=ecomm .venv/bin/flotilla-core deploy ecomm
|
|
```
|
|
|
|
Nine phases, fail-stop; it ends by polling `https://ecomm-ppe.wiggleverse.org/healthz`
|
|
and requiring `status == "ok"` and `version == <target>`. Watch it yourself the same
|
|
way:
|
|
|
|
```bash
|
|
curl https://ecomm-ppe.wiggleverse.org/healthz
|
|
```
|
|
|
|
### Configuration surface (PPE values)
|
|
|
|
| Env var | Kind | Value |
|
|
| --- | --- | --- |
|
|
| `ECOMM_DATABASE_URL` | secret ref | `<project>/ecomm-ppe-database-url` (from provision-datastore) |
|
|
| `ECOMM_SESSION_SECRET` | secret ref | `<project>/ecomm-ppe-session-secret` |
|
|
| `ECOMM_SMTP_PASSWORD` | secret ref | the shared Wiggleverse relay credential |
|
|
| `ECOMM_MAILER` | overlay | `smtp` |
|
|
| `ECOMM_COOKIE_SECURE` | overlay | `1` |
|
|
| `ECOMM_SMTP_HOST` / `_PORT` / `_USER` / `_FROM` | overlay | the relay coordinates (non-secret) |
|
|
|
|
### The rehearsal (PUC-11)
|
|
|
|
From empty persistence: the deploy migrates the schema at startup (INV-7); then a
|
|
real sign-up → one-time code arriving by **real email** → create storefront → admin,
|
|
through the public flows alone. Record each rehearsal here when it happens.
|
|
|
|
**Rehearsals:**
|
|
|
|
- **2026-06-11 — PPE first bootstrap (v0.4.0, session 0024): ✅** First-ever ecomm
|
|
deploy (`flotilla-core deploy ecomm`, 9/9 phases green, deploys.id=40) onto a
|
|
freshly provisioned environment — project `wiggleverse-ecomm`, Cloud SQL
|
|
`ecomm-ppe-pg` (provisioned by launch-app `provision-datastore`, first run), VM
|
|
`ecomm-ppe`. The app self-migrated the empty database at startup; the operator
|
|
then walked sign-up → real emailed code (Gmail relay) → create storefront →
|
|
honestly-empty admin in a browser, through the public flows alone. Findings
|
|
captured: OTC email branding (#16); identity should outgrow ecomm
|
|
(engineering#49/#50).
|
|
|
|
## Production
|
|
|
|
Lands with the prod stand-up — the **identical gesture** on a prod deployment record
|
|
(BUC-5a): same provisioning skills, same deploy, same rehearsal.
|