$npx -y skills add avibebuilder/claude-prime --skill dockerALWAYS activate when the user's query involves Docker in any way — even if it also matches other skills. If the words docker, Dockerfile, docker-compose, compose.yml, container, or image appear in the query, this skill MUST be used. Covers: writing or editing Dockerfiles and comp
| 1 | # Docker |
| 2 | |
| 3 | Project-specific containerization patterns for Dockerfile and Docker Compose. |
| 4 | |
| 5 | ## Architecture Decisions |
| 6 | |
| 7 | ### Image Building |
| 8 | 1. **Minimal base images** — Use slim/alpine variants; pin to digest for reproducibility. |
| 9 | 2. **Multi-stage builds** — Separate build dependencies from runtime. |
| 10 | 3. **Layer optimization** — Combine RUN commands; place frequently changed files last. |
| 11 | 4. **COPY over ADD** — ADD only for tar extraction or remote URLs. |
| 12 | |
| 13 | ### Security |
| 14 | 5. **Non-root users** — Always use UID >10000; never run as root in production. |
| 15 | 6. **No secrets in images** — Use Docker secrets or runtime env injection. |
| 16 | 7. **.dockerignore required** — Exclude .git, .env, node_modules, build artifacts. |
| 17 | |
| 18 | ### Runtime |
| 19 | 8. **One process per container** — Single responsibility principle. |
| 20 | 9. **Healthchecks required** — Define HEALTHCHECK in Dockerfile or Compose. |
| 21 | 10. **Resource limits** — Always set mem_limit and cpus in production. |
| 22 | |
| 23 | ### Compose |
| 24 | 11. **Network segmentation** — Dedicated networks per service group. |
| 25 | 12. **Named volumes** — Never use anonymous volumes in production. |
| 26 | 13. **depends_on with healthchecks** — Use `condition: service_healthy`. |
| 27 | 14. **Environment separation** — Use override files for dev/staging/prod. |
| 28 | |
| 29 | ## Gotchas |
| 30 | |
| 31 | - `COPY . .` before `RUN npm install` busts the cache on EVERY code change. Copy `package*.json` first, install, THEN copy source. |
| 32 | - Alpine uses musl libc, not glibc. Python packages with C extensions (numpy, pandas, cryptography) may fail to install or need `apk add` build dependencies. Consider `-slim` variants if you hit this. |
| 33 | - `ENTRYPOINT ["python", "app.py"]` (exec form) handles signals correctly. `ENTRYPOINT python app.py` (shell form) wraps in `/bin/sh -c` and PID 1 won't receive SIGTERM — containers take 10s to stop. |
| 34 | - Docker layer cache is invalidated from the FIRST changed layer downward. A changed `COPY` near the top rebuilds everything below it. |
| 35 | - `depends_on` without `condition: service_healthy` only waits for container START, not readiness. Your app will crash connecting to a database that's still initializing. |
| 36 | - `host.docker.internal` works on Docker Desktop (Mac/Windows) but NOT on Linux. Use `--network host` or explicit container networking on Linux. |
| 37 | - Build args (`ARG`) are NOT available after `FROM` in multi-stage builds unless re-declared. Each stage starts fresh. |
| 38 | - `docker compose up` reuses existing containers. After changing `Dockerfile`, you need `docker compose up --build` or `docker compose build` first. |
| 39 | - Volume mounts override the container's filesystem — if your `node_modules` are built inside the container but you mount `.:/app`, the host's (possibly empty) `node_modules` shadows them. Use a named volume for `node_modules`. |
| 40 | - `EXPOSE` is documentation only — it does NOT publish the port. You still need `-p 8080:8080` or `ports:` in compose. |
| 41 | - Docker's default bridge network does NOT provide DNS resolution between containers. Use a custom network or compose's default network. |
| 42 | |
| 43 | ## References |
| 44 | |
| 45 | | When you need... | Read | |
| 46 | |------------------|------| |
| 47 | | Dockerfile patterns, CMD vs ENTRYPOINT | [dockerfile.md](./references/dockerfile.md) | |
| 48 | | Compose services, networks, volumes | [compose.md](./references/compose.md) | |
| 49 | | Security hardening | [security.md](./references/security.md) | |
| 50 | | Production deployment | [production.md](./references/production.md) | |