---
name: docker-container-management
description: Reusable Docker container workflow for build, test, and dev tasks in containerized repos
permalink: opencode-config/skills/docker-container-management/skill
---

# Docker Container Management

Load this skill when a repo uses Docker/docker-compose for builds, tests, or local dev, or when a task involves containerized workflows.

## Core Workflow

1. **Detect** — look for `Dockerfile`, `docker-compose.yml`/`compose.yml`, or `.devcontainer/` in the repo root.
2. **Prefer compose** — use `docker compose` (v2 CLI) over raw `docker run` when a compose file exists.
3. **Ephemeral containers** — default to `--rm` for one-off commands. Avoid leaving stopped containers behind.
4. **Named volumes over bind-mounts** for caches (e.g., package manager caches). Use bind-mounts only for source code.
5. **No host-path writes outside the repo** — all volume mounts must target paths inside the repo root or named volumes. This preserves `external_directory: deny`.

## Path and Volume Constraints

- Mount the repo root as the container workdir: `-v "$(pwd):/app" -w /app`.
- Never mount host paths outside the repository (e.g., `~/.ssh`, `/var/run/docker.sock`) unless the plan explicitly approves it with a stated reason.
- If root-owned artifacts appear after container runs, document cleanup steps (see `main/knowledge/worktree-cleanup-after-docker-owned-artifacts`).

## Agent Guidance

- **planner**: Use Docker during planning for context gathering and inspection (e.g., `docker compose config`, `docker ps`, `docker image ls`, `docker network ls`, checking container health or logs). Do not run builds, installs, tests, deployments, or any implementation-level commands — those belong to builder/tester/coder.
- **builder/coder**: Run builds and install steps inside containers. Prefer `docker compose run --rm <service> <cmd>` for one-off tasks.
- **tester**: Run test suites inside the same container environment used by CI. Capture container exit codes as verification evidence.
- **coder**: When writing Dockerfiles or compose files, keep layers minimal, pin base image tags, and use multi-stage builds when the final image ships.

## Red Flags

- `docker run` without `--rm` in automation scripts.
- Bind-mounting sensitive host paths (`/etc`, `~/.config`, `/var/run/docker.sock`).
- Building images without a `.dockerignore`.
- Using `latest` tag for base images in production Dockerfiles.