open-mercato Dev Container Maintenance
Maintain .devcontainer/ so it stays in sync with the project's regular development requirements.
Spec & Documentation
- Spec:
.ai/specs/implemented/SPEC-050-2026-02-26-dev-container-setup.md - User docs:
.devcontainer/README.md
Dev Container File Map
| File | Purpose | When to modify |
|---|---|---|
.devcontainer/devcontainer.json |
VS Code integration: lifecycle hooks, ports, extensions, env forwarding | New ports, extensions, env vars to forward |
.devcontainer/Dockerfile |
Workspace image: Node.js, system packages, Python/Ruby/Homebrew, Claude CLI, Yarn | Node.js version bump, new system dep (apt-get install) |
.devcontainer/docker-compose.yml |
Services + static volumes + health checks | New service, version bump, new static volume |
.devcontainer/docker-compose.volumes.yml |
Auto-generated dist/ volumes |
Never edit — regenerated by generate-compose-volumes.sh |
.devcontainer/docker-compose.local.yml |
Personal overrides (gitignored) — extra bind mounts, env vars, services | Developer edits for local needs; auto-created if missing |
.devcontainer/scripts/setup-env.sh |
.env generation with hostname rewrites |
New .env.example keys needing container-specific values |
.devcontainer/scripts/post-create.sh |
One-time bootstrap (install, build, generate, db init) | New build steps, changed init sequence |
.devcontainer/scripts/post-start.sh |
Per-start sync (install, migrate) | New per-start maintenance steps |
.devcontainer/scripts/generate-compose-volumes.sh |
Scans packages/*/, writes docker-compose.volumes.yml |
Only if volume naming convention changes |
Workflow
1. Audit (compare regular setup vs dev container)
Read and follow the checklist in references/audit-checklist.md. It covers version alignment, service parity, env var sync, package coverage, system deps, port forwarding, and build sequence.
2. Diagnose (when something is broken)
Read the guide in references/troubleshooting.md. Covers container build failures, health check failures, postCreateCommand step failures, env var mismatches, volume permissions, and DB migration conflicts.
3. Fix (apply changes)
After identifying drift or bugs:
- Make the minimal change to the affected file(s) per the file map above
- New
.env.examplekeys needing container values: addsedrules tosetup-env.shwith verification - New service: add to
.devcontainer/docker-compose.ymlwith health check + forward port indevcontainer.json - Node.js or Yarn version change: update
.devcontainer/Dockerfile(FROMline andcorepack prepare) - Update documentation (see step 4 below) — this is mandatory for every change
4. Update documentation (mandatory after every change)
Every dev container change MUST be reflected in both documentation files. Skipping this causes drift between implementation and docs.
.devcontainer/README.md — user-facing docs
Update the relevant section(s):
- Services table — when adding/removing/upgrading a service
- Named Volumes table — when adding/removing volumes
- Lifecycle Hooks section — when changing bootstrap steps
- Environment Variables section — when changing env var handling
- Key Design Decisions table — when making a new architectural choice
- Common Tasks table — when adding new developer commands
- Updating the Dev Container table — when the maintenance protocol itself changes
- Troubleshooting table — when discovering new failure modes or fixes
.ai/specs/SPEC-050-2026-02-26-dev-container-setup.md — spec
Use the om-spec-writing skill (/om-spec-writing) to update the spec properly. At minimum:
- Changelog section: Add a dated entry with a concise summary of what changed and why
- Architecture / Volume Strategy / Configuration tables: Update if services, volumes, ports, or versions changed
- Design Decisions table: Add a row if a new architectural decision was made
- Risk Register: Add/update entries if the change introduces or mitigates a risk
- Service Versions table: Update when any image tag changes
- Compliance Matrix: Re-verify if the change touches areas covered by root
AGENTS.mdrules
The spec-writing skill ensures the update follows project conventions (TLDR, structured sections, compliance gate).
Key Comparison Points
Version sources (regular setup) vs targets (dev container):
| Tool | Regular source | Dev container target |
|---|---|---|
| Node.js | .nvmrc + package.json engines |
.devcontainer/Dockerfile FROM node:<ver>-slim |
| Yarn | package.json "packageManager" |
.devcontainer/Dockerfile corepack prepare yarn@<ver> |
| PostgreSQL | docker-compose.yml image tag |
.devcontainer/docker-compose.yml postgres image |
| Redis | docker-compose.yml image tag |
.devcontainer/docker-compose.yml redis image |
| Meilisearch | docker-compose.yml image tag |
.devcontainer/docker-compose.yml meilisearch image |
Environment variable flow:
apps/mercato/.env.example
→ .devcontainer/scripts/setup-env.sh (sed rewrites)
→ apps/mercato/.env (generated, overwritten on rebuild)
→ apps/mercato/.env.local (manual overrides, never touched)
Build sequence equivalence:
Regular: yarn install → yarn build:packages → yarn generate → yarn build:packages → yarn initialize
Container: post-create.sh steps [0]-[7] mirror this exact sequence