Skill: ivangdavila/docker (version 1.0.4)

--- name: Docker slug: docker version: 1.0.4 homepage: https://clawic.com/skills/docker description: "Docker containers, images, Compose stacks, networking, volumes, debugging, production hardening, and the commands that keep real environments stable. Use when (1) the task touches Docker, Dockerfiles, images, containers, or Compose; (2) build reliability, runtime behavior, logs, ports, volumes, or security matter; (3) the agent needs Docker guidance and should apply it by default." changelog: Simplified the skill name and kept the stateless activation guidance metadata: {"clawdbot":{"emoji":"🐳","requires":{"bins":["docker"]},"os":["linux","darwin","win32"]}} --- ## When to Use Use when the task involves Docker, Dockerfiles, container builds, Compose, image publishing, networking, volumes, logs, debugging, or production container operations. This skill is stateless and should be applied directly whenever Docker work appears. ## Quick Reference | Topic | File | |-------|------| | Essential commands | `commands.md` | | Dockerfile patterns | `images.md` | | Compose orchestration | `compose.md` | | Networking & volumes | `infrastructure.md` | | Security hardening | `security.md` | ## Core Rules ### 1. Pin Image Versions - `python:3.11.5-slim` not `python:latest` - Today's latest differs from tomorrow's — breaks immutable builds ### 2. Combine RUN Commands - `apt-get update && apt-get install -y pkg` in ONE layer - Separate layers = stale package cache weeks later ### 3. Non-Root by Default - Add `USER nonroot` in Dockerfile - Running as root fails security scans and platform policies ### 4. Set Resource Limits - `-m 512m` on every container - OOM killer strikes without warning otherwise ### 5. Configure Log Rotation - Default json-file driver has no size limit - One chatty container fills disk and crashes host ## Image Traps - Multi-stage builds: forgotten `--from=builder` copies from wrong stage silently - COPY before RUN invalidates cache on every file change — copy requirements first, install, then copy code - `ADD` extracts archives automatically — use `COPY` unless you need extraction - Build args visible in image history — never use for secrets ## Runtime Traps - `localhost` inside container is container's localhost — bind to `0.0.0.0` - Port already in use: previous container still stopping — wait or force remove - Exit code 137 = OOM killed, 139 = segfault — check with `docker inspect --format='{{.State.ExitCode}}'` - No shell in distroless images — `docker cp` files out or use debug sidecar ## Networking Traps - Container DNS only works on custom networks — default bridge can't resolve names - Published ports bind to `0.0.0.0` — use `127.0.0.1:5432:5432` for local-only - Zombie connections from killed containers — set health checks and restart policies ## Compose Traps - `depends_on` waits for container start, not service ready — use `condition: service_healthy` - `.env` file in wrong directory silently ignored — must be next to docker-compose.yml - Volume mounts overwrite container files — empty host dir = empty container dir - YAML anchors don't work across files — use multiple compose files instead ## Volume Traps - Anonymous volumes accumulate silently — use named volumes - Bind mounts have permission issues — container user must match host user - `docker system prune` doesn't remove named volumes — add `--volumes` flag - Stopped container data persists until container removed ## Resource Leaks - Dangling images grow unbounded — `docker image prune` regularly - Build cache grows forever — `docker builder prune` reclaims space - Stopped containers consume disk — `docker container prune` or `--rm` on run - Networks pile up from compose projects — `docker network prune` ## Secrets and Security - ENV and COPY bake secrets into layer history permanently — use secrets mount or runtime env - `--privileged` disables all security — almost never needed, find specific capability instead - Images from unknown registries may be malicious — verify sources - Build args visible in image history — don't use for secrets ## Debugging - Exit code 137 = OOM killed, 139 = segfault — check `docker inspect --format='{{.State.ExitCode}}'` - Container won't start: check logs even for failed containers — `docker logs <container>` - No shell in distroless images — `docker cp` files out or use debug sidecar - Inspect filesystem of dead container — `docker cp deadcontainer:/path ./local` ## Related Skills Install with `clawhub install <slug>` if user confirms: - `devops` — deployment pipelines - `linux` — host system management - `server` — server administration ## Feedback - If useful: `clawhub star docker` - Stay updated: `clawhub sync`

path: commands.md
content: # Essential Commands — Docker

Quick reference for common Docker operations.

## Container Lifecycle

```bash
docker run -d --name app -p 8080:80 image    # start detached
docker ps                                      # list running
docker ps -a                                   # list all
docker stop app && docker rm app              # cleanup
docker logs -f app                            # follow logs
docker exec -it app sh                        # shell into
```

## Image Management

```bash
docker build -t myapp:1.0 .                   # build
docker images                                  # list
docker pull nginx:alpine                       # fetch
docker push registry/myapp:1.0                # publish
docker rmi $(docker images -q --filter dangling=true)  # prune
```

## Compose

```bash
docker compose up -d                          # start stack
docker compose down                           # stop & remove
docker compose logs -f                        # follow all logs
docker compose ps                             # stack status
docker compose exec web sh                    # shell into service
```

## Cleanup

```bash
docker container prune                        # remove stopped
docker image prune                            # remove dangling
docker volume prune                           # remove unused (DESTRUCTIVE)
docker system prune -a --volumes              # remove everything (DESTRUCTIVE)
```


path: compose.md
content: # Compose Traps

## depends_on

- `depends_on: [db]` espera que CONTAINER arranque — no que servicio esté ready
- `condition: service_healthy` requiere healthcheck definido — sin él, falla silenciosamente
- Circular dependency no es error — compose intenta resolver y puede fallar random
- depends_on no afecta `docker compose run` — servicios dependency no arrancan

## Environment

- `.env` debe estar junto a `docker-compose.yml` — en subdirectorio no se lee
- `${VAR}` undefined = string vacío, no error — bugs silenciosos
- `${VAR:-default}` solo aplica si VAR undefined — VAR="" usa vacío, no default
- `env_file` no acepta export syntax — `export VAR=x` falla

## Volumes

- Volume mount sobre directorio con archivos = archivos del container desaparecen
- Bind mount de directorio host vacío = directorio container vacío
- `./path` relativo al compose file, no al cwd
- Named volume primera vez copia contenido del container — después no

## Networks

- Default bridge no tiene DNS entre containers — nombres no resuelven
- Container name ≠ service name — usar service name para DNS
- `network_mode: host` desactiva toda la red de compose — no solo para ese container
- External network no se crea automáticamente — debe existir

## Build

- `build: .` usa Dockerfile, `build: { dockerfile: X }` para otro nombre
- Build context se envía completo al daemon — directorio grande = build lento
- `image:` + `build:` juntos = build y tag con ese nombre
- Cache de build no se comparte entre diferentes compose projects por defecto

## Healthcheck

- Healthcheck en compose override el del Dockerfile
- `start_period` no cuenta para retries — primeros N segundos ignora fallos
- `test: ["CMD", "curl", ...]` — CMD usa exec, CMD-SHELL usa shell
- Exit code 0 = healthy, 1 = unhealthy, 2 = reserved (don't use)


path: images.md
content: # Image Building Traps

## Layer Cache

- `COPY . .` antes de `RUN npm install` = cache invalidado en cada cambio de código
- `apt-get update` y `apt-get install` en RUNs separados = packages stale semanas después
- `--no-cache` en build borra TODO el cache — no solo del paso actual
- Cache de un stage no se usa en otro stage — multi-stage rebuild from scratch

## Multi-Stage

- `--from=builder` con typo = copia de stage equivocado silenciosamente
- `COPY --from=0` es primer stage, no stage llamado "0"
- Stage sin nombre + reorden de stages = `--from=N` apunta a stage diferente
- Files copiados de stage anterior pierden permisos — copiar con `--chmod`

## Base Images

- `python:latest` hoy ≠ `python:latest` mañana — builds no reproducibles
- `alpine` sin glibc = muchos binarios no funcionan — errores crípticos
- `slim` images sin shell tools = debugging imposible
- Imagen "latest" puede ser major version diferente — breaking changes

## COPY vs ADD

- `ADD` con URL descarga pero no cachea — rebuild = re-download
- `ADD` con .tar.gz extrae automáticamente — sorpresa si no lo esperabas
- `COPY` no expande wildcards como shell — `COPY *.json ./` puede no hacer lo que esperas
- `.dockerignore` ignorado en builds remotos (docker build - < Dockerfile)

## ARG vs ENV

- `ARG` no disponible después de `FROM` — cada stage necesita re-declarar
- `ARG` con valor default + override vacío = usa el default, no vacío
- `ARG` visible en `docker history` — no para secrets
- `ENV` persiste en runtime — `ARG` solo en build

## Size Traps

- `rm -rf /var/lib/apt/lists` en RUN separado = espacio no recuperado (layers)
- `npm install --production` después de `npm install` = dev dependencies todavía en layer anterior
- `.git` copiado = megas extra si no hay .dockerignore
- Múltiples `RUN apt-get` = cada uno es layer con cache de apt


path: infrastructure.md
content: # Infrastructure Traps

## Networking

- `localhost` en container es el container, no el host — usar `host.docker.internal`
- `0.0.0.0` bind necesario para que container sea accesible — `127.0.0.1` solo local al container
- `-p 5432:5432` sin IP = bind a todas interfaces = público si no hay firewall
- Container restart cambia IP — usar network aliases, no IPs hardcoded

## DNS

- DNS default es 127.0.0.11 interno — no usa /etc/resolv.conf del host
- `--dns` override completo — no se añade, reemplaza
- DNS caching en daemon — cambios DNS externos tardan en propagarse
- Container sin network no tiene DNS — ni siquiera localhost resuelve

## Volumes

- Volume anónimo (`VOLUME` en Dockerfile) acumula sin límite — nunca se borran automáticamente
- `docker system prune` NO borra volumes — necesita `--volumes` explícito
- Bind mount permissions: container user vs host user — mismatch = permission denied
- NFS volumes con latencia = performance horrible — especialmente para node_modules

## Storage Driver

- `overlay2` default pero overlayfs en kernel viejo = bugs sutiles
- Storage driver diferente entre dev/prod = comportamiento diferente
- Logs sin limit crecen infinito — `--log-opt max-size=10m`
- `/var/lib/docker` lleno = daemon se cuelga — monitoring esencial

## Resources

- Sin `--memory` limit = container puede usar toda la RAM y triggerar OOM killer
- `--memory` sin `--memory-swap` = swap = 2x memory — puede ser mucho
- `--cpus=0.5` es limit, no reservation — otros containers pueden usar
- Java en container sin `-XX:+UseContainerSupport` no ve el límite correcto

## Security

- `--privileged` desactiva TODA la seguridad — casi nunca necesario
- `--cap-add` granular mejor que privileged — solo lo que necesitas
- Root en container puede ser root en host — user namespaces para evitar
- Secrets en env vars visibles con `docker inspect` — usar secrets/mounts


path: security.md
content: # Security Traps

## User

- Container corre como root por defecto — security scanners lo flaggean
- `USER` directive después de `RUN` que necesita root = build falla
- User en container con UID 1000 = puede ser otro user en host — confuso
- `--user` en runtime override USER de Dockerfile — pero permisos de archivos quedan

## Secrets

- `ENV SECRET=x` visible en `docker history` y `docker inspect`
- `ARG` para secrets también visible en history — no es seguro
- `COPY secrets.txt` baked en layer — aunque lo borres después, está en layer anterior
- `--env-file` seguro en runtime pero archivo debe protegerse en host

## BuildKit Secrets

- `RUN --mount=type=secret` no disponible sin DOCKER_BUILDKIT=1
- Secret mount solo disponible en ese RUN — no persiste
- Secret ID debe coincidir exacto — typo = build falla sin mensaje claro
- Secret no disponible en stages que no lo montan explícitamente

## Image Scanning

- Vulnerabilities en base image heredadas — actualizar base regularmente
- Scan en CI pero no en registry = images vulnerables en producción
- CVE "fixed" en package pero base image no actualizada = sigue vulnerable
- Distroless images difíciles de scanear — menos CVEs reportadas, no menos bugs

## Runtime

- `--privileged` = acceso completo a host devices, kernel modules, etc.
- `--cap-add SYS_ADMIN` casi tan malo como privileged — evitar
- `-v /:/host` monta root del host = game over si container comprometido
- `--pid=host` permite ver/kill procesos del host desde container

## Network

- Container en bridge network puede acceder a metadata service (169.254.x.x)
- Sin `--network=none`, container tiene acceso a red por defecto
- Published ports sin firewall = público a internet
- Container puede hacer requests a otros containers en misma network — no isolation

## Supply Chain

- Base image de registry público puede ser maliciosa — verificar publisher
- `latest` tag puede ser hijacked — usar digest para images críticas
- Dependencias descargadas en build pueden cambiar — lock files + verified mirrors


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)