containers · diff
git:20260313.02a8e7c to git:20260314.9629b35
12 added, 8 removed. Audit A to A.
---
name: containers
description: >-
Docker and Podman container management: Dockerfile optimization, multi-stage
builds, Compose v2 orchestration, networking, volumes, security hardening,
supply chain integrity, health checks, resource limits, Quadlet systemd
integration, and debugging. Invoke whenever task involves any interaction
with containers — writing Dockerfiles, configuring Compose, managing
Podman Quadlets, reviewing container security, debugging container
issues, or setting up image signing and scanning.
---
# Containers
Security is not optional. Every container runs non-root, with dropped capabilities, on a minimal base image. Convenience
defaults that weaken security posture are bugs, not trade-offs.
## Security Rules
These are non-negotiable defaults for every container configuration. Apply unconditionally — no exceptions for
development, convenience, or "temporary" setups.
- **Run as non-root.** Add a `USER` instruction with explicit UID/GID. Never run production containers as root.
- **Drop all capabilities.** `--cap-drop=ALL`, then add back only what the application genuinely requires. Most
applications need zero.
- **Enable no-new-privileges.** `--security-opt=no-new-privileges` prevents setuid/setgid escalation.
- **Use read-only filesystem.** `--read-only` with `tmpfs` mounts for `/tmp`, `/run`, and any directories the app writes
to.
- **Never pass secrets via ENV.** Visible in `docker inspect`, logs, and child processes. Use mounted secret files or
Docker secrets.
- **Scan images before deployment.** Use Docker Scout, Trivy, or Grype in CI. Block images with critical CVEs.
- **Use distroless for production** when possible. No shell means no shell-based attacks and dramatically fewer CVEs.
- **Never use `--privileged`.** It removes almost all security restrictions. If a workload claims to need it, decompose
the requirement into specific capabilities.
- **Never mount the Docker socket** (`/var/run/docker.sock`) into containers. It grants root-equivalent control over the
host. Use purpose-built APIs or socket proxies with restricted access.
- **Use `--init` or tini/dumb-init for PID 1.** Regular applications don't reap zombie processes or handle signals
correctly as PID 1. Use `docker run --init`, `RunInit=true` in Quadlets, or install tini in the Dockerfile. Without
this, `docker stop` waits for the kill timeout and zombies accumulate.
- **Verify supply chain integrity.** Pin images to digest, generate SBOMs (Syft, Docker Scout), sign images with
cosign/Sigstore. Use VEX documents to distinguish exploitable from non-exploitable CVEs. Block unsigned images in CI.
## References
- | Topic | Reference | Contents |
- | --------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
- | Dockerfile patterns | [`${CLAUDE_SKILL_DIR}/references/dockerfile-patterns.md`] | Multi-stage templates, layer optimization, base image table, .dockerignore, ENTRYPOINT/CMD, BuildKit cache mounts, signal handling, OCI labels |
- | Compose orchestration | [`${CLAUDE_SKILL_DIR}/references/compose-orchestration.md`] | Service structure, depends_on conditions, env vars, secrets, networks, volumes, profiles, restart policies, override files, zero-downtime patterns |
- | Security hardening | [`${CLAUDE_SKILL_DIR}/references/security-hardening.md`] | Non-root patterns, read-only FS, capabilities, distroless, secrets, scanning, supply chain security, SBOM, image signing, VEX, hardening checklist |
- | Networking | [`${CLAUDE_SKILL_DIR}/references/networking.md`] | Driver selection table, bridge/host/macvlan/ipvlan usage, port publishing, DNS, multi-network, common mistakes, iptables bypass |
- | Storage and volumes | [`${CLAUDE_SKILL_DIR}/references/storage-and-volumes.md`] | Volume types table, named/bind/tmpfs, NFS/CIFS drivers, backup/restore, permissions, storage drivers, performance |
- | Operations | [`${CLAUDE_SKILL_DIR}/references/operations.md`] | Health checks, resource constraints, logging drivers, structured logging, debugging, monitoring, Quadlet patterns, Docker/Podman CLI compat |
+ - **Dockerfile patterns** — [`${CLAUDE_SKILL_DIR}/references/dockerfile-patterns.md`]: Multi-stage templates, layer
+ optimization, base image selection, .dockerignore, ENTRYPOINT/CMD, BuildKit cache mounts, signal handling, OCI labels
+ - **Compose orchestration** — [`${CLAUDE_SKILL_DIR}/references/compose-orchestration.md`]: Service structure, depends_on
+ conditions, env vars, secrets, networks, volumes, profiles, restart policies, override files, zero-downtime patterns
+ - **Security hardening** — [`${CLAUDE_SKILL_DIR}/references/security-hardening.md`]: Non-root patterns, read-only FS,
+ capabilities, distroless, secrets, scanning, supply chain security, SBOM, image signing, VEX, hardening checklist
+ - **Networking** — [`${CLAUDE_SKILL_DIR}/references/networking.md`]: Driver selection, bridge/host/macvlan/ipvlan usage,
+ port publishing, DNS, multi-network, common mistakes, iptables bypass
+ - **Storage and volumes** — [`${CLAUDE_SKILL_DIR}/references/storage-and-volumes.md`]: Volume types, named/bind/tmpfs,
+ NFS/CIFS drivers, backup/restore, permissions, storage drivers, performance
+ - **Operations** — [`${CLAUDE_SKILL_DIR}/references/operations.md`]: Health checks, resource constraints, logging
+ drivers, structured logging, debugging, monitoring, Quadlet patterns, Docker/Podman CLI compat
## Dockerfile Rules
- **Use multi-stage builds.** Separate build dependencies from the runtime image. Final stage contains only the
binary/app and its runtime dependencies.
- **Choose minimal base images.** `alpine`, `*-slim`, `distroless`, or `scratch` for static binaries. Never use full OS
images in production.
- **Pin base image versions.** Use digest pinning (`@sha256:...`) in CI for reproducibility. Use minor version tags
(`3.13-slim`) in development. Never use `:latest`.
- **Order layers by change frequency.** Stable instructions first (OS packages), volatile instructions last (source
code). Copy dependency manifests before source code for layer caching.
- **Combine RUN statements.** Merge `apt-get update` with `apt-get install` in the same `RUN`. Clean caches in the same
layer. Sort packages alphabetically.
- **Use COPY, not ADD.** `COPY` for local files. `ADD` only when you need remote URL fetching or automatic tar
extraction.
- **Use exec form for CMD/ENTRYPOINT.** `CMD ["app", "--flag"]` — not `CMD app --flag`. Shell form wraps in
`/bin/sh -c`, making the shell PID 1. Shells don't forward signals to children — your app never receives SIGTERM on
`docker stop`.
- **Use `exec "$@"` in entrypoint scripts.** Without `exec`, the shell spawns the app as a child and swallows signals.
`exec` replaces the shell process with the app, making it PID 1.
- **Always create a .dockerignore.** Exclude `.git`, `node_modules`, `.env`, build artifacts, and documentation from the
build context.
- **Use `--mount=type=secret` for build-time secrets.** Never `COPY` or `ENV` secrets — they persist in image layers.
- **Set WORKDIR to an absolute path.** Never use `RUN cd ... && ...`.
- **Use BuildKit cache mounts** for package manager caches:
`RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt`. Avoids re-downloading dependencies
on every build.
- **Use `docker buildx` for multi-platform images.** `docker buildx build --platform linux/amd64,linux/arm64` produces
images for multiple architectures. Required for ARM/x86 portability.
- **Add OCI labels.** Use `LABEL org.opencontainers.image.*` for source, version, description. Enables registry
identification and automated tooling.
## Compose Rules
- **Use Compose v2 specification.** No `version:` field. Use `compose.yml` (not `docker-compose.yml`).
- **Use `depends_on` with `condition: service_healthy`** for services that need initialization time (databases, caches).
- **Use `service_completed_successfully`** for one-shot dependencies like migrations.
- **Isolate networks.** Create separate networks for frontend/backend tiers. Use `internal: true` on backend networks to
block outbound internet access.
- **Use named volumes for persistent data.** Bind mounts for development, named volumes for production. Never rely on
anonymous volumes.
- **Always set resource limits.** `deploy.resources.limits` for memory and CPU. A container without memory limits can
OOM-kill the host.
- **Configure log rotation.** Use `local` logging driver, or configure `json-file` with `max-size` and `max-file`.
Default has no rotation.
- **Use restart policies.** `unless-stopped` for production services. `on-failure` for tasks that should retry but
eventually stop.
- **Use profiles for optional services.** Debug tools, monitoring, and test runners behind `profiles:` — not started by
default.
- **Use env_file for environment variables.** Keep `.env.example` in version control, `.env` in `.gitignore`.
- **Use file-based secrets.** Compose `secrets:` mounts files at `/run/secrets/<name>` — granular per-service access,
not visible in `docker inspect` or process listings like env vars.
- **Use override files for multi-environment.** `compose.yml` for common defaults, `compose.prod.yml` for production
overrides. Use explicit `-f` flags in production — never rely on automatic `compose.override.yml` loading.
- **Use structured logging (JSON).** Configure apps to emit JSON logs to stdout. Use Pino (Node), Zap (Go), or stdlib
JSON formatters. Structured logs enable filtering and aggregation.
## Networking Rules
- **Always use user-defined bridge networks.** Default bridge has no DNS resolution and no isolation. User-defined
bridges provide automatic service discovery by container name.
- **Use `host` network only for performance-critical workloads** that bind many dynamic ports. Not available on Docker
Desktop.
- **Use `macvlan` when containers need LAN presence** with unique MAC addresses. Use `ipvlan` when the switch limits MAC
count.
- **Bind published ports to `127.0.0.1`** when the service should not be externally accessible. Docker port mapping
bypasses host firewall rules.
- **Use `internal: true`** on backend Compose networks to prevent outbound internet access from database and cache
containers.
- **Bind services to `0.0.0.0` inside containers.** A service bound to `localhost` inside a container is unreachable
from other containers — `localhost` refers to the container's own namespace.
- **Use a reverse proxy for public-facing services.** Only the proxy publishes ports. Backend services stay on internal
networks with no published ports. This centralizes TLS, rate limiting, and access logs.
## Volume Rules
- **Named volumes for persistent data.** Databases, uploads, state that must survive container recreation.
- **Bind mounts for development.** Source code, config files injected from host. Always use `:ro` when the container
should not modify.
- **tmpfs for sensitive ephemeral data.** Secrets at runtime, session files, scratch space. Never persisted to disk.
- **Set volume permissions at build time.** `RUN mkdir && chown` before `USER` instruction. Avoids permission denied
errors at runtime.
- **Monitor volume disk usage.** `docker system df` shows space used by images, containers, and volumes. Dangling
anonymous volumes accumulate silently — run `docker volume prune` periodically.
- **For Podman:** use `:U` to chown volume contents to match container user, `:Z`/`:z` for SELinux relabeling.
## Health Check Rules
- **Define health checks for every long-running service.** Use `HEALTHCHECK` in Dockerfile or `healthcheck:` in Compose.
- **Use appropriate check commands.** `curl -f` for HTTP services, `pg_isready` for Postgres, `redis-cli ping` for
Redis, `nc -z` for TCP ports.
- **Set `start_period`** for services with slow initialization. Failures during start period don't count toward retry
limit.
- **For distroless images,** build the health check into the application binary. No shell or curl available.
- **Health checks run inside the container.** Only check local endpoints, never external dependencies.
## Resource Limit Rules
- **Always set memory limits in production.** `--memory` or `deploy.resources.limits.memory`. Prevents OOM cascade.
- **Set `--memory-swap` equal to `--memory`** to disable swap. Swapping containers cause unpredictable latency.
- **Use `--cpus` for CPU limits.** Simpler than `--cpu-period`/`--cpu-quota`. `--cpus=1.5` means 150% of one core.
- **Use `--cpu-shares` for relative priority** under contention. Not a hard limit — only enforced when CPU is scarce.
## Podman Considerations
- **Podman is rootless by default.** No daemon, no root required. Uses user namespaces to map container root to
unprivileged host user. Grants only 11 default capabilities (vs Docker's 14) — tighter least-privilege baseline out of
the box.
- **Requires `/etc/subuid` and `/etc/subgid` ranges** for the user running containers. Run `podman system migrate` after
changes.
- **Rootless cannot bind ports < 1024** without `net.ipv4.ip_unprivileged_port_start` sysctl.
- **Rootless networking uses `pasta` or `slirp4netns`** — not kernel bridging. Performance differs from Docker's bridge
driver. DNS resolution within custom networks is handled by `aardvark-dns`; network setup by `netavark`.
- **Use Quadlet files for systemd integration.** Place `.container`, `.volume`, `.network`, `.pod` files in
`~/.config/containers/systemd/` (rootless) or `/etc/containers/systemd/` (rootful). Replaces deprecated
`podman generate systemd`. Run `systemctl --user daemon-reload` after changes. Enable user lingering
(`loginctl enable-linger`) for rootless services to survive logout.
- **Use `AutoUpdate=registry` in Quadlet containers.** Requires fully-qualified image names. Enable the timer:
`systemctl --user enable --now podman-auto-update.timer`. Podman pulls new images and restarts affected services.
Dry-run with `podman auto-update --dry-run`.
- **Use `RunInit=true` in Quadlet containers.** Equivalent to `docker run --init` — adds tini as PID 1 for signal
forwarding and zombie reaping.
- **Use `TimeoutStartSec=900` for slow image pulls.** Systemd defaults to 90s — large images will fail the service
start.
- **`podman pod`** groups containers sharing a network namespace, similar to Kubernetes pods. Containers in a pod
communicate over `localhost`. Use `.pod` Quadlet files with `Pod=` directive in container files to join.
- **SELinux integration is first-class.** Use `:Z` (private) or `:z` (shared) volume flags. `:Z` applies MCS labels
isolating containers from each other. Always use `:Z` on SELinux systems.
- **Use `Secret=` in Quadlets for credentials.** Create with `podman secret create`, reference with
`Secret=name,type=env,target=VAR`. Cleaner than env files for sensitive data.
- **Docker Compose compatibility:** `podman compose` wraps docker-compose. Use fully-qualified image names for registry
operations. Most Docker CLI commands work identically with Podman.
## Application
**When writing Dockerfiles or Compose files:** Apply all rules silently. Produce secure, optimized configurations by
default — multi-stage builds, non-root users, minimal images, init process, health checks, resource limits, log
rotation, and file-based secrets. Never produce a Dockerfile without a `USER` instruction or a Compose service without
`deploy.resources.limits`.
**When reviewing container configurations:** Check every security rule first. Cite the specific rule violated and show
the fix inline. Review priority: security violations > missing resource limits > missing health checks > missing log
rotation > layer optimization.
**When debugging container issues:**
1. `docker logs -f --tail 100 <container>` — check application output
2. `docker inspect <container>` — verify config, mounts, network, env
3. `docker exec -it <container> sh` — interactive inspection (if shell available)
4. `docker run -it --rm --network container:<target> nicolaka/netshoot` — network debugging with full toolkit
5. For distroless: `docker run -it --rm --pid container:<target> --network container:<target> busybox` — ephemeral debug
sidecar
## Integration
- `the-coder` provides overall coding discipline for configuration files
- `networking` skill in this plugin covers network infrastructure beyond container networking (VLANs, firewalls, reverse
proxies)
- Language plugins (golang, javascript, python) provide language-specific build patterns referenced in multi-stage
Dockerfiles
Every container is non-root, read-only filesystem, all capabilities dropped, with an init process for signal handling.
Every image is minimal, scanned, signed, and pinned. Every service has health checks, resource limits, log rotation, and
structured logging. No exceptions.