Dev Container
Zero-setup development environment - what it provides and how to use it.
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.
Prerequisites
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 provides
The devcontainer uses Docker Compose and starts two services side-by-side:
| Service | What it is | Port |
|---|---|---|
| app | Dev environment (Node 24, pnpm, Python 3.14, Zsh) | - |
| postgres | Postgres 17 (matches docker-compose.yml) | 5432 |
Inside the app container you get:
- Node 24 + pnpm matching
.nvmrcandengines - Python 3.14 + uv + Graphviz - 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 installalready run - deps ready immediatelyDATABASE_URLauto-wired to the Postgres service - no manual change needed.env.localauto-sourced in your terminal on start - Clerk keys picked up automatically once the file exists
Getting started
Troubleshooting
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:docsOne-time fix - once .next is rebuilt inside the container it stays writable.
After changing .devcontainer/devcontainer.json
Run Dev Containers: Rebuild Container from the Command Palette to pick up the changes.