wk-devcontainer

Files (14)

• README.md
• SKILL.md
• 2026-05-12_apt-package-audit.md · references/
• 2026-05-12_host-config-mounts-and-autostart.md · references/
• 2026-05-12_mise-profiles-for-container-tools.md · references/
• 2026-08-05_secret-safe-startup-output.md · references/
• 2026-08-17_container-env-defeats-conditional-default.md · references/
• 2026-08-17_sibling-worktree-port-conflict.md · references/
• 2026-10-14_bake-fs-entitlement-docker.md · references/
• 2026-10-14_bake-fs-entitlement.md · references/
• 2026-10-19_plain-compose-fallback-exec-labels.md · references/
• 2026-10-21_bake-fs-entitlement-escalation.md · references/
• config-templates.md · references/
• teardown-project-name.md · references/

SKILL.md (first lines)

# wk-devcontainer

Create or debug a `.devcontainer/` setup for a mise-managed Rails app.

## When to Use

- Setting up a new devcontainer from scratch
- Debugging broken mise tool resolution, Bundler cache, MySQL/Redis connectivity
- After `postCreateCommand` fails or tools are missing in the container

## Step 1: Audit the project first

**HARD RULE: Check CI compose before writing any config.** Project already
demonstrates the correct Docker override pattern.

```bash
cat .buildkite/docker/compose.yml   # authoritative for CONFIG__ overrides
cat config/database.yml             # which keys drive DB connection
cat .ruby-version                   # pin this exactly in mise.toml
grep -E "redis|sidekiq|elasticsearch" Gemfile | head -10  # extra services needed
```

- Read all four.
- CI compose → exact image versions, service names, `CONFIG__` keys. Copy them, don't guess.
- DB adapter in `Gemfile`: `trilogy` → no `libmysqlclient-dev` needed; `mysql2` → needs it.

## Steps 2-4: Write the config files

See [references/config-templates.md](references/config-templates.md) for
complete Dockerfile, docker-compose.yml, and devcontainer.json templates with
key decisions and HARD RULEs (no manual PATH/shim wiring, no COPY mise.toml,
no env var the app conditionally defaults).

**HARD RULE: Never stream `devcontainer up` output when Compose interpolates a
host credential** — some CLI versions print the resolved Compose model. Enumerate
host vars Compose references first; prefer file-backed secrets; else `umask 077`,
capture output to a temp file, show only an exact-value-redacted copy, delete the raw
capture on exit, and prove it with a canary. Direct startup with a forwarded
credential is a blocker.

**Mise profiles (optional):** keep host `mise.toml` lean; add container-only
tools via `mise.devcontainer.toml` + `MISE_PROFILE: devcontainer` in compose.

## Step 5: Update mise.toml

Add to the project's `mise.toml`:

```toml
[settings]
auto_install = true   # install tools on container start, no COPY+install at build time

[tools]
ruby = "3.4.7"   # must match .ruby-version exactly
```

Ruby version must match `.ruby-version` exactly → mismatch causes Bundler
lockfile platform conflicts.

## Teardown / rebuild the stack

**HARD RULE: pin the Compose project name in every teardown/rebuild command.**
`devcontainer up` and VS Code "Reopen in Container" create the stack under
project `<workspace-folder-basename>_devcontainer`, **lowercased** (Compose rejects uppercase
project names, so an unlowered `-p` fails on a mixed-case worktree directory). A bare `docker compose -f
.devcontainer/docker-compose.yml down` defaults the project to the compose
file's parent-directory basename (`devcontainer`) → targets an empty project and
silently leaves the real stack running.

```bash
proj="$(basename "$PWD" | tr '[:upper:]' '[:lower:]')_devcontainer"
docker compose -p "$proj" ps                                          # verify target before acting
docker compose -p "$proj" -f .devcontainer/docker-compose.yml down    # stop (add -v to drop volumes)
docker compose -p "$proj" -f .devcontainer/docker-compose.yml build   # rebuild
```

### Host port already bound by a sibling worktree

Two worktrees of one project publish the same host port, so the second stack
cannot start. A published port exists only for **host** access —
container-to-container traffic uses the Compose network — so a task that merely
needs to run inside the project environment does not need one.

Attach a throwaway container to the running stack's network and named volumes,
publishing nothing:

```bash
proj="$(basename "$PWD" | tr '[:upper:]' '[:lower:]')_devcontainer"
docker network ls; docker volume ls          # resolve real names before running
docker run --rm -it \
  --network "${proj}_default" \
  -v "${proj}_bundle:/usr/local/bundle" \
  -v "$PWD:/workspace" -w /workspace \
  <app-image> bash
```

- Read the network and volume names off the running stack; the `_default` suffix
  and volume prefixes follow the **pinned project name**, not the compose file's
  directory.
- Never resolve this by editing the committed port mapping — that breaks the other
  worktree and lands an unrelated diff.

## `devcontainer up` fails at the image build

**HARD RULE: surface the real build error before changing config.** The CLI reports only
"An error occurred building the Docker Compose images"; never guess from that line.

- Rerun with `devcontainer up --log-level trace` (capture under the credential rule above) and grep the capture for
  `privileges` / `error`, or rerun the generated compose overlay command from the trace by hand.
- **Important:** `additional privileges requested: pass "--allow=fs.read=<tmp>/Dockerfile-with-features"` → Compose
  5.x builds via buildx bake, which gates reads outside the build context; the CLI writes its features Dockerfile to a
  temp dir. `COMPOSE_BAKE=false` does not help — never try it first. Set `BUILDX_BAKE_ENTITLEMENTS_FS=0` (buildx's
  documented opt-out) in the CLI's own process env and retry:
  `BUILDX_BAKE_ENTITLEMENTS_FS=0 devcontainer up --workspace-folder .` (`devcontainer.json` env keys reach the
  container, never the host-side build).
- **Plain compose is a last resort, never a substitute.** `devcontainer exec` resolves its container by the
  `devcontainer.local_folder` / `devcontainer.config_file` labels only `devcontainer up` sets, so a stack started by
  plain compose is invisible to it — and to every git hook or script that shells in through it. Grep hooks and scripts
  for `devcontainer exec` first; any hit → fix the build, never fall back.
- Still failing, no features declared (the overlay adds nothing), and nothing relies on `devcontainer exec` → bring

From whizzzkid/skills, MIT.

More from whizzzkid/skills