feat(dev): self-contained dev container, and setup docs to match

[cqnykamp]

Two commits: a working dev container, and a reorganization of the setup instructions around it.

The dev container

The existing .devcontainer/ was left over from the PHP/Apache era of DoenetTools — it built apache and php services and mounted paths like ./public/api and ./docker/mysql that no longer exist, so it could not start at all. Replaced with one that matches the current monorepo.

Everything needed to run and test the repo lives in the container; the only host requirement is Docker.

Service	Purpose
dev	Node 24.15.0 (matching .nvmrc), Chrome + Cypress runtime libs, the workspace
mysql	MySQL 8.0, migrated and seeded by the post-create step
s3mock	adobe/s3mock, so image upload works — the same image CI uses

Works with Codespaces, VS Code, the devcontainer CLI, or plain docker compose.

Notable decisions

The app is browsable without an editor. Vite and Astro bind to 127.0.0.1, which Docker's published ports cannot reach, so both configs now read an optional DEV_SERVER_HOST. It is unset on a normal checkout — host-based development stays on localhost exactly as before — and the container sets it to 0.0.0.0. Ports are published on the host's loopback only.

apps/api/.env is never rewritten. The database and media addresses are supplied as environment variables in the compose file. Both dotenv and the Prisma CLI leave already-set variables alone, so the container's values win while the checkout's .env — shared with the host through the bind mount — is left alone. That lets the same checkout be used on the host and in the container. dev-preflight.js now resolves the database host the same way instead of assuming 127.0.0.1; behaviour on the host is unchanged, since DATABASE_HOST is localhost there.

node_modules are named volumes, so the container's Linux-native installs never collide with the host's (which matters on macOS/arm64, given the platform-specific optionalDependencies in apps/api and apps/app). The list is limited to the workspaces npm actually populates, and initializeCommand pre-creates those mount points as the host user — Docker otherwise creates them as root, leaving directories in the checkout that a later host-side npm ci cannot write to.

The docs

Setup lived entirely in the README, offered one path, and pointed git clone at the old DoenetTools repository. Now split the conventional way — a short quick start in the README, detail in CONTRIBUTING.md, which GitHub also surfaces from issue and pull request pages — with the three environments presented easiest first:

1. GitHub Codespaces — a browser, one click
2. Dev container locally — Docker, one command
3. The toolchain on your machine — Node 24 + Docker, full control

CONTRIBUTING.md also gathers what a contributor needs past that first command: what runs on which port, how to run each test suite, the format/lint pass CI expects, and the fork and expand-migrate-contract conventions that were previously documented only in AGENTS.md. .devcontainer/README.md keeps only what is genuinely container-specific.

Verification

Run inside the container, on a fresh clone:

• npm test --workspace @doenet-tools/api — 408 passed, 30 files
• npm test --workspace @doenet-tools/shared — 7 passed
• Cypress e2e imageUpload.cy.ts — 2 passed, exercising browser → Vite → API → MySQL → s3mock
• Cypress component ChatConversation.cy.tsx — 3 passed
• npm run dev — api, app, and blog all serving; app and /blog reachable from a host browser
• format:check, lint:check, build — clean

The full setup path was verified twice end to end via devcontainer up on fresh clones, and every internal doc link and anchor was checked.

Note for reviewers

The Codespaces path is the one thing not verified end to end — launching a codespace bills someone's account, so it was reasoned about rather than run. The config uses no features Codespaces does not support, but the first person with quota should confirm it before we lean on that badge.

Only three suites were run as single specs rather than in full — enough to prove Chrome, the s3mock upload path, and both Cypress modes work in the container, without the full suite runtime. CI covers the rest.

On arm64 hosts Google ships no Chrome build, so Chromium is installed instead and Cypress needs -b chromium; the package scripts hardcode -b chrome. Documented rather than changed, since changing them would affect CI.

🤖 Generated with Claude Code