# Om Dev Container Maintenance

> Maintain the VS Code Dev Container setup for Open Mercato. MUST use for ANY change to `.devcontainer/` files. Also use when the container fails to build/start, services inside misbehave, or "works locally but not in dev container". Triggers on "dev container", "devcontainer", ".devcontainer".

- Skill: `open-mercato/om-dev-container-maintenance` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add open-mercato/om-dev-container-maintenance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/open-mercato/om-dev-container-maintenance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: open-mercato (https://skillmd.com/u/open-mercato)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/open-mercato/om-dev-container-maintenance

---


# 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:

1. Make the minimal change to the affected file(s) per the file map above
2. New `.env.example` keys needing container values: add `sed` rules to `setup-env.sh` with verification
3. New service: add to `.devcontainer/docker-compose.yml` with health check + forward port in `devcontainer.json`
4. Node.js or Yarn version change: update `.devcontainer/Dockerfile` (`FROM` line and `corepack prepare`)
5. **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.md` rules

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
```