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

[cqnykamp]

A working dev container, a reorganization of the setup instructions around it, and a handful of follow-up fixes from actually using it in a codespace.

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.

scripts/dc — the container as a local toolchain

The point of option 2 is "only Docker on the host", but the devcontainer CLI needs Node. scripts/dc drives docker-compose.yml directly instead, so the whole loop is:

./scripts/dc dev      # builds + seeds on first run, then npm run dev; prints the auto-login link
./scripts/dc shell    # a terminal inside
./scripts/dc claude   # Claude Code inside (sign in once; kept in a volume)
./scripts/dc <cmd>    # anything else, run inside

plus up, down, rebuild, reset, status. It reads the checkout's ports from apps/api/.env (worktrees get their offset automatically), runs post-create.sh once per container via a marker file, and uses the same <folder>_devcontainer project name as VS Code and the CLI, so it attaches to a container started by either. Files are edited on the host as usual; the docs spell out the one gap (a host editor cannot see node_modules for type hints) and point at Reopen in Container for that.

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.

Follow-ups from using it

• Codespaces verified end to end (see the original caveat below, now resolved). Using it turned up four fixes:
  • s3mock is service_started, not service_healthy: the JVM can take minutes to answer on a 2-core machine, and gating container creation on it cost a failed codespace build.
  • The sshd feature is added so gh codespace ssh|logs|cp work; the slim Node base image has no SSH server.
  • Port forwarding opens the app (8000), not the API. The API and blog ports are labelled but silent.
  • In a codespace the browser is on *.app.github.dev, so post-create.sh writes apps/web/.env.local (blog links back to the app) and points APP_URL in apps/api/.env at the forwarded origin (magic-link sign-in and the npm run dev auto-login banner). The banner now builds its URL from APP_URL via worktree-env.js rather than hardcoding localhost.
• Claude Code is installed in the image, with its config in a named volume so a login survives rebuilds, and ANTHROPIC_API_KEY passed through from the host or a Codespaces secret.

VS Code: one click to a running app

Opening the folder recommends the Dev Containers extension, so the Reopen in Container prompt appears. waitFor: postCreateCommand keeps VS Code from connecting until the database is seeded, and a postAttachCommand then runs .devcontainer/start-dev.sh, which starts npm run dev in a terminal unless the API port is already answering (so a window reload does not start a second copy). The same script is the default build task (Ctrl/Cmd+Shift+B) and what dc dev runs. The Claude Code extension is in the container's extension list.

Git and GitHub from inside

An agent in the container can commit, push, and open PRs. The image installs gh (config in a volume); post-create.sh marks directories safe for git, sets gh as the credential helper, and rewrites SSH remotes to HTTPS. scripts/dc passes the host's gh auth token as GH_TOKEN per command, copies the host git identity on up, and on a linked worktree mounts the main repository's git directory so git can find it. VS Code gets GH_TOKEN from the host environment; Codespaces has its own token. Verified from inside the container on a linked worktree: commit with the host identity (husky hook ran), gh pr list, credential fill, and a real git push of the commit that added this.

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

Each path now runs from git clone to a signed-in browser without leaving the page: a Signing in section explains the auto-login link npm run dev prints (and that magic links land in the API log in development), the container path says how to get a shell and how long the first build takes, and a short Troubleshooting list covers the failures a newcomer actually hits.

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. Since verified in a live codespace: it builds, npm run dev serves, and the app and the blog's links work from the forwarded host. The fixes that took are listed above. Two things have not been exercised end to end yet: the sign-in-link fix (APP_URL) in a fresh codespace, and the VS Code attach flow (waitFor + postAttachCommand), which is configured per the spec and whose script is verified in the container but has not been driven from VS Code itself.

The e2e-tests (group2) failure is the pre-existing race in addToCompoundActivity.cy.ts (the problem-set title is read back as "Untitled Problem Set" before the rename lands). It fails the same way on other branches and nothing here touches that code.

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