Dev Container

The repo ships a Dev Container for a zero-setup environment. Clone the repo, open it in VS Code or Cursor, and everything is ready - no manual Node, pnpm, Python, or database installation required. Database migrations are applied automatically each time the container starts.

PrerequisitesCopy Anchor Link

You need a Docker-compatible runtime. Either works:

• Docker Desktop - the standard option
• Rancher Desktop - free alternative; use the dockerd (moby) container engine

Make sure whichever you choose is running before opening the container.

What it providesCopy Anchor Link

The devcontainer is a single container built from .devcontainer/Dockerfile - no Docker Compose. Postgres 17 runs inside it, started automatically each time the container starts. Keeping it to one container avoids path problems some Docker runtimes (notably Rancher Desktop) have with Compose-based devcontainers.

Inside the container you get:

• Postgres 17 on localhost:5432 (database app, user and password postgres)
• Node 24 + pnpm matching .nvmrc and engines
• uv + Graphviz, with Python 3.14 downloaded by uv - ready to regenerate the architecture diagram
• Zsh + Oh My Zsh with autosuggestions, syntax highlighting, and history search
• VS Code extensions pre-installed: ESLint, Prettier, Tailwind IntelliSense, Playwright, Vitest, GitLens, Python/Ruff, Material Icon Theme, Error Lens
• pnpm install already run - deps ready immediately
• DATABASE_URL auto-wired to the in-container Postgres - no manual change needed
• .env.local auto-sourced in your terminal on start - Clerk keys picked up automatically once the file exists

Getting startedCopy Anchor Link

Leaving the container

To go back to working on your machine, open the Command Palette (Cmd+Shift+P) → Dev Containers: Reopen Folder Locally.

After changing .devcontainer/devcontainer.json

Run Dev Containers: Rebuild Container from the Command Palette to pick up the changes.

TroubleshootingCopy Anchor Link

Docs site Turbopack errors / read-only filesystem

If pnpm dev:docs spams Read-only file system errors or Turbopack loops, it means docs/.next/ was built on the host machine and mounted into the container where the vscode user can't write to it. Fix:

rm -rf docs/.next && pnpm dev:docs

One-time fix - once .next is rebuilt inside the container it stays writable.