Development Environment

Two environments share one authority, GitHub ApeDevil/v10r: every change is a feature branch pushed there, and main moves only by a ship (shipping.md). Neither environment reaches the other — a cloud session never assumes Stas's machine exists.

The cloud environment needs only the Trusted network defaults (the npm registry). Paraglide's inlang plugins are devDependencies loaded from node_modules, not fetched from a CDN (i18n.md).

What runs where

A check that could not run is reported as not run, never as passed.

The local container

The local environment runs entirely in a Podman container. The host only needs Podman — all other tools (Bun, Node 22, dependencies, build tools) live inside the container. Which engine runs what: docs/stack/core/bun.md.

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

The sections below describe the local container.

Adding Dependencies

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

1. Add inside the container — podman exec v10r bun add <pkg> (or bun add -D). This updates package.json and bun.lock on the bind mount and installs into the volume in one step.
2. Restart the container — podman compose restart. Startup runs bun install --frozen-lockfile, so a passing restart proves manifest and lockfile agree.

Editing package.json by hand without regenerating bun.lock fails that frozen-lockfile startup guard — the fix is reconciling the lockfile in the container, never dropping the flag.

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. Baseline and breakdown were measured on Vite 7; the move to Vite 8 (Rolldown, which also replaces esbuild in the dep prebundle) has not been re-measured.

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. The 15 s warn / 25 s fail thresholds in budgets.json are targets the current stack does not meet — the last measured baseline is ~36 s (Vite 7), so a run "failing" the target is the expected, honest state until a run on Vite 8 shows otherwise. The probe is a manual trend check, not part of validate.

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