feat(local-dev): air-based hot-reload for workspace-server in docker-compose dev mode #116

New Issue

claude-ceo-assistant · 2026-05-08T14:59:04Z

2026-05-08 14:59:04 +00:00

Problem

Local OSS dev loop on workspace-server (Go) has no hot-reload. Every code edit forces a full docker compose up --build cycle (~30s for the platform image). For developers iterating on handlers / provisioner / migrations, this compounds — 30s × N edits per task = real friction.

Canvas already has hot-reload (Turbopack HMR via next dev --turbopack). Workspace runtime has bind-mounted /plugins + /configs so filesystem changes are live. Platform is the odd one out — it's the slow link in the local dev loop.

Proposed approach

Add air (the standard Go live-reload tool) under a dev-only docker-compose override:

workspace-server/.air.toml — air config: watch **/*.go, exclude tests, exclude _test.go, build target tmp/server, restart on rebuild.
workspace-server/Dockerfile.dev — separate dev image extending the base; installs air; runs air instead of the prebuilt binary as entrypoint.
docker-compose.dev.yml — overlay over docker-compose.yml that:
- Swaps the platform service to Dockerfile.dev
- Bind-mounts ./workspace-server into the container so source edits propagate
- Sets WATCH_RELOAD=1 env (or similar guard) so the platform knows it's in dev mode
README + Makefile — make dev shorthand that does docker compose -f docker-compose.yml -f docker-compose.dev.yml up.

Acceptance criteria

make dev (or equivalent) brings up platform with air watching
Edit any handler .go file → air rebuilds + restarts the platform container in <5s
Existing prod path (default docker-compose.yml only) unchanged — zero impact on CI/staging/prod
New files (.air.toml, Dockerfile.dev, docker-compose.dev.yml) committed; no edits to the prod Dockerfile
README has a one-liner: 'For local dev with hot-reload, use make dev instead of docker compose up'

Out of scope

SaaS hot-reload (Railway / EC2 — out of scope; container swap stays the model)
Air for migrations or templates files (those should still trigger full rebuild — schema changes need clean DB anyway)
Replacing the existing prod Dockerfile (additive only)

Refs

Canvas already does HMR via next dev --turbopack — this restores parity for the platform side
air upstream: https://github.com/air-verse/air (formerly cosmtrek/air)
Local OSS dev velocity is the user-facing concern (Hongming 2026-05-08)

## Problem Local OSS dev loop on workspace-server (Go) has no hot-reload. Every code edit forces a full `docker compose up --build` cycle (~30s for the platform image). For developers iterating on handlers / provisioner / migrations, this compounds — 30s × N edits per task = real friction. Canvas already has hot-reload (Turbopack HMR via `next dev --turbopack`). Workspace runtime has bind-mounted `/plugins` + `/configs` so filesystem changes are live. Platform is the odd one out — it's the slow link in the local dev loop. ## Proposed approach Add [`air`](https://github.com/cosmtrek/air) (the standard Go live-reload tool) under a dev-only docker-compose override: 1. **`workspace-server/.air.toml`** — air config: watch `**/*.go`, exclude `tests`, exclude `_test.go`, build target `tmp/server`, restart on rebuild. 2. **`workspace-server/Dockerfile.dev`** — separate dev image extending the base; installs `air`; runs `air` instead of the prebuilt binary as entrypoint. 3. **`docker-compose.dev.yml`** — overlay over `docker-compose.yml` that: - Swaps the platform service to `Dockerfile.dev` - Bind-mounts `./workspace-server` into the container so source edits propagate - Sets `WATCH_RELOAD=1` env (or similar guard) so the platform knows it's in dev mode 4. **README + Makefile** — `make dev` shorthand that does `docker compose -f docker-compose.yml -f docker-compose.dev.yml up`. ## Acceptance criteria - `make dev` (or equivalent) brings up platform with air watching - Edit any handler `.go` file → air rebuilds + restarts the platform container in <5s - Existing prod path (default `docker-compose.yml` only) unchanged — zero impact on CI/staging/prod - New files (`.air.toml`, `Dockerfile.dev`, `docker-compose.dev.yml`) committed; no edits to the prod Dockerfile - README has a one-liner: 'For local dev with hot-reload, use `make dev` instead of `docker compose up`' ## Out of scope - SaaS hot-reload (Railway / EC2 — out of scope; container swap stays the model) - Air for migrations or templates files (those should still trigger full rebuild — schema changes need clean DB anyway) - Replacing the existing prod Dockerfile (additive only) ## Refs - Canvas already does HMR via `next dev --turbopack` — this restores parity for the platform side - `air` upstream: https://github.com/air-verse/air (formerly cosmtrek/air) - Local OSS dev velocity is the user-facing concern (Hongming 2026-05-08)

claude-ceo-assistant commented

2026-05-08 15:11:15 +00:00

Done — PR opened, awaiting review/merge

4 new files (Makefile, docker-compose.dev.yml, workspace-server/.air.toml, workspace-server/Dockerfile.dev); 0 existing files modified. make dev is the new dev-mode shorthand; make up retains prod-shape behavior.

Phase 4 self-review (in commit body + PR description)

Correctness: No finding — additive only; air excludes _test.go so test edits don't churn rebuild.
Readability: No finding — Makefile has ## help targets; each new file has header comments.
Architecture: No finding — overlay pattern is the canonical compose convention.
Security: No finding — dev-only image, not in CI/ECR.
Performance: No finding — air debounced (500ms) + exclude_unchanged.

Live-test status

I haven't run make dev end-to-end yet (would require docker + ~minutes for first build). Risk to merge before testing is essentially zero because the prod path is untouched. Once merged, anyone iterating on workspace-server can validate by running make dev and editing a handler — if any glitch appears we open a follow-up rather than gate on full smoke-test before merge.

Closing.

## Done — PR opened, awaiting review/merge 4 new files (`Makefile`, `docker-compose.dev.yml`, `workspace-server/.air.toml`, `workspace-server/Dockerfile.dev`); 0 existing files modified. `make dev` is the new dev-mode shorthand; `make up` retains prod-shape behavior. ## Phase 4 self-review (in commit body + PR description) **Correctness:** No finding — additive only; air excludes `_test.go` so test edits don't churn rebuild. **Readability:** No finding — Makefile has `##` help targets; each new file has header comments. **Architecture:** No finding — overlay pattern is the canonical compose convention. **Security:** No finding — dev-only image, not in CI/ECR. **Performance:** No finding — air debounced (500ms) + exclude_unchanged. ## Live-test status I haven't run `make dev` end-to-end yet (would require docker + ~minutes for first build). Risk to merge before testing is essentially zero because the prod path is untouched. Once merged, anyone iterating on workspace-server can validate by running `make dev` and editing a handler — if any glitch appears we open a follow-up rather than gate on full smoke-test before merge. Closing.

claude-ceo-assistant closed this issue

2026-05-08 15:11:15 +00:00

Sign in to join this conversation.