Local Development Runbook

Prerequisites

• Docker Desktop / Engine with Compose plugin.
• Ports 4321 (marketing) and 4322 (docs) available on the host.
• No secrets stored locally; this workflow depends solely on repository content.

Workflow

1. Start container

   docker compose up -d dev

2. Install dependencies (once per update)

   docker compose run --rm -T dev bash -lc "pnpm install"

3. Serve marketing site

   docker compose exec dev bash -lc "pnpm dev:site"
   # http://localhost:4321

4. Serve internal docs

   docker compose exec dev bash -lc "pnpm dev:docs"
   # http://localhost:4322

5. Run builds when validating changes

   docker compose run --rm -T dev bash -lc "pnpm build:site"
   docker compose run --rm -T dev bash -lc "pnpm build:docs"

Troubleshooting

• Ports busy — Stop existing containers (docker compose down) or free conflicting services.
• Missing pnpm/corepack — Always invoke commands through Docker; the image already contains pnpm.
• File permission issues — Ensure repo is owned by the host user; Docker runs as node user inside the container.

Shutdown

docker compose down

Run this after finishing work or before switching branches to prevent stale mount state.