Development Environment

Container-First Development

This project runs entirely in a Podman container. The host machine only needs Podman installed - all other tools (Bun, dependencies, build tools) live inside the container.

Host Machine          Container (v10r)
┌─────────────┐      ┌──────────────────────┐
│  Podman     │ ───► │  Bun runtime         │
│  (only)     │      │  node_modules        │
│             │      │  Build tools         │
└─────────────┘      └──────────────────────┘

Adding Dependencies

Never run bun add on the host. The workflow is:

1. Edit package.json — add the package to dependencies or devDependencies
2. Restart the container — the container runs bun install automatically on startup

Why No Manual Installation?

Container Commands

Ports

Volume Mounts

Project files are bind-mounted at /app for hot reload. node_modules uses a named volume, which means:

• Dependencies don't sync back to host
• Faster I/O (no filesystem translation)
• No conflicts with host's Node version

Cold-start expectations

First podman compose up on a fresh container takes ~30-40 s to reach ready in Xms in the Vite logs. This is the established baseline, not a regression.

After ready, HMR is fast. Subsequent restarts on the same container are similar — the cost is per-process, not cached.

Measuring

bun run perf:cold-start

Drives podman compose down && up, parses Vite logs, and reports install_ms, vite_ready_ms, first_ssr_ttfb_ms, ssr_reload_count. Thresholds: warn > 15 s, fail > 25 s (current baseline ~36 s is set as the working ceiling for this stack until Vite 8 / Rolldown lands).

Running Commands Inside Container

Use podman exec -it v10r <command> for one-off commands (e.g., bun run check, bun run build), or open a shell with podman exec -it v10r sh.

Troubleshooting