# Containers > 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. - Skill: `xobotyi/containers` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add xobotyi/containers` - Raw SKILL.md: https://api.skillmd.com/api/skills/xobotyi/containers/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: xobotyi (https://skillmd.com/u/xobotyi) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/xobotyi/containers --- # 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 - **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/` — 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 ` — check application output 2. `docker inspect ` — verify config, mounts, network, env 3. `docker exec -it sh` — interactive inspection (if shell available) 4. `docker run -it --rm --network container: nicolaka/netshoot` — network debugging with full toolkit 5. For distroless: `docker run -it --rm --pid container: --network container: 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.