| name | dev-server |
| description | Bring up the full Orbit local stack for manual/visual testing — Docker Postgres, then the orbit-api .NET backend, then the web dev server — in dependency order with readiness gates. Use when the user wants to run the app locally, start the dev server, spin up the local stack, or view web changes in a browser. |
| argument-hint | [web-only | up | down | status] |
Dev Server — full local Orbit stack
Brings up the three tiers in order, each gated on the previous being ready: Docker Postgres → orbit-api (.NET) → web (npm run web). Launch the long-running processes in the background so they persist across turns, then report the URLs.
Paths & ports (verified)
| Tier | Where | Command | URL / port |
|---|
| DB | Docker container orbit-postgres (postgres:17) | docker start orbit-postgres | localhost:5432 |
| API | C:\Users\thoma\Documents\Programming\Projects\orbit-api | dotnet run --project src/Orbit.Api | http://localhost:5000 |
| Web | C:\Users\thoma\Documents\Programming\Projects\orbit-ui-mobile | npm run web | http://localhost:3000 |
- DB connection (from
appsettings.Development.json): Host=localhost;Port=5432;Database=orbit;Username=postgres;Password=postgres.
- Web→API wiring needs nothing: the BFF proxy reads
API_BASE and defaults to http://localhost:5000. Only intervene if apps/web/.env* sets API_BASE to a non-localhost value (then the local web would hit prod) — warn the user, don't edit their .env.
Mode (from $ARGUMENTS)
down → jump to Stop.status → jump to Status.web-only → skip DB+API (assume already up or pointed at prod); run only Step 4.- empty /
up → run all steps.
Step 1 — Docker Postgres
- Confirm Docker is up:
docker info (>/dev/null). If it errors, tell the user to start Docker Desktop and stop.
- Start the existing container, creating it only if absent:
docker start orbit-postgres 2>/dev/null || docker run -d --name orbit-postgres \
-e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=orbit \
-p 5432:5432 postgres:17
- Gate on readiness (loop, ~30s budget):
docker exec orbit-postgres pg_isready -U postgres until it prints accepting connections.
Step 2 — Migrations
Normally a no-op: the API auto-applies migrations on startup in Development (Step 3), so skip this. Only run a manual apply if you need the schema current before booting the API — and note dotnet ef does NOT load appsettings.Development.json (it reads the empty base appsettings.json), so you MUST pass the connection string explicitly:
cd "C:/Users/thoma/Documents/Programming/Projects/orbit-api"
dotnet ef database update --project src/Orbit.Infrastructure --startup-project src/Orbit.Api \
--connection "Host=localhost;Port=5432;Database=orbit;Username=postgres;Password=postgres"
(Plain dotnet ef database update fails with "ConnectionString property has not been initialized" — that's the missing --connection, not a real error.)
Step 3 — API (background, gated)
cd "C:/Users/thoma/Documents/Programming/Projects/orbit-api"
dotnet run --project src/Orbit.Api
Launch it with run_in_background: true. Then gate on health: poll http://localhost:5000/health until 200 (the XpAwardLog backfill runs on first startup — allow ~60s). Do not proceed to web until the API answers.
Step 4 — Web (background, gated)
cd "C:/Users/thoma/Documents/Programming/Projects/orbit-ui-mobile"
npm run web
Launch with run_in_background: true. Gate on http://localhost:3000 returning HTML. npm run web = turbo run dev --filter=@orbit/web (Next dev), so it serves only the web app, not Expo.
Report
Print the live URLs and what's running:
DB localhost:5432 (docker: orbit-postgres)
API http://localhost:5000 (/scalar for docs, /health)
Web http://localhost:3000 ← open this
Tell the user the web proxies to the local API by default, and to open http://localhost:3000. The API + web run in background tasks; their logs stream to their task output files.
Status
docker ps --filter name=orbit-postgres for the DB; check http://localhost:5000/health and http://localhost:3000. Report which tiers are up.
Stop
- Kill the background API + web tasks (TaskStop on their task ids, or close the shells).
- Stop the DB only if asked:
docker stop orbit-postgres (keep the container so data + next docker start are instant; never rm it unless the user asks).
Notes
- Bring tiers up in order; a failed gate stops the chain (don't start the API before Postgres accepts connections, nor web before the API is healthy).
- This is a local-only dev runbook; it touches no secrets and edits no
.env.
