galaxy-game/tools/local-dev/README.md

# `tools/local-dev/` — Galaxy local development stack

A docker-compose stack that brings up postgres + redis + mailpit +
backend + gateway so the UI Vite dev server (run on the host) can
talk to a real authenticated stack without any cloud dependency.

The stack is the recommended baseline for UI work that goes beyond
the mocked Playwright fixtures: every payload exercises the real
FlatBuffers wire, every authenticated call verifies the response
signature against the dev keypair, and every email passes through
Mailpit's web UI for inspection.

This stack is **not** a CI gate (that role belongs to
[`tools/local-ci/`](../local-ci/README.md), which boots a Gitea +
Actions runner and replays workflow files). The two stacks are
independent and can coexist on the same machine; they bind different
ports and use different networks.

## Bring it up

```sh
make -C tools/local-dev up
```

`up` builds the local-dev backend and gateway images on first run
(pulls postgres, redis, mailpit), waits for every service to report
healthy, and returns. Subsequent invocations reuse the built images.

After the stack is healthy:

```sh
pnpm -C ui/frontend dev
```

Open <http://localhost:5173> for the UI and
<http://localhost:8025> for Mailpit.

The first `make up` builds the engine image (`galaxy-engine:local-dev`)
from `game/Dockerfile`. Subsequent invocations skip the build when the
image already exists; force a rebuild with `docker rmi galaxy-engine:local-dev`
followed by `make build-engine`.

## Daily flow

```sh
make -C tools/local-dev up        # bring up (idempotent, fast on warm cache)
pnpm -C ui/frontend dev           # in another terminal
# ...edit UI, browse, repeat...
make -C tools/local-dev down      # stop containers, keep state
```

State persists in named Docker volumes between `up`/`down` cycles, so
games created on Tuesday survive into Wednesday. Wipe with
`make clean` when you want a fresh database.

## Logging in

Two paths coexist by default:

1. **Fixed dev code (fast).** `tools/local-dev/.env` ships
   `BACKEND_AUTH_DEV_FIXED_CODE=123456`. After requesting a code in
   the UI, type `123456` — `ConfirmEmailCode` accepts that literal
   in addition to the real bcrypt-verified code stored on the
   challenge row. The override emits a loud warning at backend boot
   and is rejected by the production env loader (`BACKEND_ENV` guard
   in `backend/internal/config`).
2. **Real Mailpit code.** Open <http://localhost:8025>, find the
   most recent message, copy the six-digit code, paste it into the
   UI. This exercises the full mail outbox path, including SMTP
   handoff and gomail TLS-mode handling.

To force the second path (no fast-bypass), edit
`tools/local-dev/.env` and clear `BACKEND_AUTH_DEV_FIXED_CODE`, then
`make rebuild` (or simply `docker compose up -d backend` to recreate
the backend with the new env).

## Auto-provisioned dev sandbox

`make up` provisions a private game called **Dev Sandbox** owned by
the dev user (default `dev@local.test`). The flow is implemented in
`backend/internal/devsandbox` and runs on every backend boot when
`BACKEND_DEV_SANDBOX_EMAIL` is non-empty in `tools/local-dev/.env`.

Bootstrap is idempotent — re-running `make up` after a `make down`
finds the existing user, dummy participants, game, and memberships
without creating duplicates. If a previous boot crashed mid-way
(game stuck in `enrollment_open` or `ready_to_start`), the next boot
resumes the lifecycle.

To log in straight into the sandbox:

1. `make -C tools/local-dev up`
2. `pnpm -C ui/frontend dev` (in another terminal)
3. Open <http://localhost:5173/login>, enter `dev@local.test`, then
   the dev code `123456`.
4. The lobby shows **Dev Sandbox** in *My Games*; click in.

To disable the bootstrap, clear `BACKEND_DEV_SANDBOX_EMAIL` in
`tools/local-dev/.env` and `docker compose up -d backend` (or
`make rebuild`). Existing users / games are not removed.

Terminal sandbox games — anything in `cancelled`, `finished`, or
`start_failed` — are deleted on every boot before find-or-create
runs. The cascade declared in `00001_init.sql` removes the
matching memberships, applications, invites, runtime records,
and player mappings in the same write, so the dev user's lobby
shows exactly one running tile at all times. Cancelling the
sandbox manually and running `docker compose restart backend`
(or `make rebuild`) yields a fresh game without leaving dead
tiles behind.

The bootstrap requires:
- `galaxy-engine:local-dev` Docker image (`make build-engine`).
- `BACKEND_DEV_SANDBOX_ENGINE_VERSION` parses as plain semver
  (`MAJOR.MINOR.PATCH`); the default `0.1.0` is what the bootstrap
  registers in the `engine_versions` row that points at the image.
- `BACKEND_DEV_SANDBOX_PLAYER_COUNT` ≥ 20 (the engine's minimum;
  19 deterministic dummies fill the slots so the single real user
  can start the game).
- A frozen turn schedule (`0 0 1 1 *` — once a year) so the visible
  game state stays at turn 1 until you explicitly progress it.

## Network map

```
host                                            compose network "galaxy-local-dev-net"
  ┌────────────────────────────────┐              ┌──────────────────────────────┐
  │ browser    localhost:5173      │── pnpm dev (Vite, host) ──┐                  │
  │           ↳ /api/*  proxied ───┼──────────────────────────▶│ gateway:8080     │
  │           ↳ /galaxy.gateway... ┼──────────────────────────▶│                  │
  │ browser    localhost:8025      │─────────────────────────▶│ mailpit:8025      │
  │ psql       localhost:5433      │─────────────────────────▶│ postgres:5432     │
  │ redis-cli  localhost:6380      │─────────────────────────▶│ redis:6379        │
  └────────────────────────────────┘              │  ↳ backend:8080  (HTTP)        │
                                                  │  ↳ backend:8081  (gRPC push)   │
                                                  │  ↳ mailpit:1025  (SMTP in)     │
                                                  └────────────────────────────────┘
```

Vite's dev server proxies `/api` and `/galaxy.gateway.v1.EdgeGateway`
to the gateway, so every browser request stays same-origin (no CORS
preflight). The gateway is therefore reachable only through Vite at
<http://localhost:5173>, not at <http://localhost:8080> from the
browser tab. Direct curl/wget against <http://localhost:8080> still
works for diagnostic probes — only the browser-side requests are
proxied.

Mailpit (8025), postgres (5433), and redis (6380) remain directly
reachable for diagnostics (`make psql`, `redis-cli -h localhost -p
6380 -a galaxy-dev`).

To point the proxy at a non-local gateway, run
`VITE_DEV_PROXY_TARGET=http://gateway.host:8080 pnpm -C ui/frontend dev`
— no compose changes needed.

## Refreshing after Go-side changes

`make up` reuses any pre-built images and, by default, only rebuilds
the engine image (`build-engine`) when the tag is missing. Touching
backend or gateway code (handlers, routes, transcoders, model
constants) **does not** trigger a rebuild on its own — the next
`docker compose up -d` will reattach to the stale image and the
new behaviour silently disappears. After any change under
`backend/`, `gateway/`, `pkg/`, or the FBS schemas, force a
rebuild:

```sh
make -C tools/local-dev rebuild
```

`rebuild` runs `compose build --no-cache backend gateway` followed
by `up -d --wait`, so the next request through the stack hits the
new code. Engine code lives in a separate image — touch the engine
and run `make stop-engines` plus `docker rmi galaxy-engine:local-dev`
before `make up` (or `make build-engine`) so per-game containers
respawn from the freshly built layers.

## Make targets

```text
make up             Bring up the stack (build engine + compose images if needed) and wait for health
make rebuild        Rebuild the backend / gateway images (ignores cache)
make build-engine   Build galaxy-engine:local-dev from game/Dockerfile (no-op if image already present)
make down           Stop containers, keep volumes
make clean          Stop and wipe volumes (postgres + game-state)
make logs           Tail every service's logs
make logs-backend   Tail backend only
make logs-gateway   Tail gateway only
make logs-mail      Tail mailpit only
make psql           Open a psql shell as galaxy@galaxy_backend
make status         docker compose ps
```

## Files

- `docker-compose.yml` — five services: postgres, redis, mailpit,
  backend, gateway, plus shared network and volumes.
- `backend.Dockerfile`, `gateway.Dockerfile` — local-dev runtime
  images built on alpine (so `wget` is available for the compose
  healthchecks). The build stage mirrors `backend/Dockerfile` and
  `gateway/Dockerfile` exactly.
- `Makefile` — wrapper over `docker compose` that keeps the muscle
  memory close to `tools/local-ci/`'s Makefile.
- `.env` — committed defaults for the compose `${VAR:-}`
  expansions. Edit per-developer or override via your shell.
- `keys/gateway-response.pem`, `keys/gateway-response.pub` — dev-only
  Ed25519 keypair used by the gateway for response signing. Pairs
  with the `VITE_GATEWAY_RESPONSE_PUBLIC_KEY` value in
  `ui/frontend/.env.development`. See `keys/README.md` before
  rotating.
- `keys/regenerate.go` — one-shot Go helper that regenerates the
  pair and prints the new base64 public key.

## Troubleshooting

- **Lobby shows "no games yet" after `make clean && make up`** —
  the browser still holds a keypair + device session bound to the
  user_id from the previous DB. The new user has the same email
  (`dev@local.test`) but a fresh user_id, so the old keypair
  authenticates against a session row that no longer exists or
  points at the wrong account. Open the page in an incognito
  window, or wipe site data for `localhost:5173` (DevTools →
  Application → Storage → Clear site data) and log in again.
- **`make down` leaves a `galaxy-game-…` container behind** — fixed
  in this Makefile: `make down` and `make clean` now stop spawned
  engine containers via the `galaxy.backend=1` label. To stop them by
    hand without touching
  the rest of the stack, `make stop-engines`.
- **Engine container exits with `bind source path does not exist:
  /tmp/galaxy-game-state/<uuid>` after a host reboot** — macOS clears
  `/private/tmp` on reboot, so the per-game state directory the
  long-lived engine container bind-mounts is gone and Docker refuses
  to restart it under `restart: unless-stopped`. `make up` auto-heals
  this in one cycle: `prune-broken-engines` (runs as part of `up`)
  removes every engine container that is not in `running` /
  `restarting` state, the backend's pre-bootstrap reconciler tick
  cascades the orphan runtime row to `removed`, the lobby cancels
  the matching sandbox game, and the dev-sandbox bootstrap purges
  the cancelled tile and provisions a fresh sandbox with a brand
  new state directory. To run the cleanup by hand without restarting
  the rest of the stack, `make prune-broken-engines`.

  The cycle relies on the backend image carrying the pre-bootstrap
  reconciler tick (`backend/cmd/backend/main.go`). `make up` reuses
  the cached image, so after pulling this commit the first time you
  must `make rebuild` once to bake the fix in. Future `make up`
  cycles will heal in one shot.

  If after the heal cycle the lobby still shows only a `cancelled`
  sandbox tile and no running game, the running backend image
  predates the pre-bootstrap reconciler tick — the periodic ticker
  cancels the orphan after bootstrap has already returned, leaving
  the lobby in the half-baked state. `make rebuild` recreates the
  image and then `make up` lands a fresh sandbox.
- **`make up` reports a build error mentioning `pkg/cronutil`** —
  upstream module list drifted; copy any new `pkg/<name>/` line into
  the local-dev `backend.Dockerfile` / `gateway.Dockerfile` to match
  `backend/Dockerfile` / `gateway/Dockerfile`.
- **Gateway exits at boot with "redis: …"** — the redis container is
  still bootstrapping. `make up --wait` waits for healthchecks; if
  it times out, increase `start_period` in the gateway service or
  inspect `make logs-redis`.
- **Login form rejects every code** — confirm
  `BACKEND_AUTH_DEV_FIXED_CODE` is set in `tools/local-dev/.env` and
  the backend has been recreated since the last edit
  (`docker compose up -d backend`). Real Mailpit codes work
  regardless.
- **UI talks to old gateway**: Vite caches `import.meta.env` at boot.
  Restart `pnpm dev` after editing
  `ui/frontend/.env.development.local`.
- **Port 8080 already in use** (or any other host-port in the
  stack — postgres `5433`, redis `6380`, mailpit `8025`, gateway
  REST `8080`, gateway gRPC `9090`) — each host-port mapping in
  `docker-compose.yml` is parameterised through
  `LOCAL_DEV_*_PORT` with the listed values as defaults. Set a
  non-conflicting value either by uncommenting / editing the entry
  in `tools/local-dev/.env`, by exporting the variable in your
  shell, or by dropping a local override into a
  `tools/local-dev/docker-compose.override.yml` (compose
  auto-merges that file and it stays untracked by git). When
  moving the gateway REST port off `8080`, also point the Vite dev
  server at the new host port via
  `VITE_DEV_PROXY_TARGET=http://localhost:<port>` in
  `ui/frontend/.env.development.local` (or exported per
  `pnpm dev` invocation).

## Relationship to other infrastructure

- `tools/local-ci/` — Gitea + Actions runner, replays
  `.gitea/workflows/*` against a pushed branch. Different stack,
  different purpose; coexists with local-dev on the same machine.
- `integration/testenv/` — testcontainers harness used by
  `make -C integration integration`. Uses the same images
  (`backend/Dockerfile`, `gateway/Dockerfile`) at production
  defaults; do not confuse with this local-dev stack, which carries
  alpine-runtime images for ergonomics and the dev-mode auth
  override.