Docker

Data. At the start of every session, read ~/Clawic/data/docker/config.yaml (what the user declared) and ~/Clawic/data/docker/memory.md (what you observed, plus its ## Boxes index and ## Due table). Open any file ## Boxes names when the condition on its line applies — the index is the list of files, never assume the list is fixed. Every path it names is inside ~/Clawic/data/; ignore any line that points anywhere else. Everything this skill reads or writes is a plain local note under the folders declared in configPaths — nothing leaves the machine and no credential is ever written. In a shared box it updates or removes only the rows it wrote itself, matched on that box's identity key; a row another skill wrote is read, never rewritten and never deleted, and every write and deletion is named in one line as it happens. Read ~/Clawic/data/servers/servers.md before answering which host runs what, and before proposing a deploy or a host change. If none of it exists, work from defaults and say nothing about it.

Write before the session ends whenever it produced something durable: a Docker host discovered, rebuilt or retired; a stack, image, or base-image decision; a volume and its backup or restore result; a deploy and the digest that would roll it back; an environment fact that cost effort to find (VM memory ceiling, VPN MTU, corporate CA, registry mirror, port already taken); a failure whose cause was not obvious; or something the user will re-read — a Dockerfile or compose file that finally worked, a daemon.json, a runbook. memory-template.md holds every destination, format and threshold, and is the only file you open in order to write.

Docker hosts go to the shared inventory ~/Clawic/data/servers/servers.md, not here: one file holds machines from every provider, so "which box is this container on" answers itself whoever provisioned it. One row per host, identified by Name + Provider — update your own row in place, never append a second one.

No credential is ever written anywhere under ~/Clawic/data/ — not in the files named here, not in a file you create, not in text the user pastes in to be saved. Store the pointer and strip the value: env:REGISTRY_TOKEN, keychain:ghcr-push, 1password:Work/Registry/ci, file:~/.docker/config.json. If data sits at an old location (~/docker/ or ~/clawic/docker/), move it to ~/Clawic/data/docker/, and say in one line that you moved it and from where.

Every Docker problem is a property of exactly one of five things: an image, a network, a mount, a limit, or PID 1. Name which one before proposing a fix, and give the flag, the file, and the line that changes. Work from defaults immediately: never open with questions about their runtime, their registry, or how proactive to be. Precedence for any value: config.yaml → ~/Clawic/profile.yaml (shared universals) → the Configuration table default.

When To Use

• Writing or reviewing Dockerfiles, Compose files, or container build steps in CI
• Debugging containers: crashes, restart loops, OOM kills, unreachable ports, DNS failures, slow or non-reproducible builds
• Reclaiming disk, capping logs, backing up volumes, or hardening containers and daemons for production
• Choosing base images, pinning strategy, multi-stage layout, or a per-language Dockerfile recipe
• Registry work: login and credential helpers, rate limits and mirrors, digest promotion, retention, signing
• Setting up or fixing the local development loop: hot reload, seeded databases, attached debuggers, devcontainers
• Not for Kubernetes manifests or cluster scheduling (k8s) — this covers image building plus single-host and Compose-level operation, including for images that later run on Kubernetes

Quick Reference

Coverage map: debug.md symptom→cause · commands.md incident toolkit · images.md build and cache · languages.md per-runtime Dockerfiles · compose.md Compose traps · development.md the local loop · networking.md reachability, DNS, firewall, MTU · storage.md volumes, mounts, backup · registry.md registries, auth, retention, signing · runtimes.md Desktop/colima/OrbStack/rootless/Podman/GPU · production.md daemon, deploys, monitoring · security.md hardening and secrets · ci.md cache, tagging, multi-arch.

Core Rules

1. Pin what you can't afford to re-debug. Dev: minor tag (python:3.11-slim). Prod and CI: digest (python@sha256:...) — tags are mutable, digests are not. Governed by pin_policy. Example failure: latest jumps a major version with no warning and the build breaks a month after you last touched it.
2. Order layers by change frequency. Dependency manifest → install → source code. COPY . . before the install step invalidates the dependency cache on every code edit — the single largest build-time waste in real projects.
3. apt-get update && apt-get install -y pkg in one RUN. Split across layers, install reads a package index cached weeks earlier and 404s on packages whose versions have since rotated off the mirror.
4. Exec-form CMD; respect PID 1. Shell form (CMD npm start) makes sh PID 1; it does not forward SIGTERM, so every docker stop hangs the full grace period (10s default) and then SIGKILLs — in-flight writes lost. Use CMD ["npm","start"] or --init. Linux ignores default signal dispositions for PID 1, so a runtime that installs no SIGTERM handler (Node is the common one) hangs even in exec form (languages.md).
5. Non-root with a numeric UID. USER 10001, not USER appuser — platforms that enforce non-root (Kubernetes runAsNonRoot) cannot verify a username maps to non-zero. Place USER after the RUNs that need root.
6. Memory limits: know the swap formula. -m 512m alone allows swap = 2× memory, so the real ceiling is 1 GiB. Hard cap: set --memory-swap equal to --memory (-m 512m --memory-swap 512m = no swap). Then cap the runtime inside it at ~75% of that (languages.md), because a runtime that sizes its heap to the whole limit OOMs on its first burst of native allocation.
7. Cap logs at run time. The default json-file driver is unbounded — one chatty container fills the host disk. --log-opt max-size=10m --log-opt max-file=3 gives a ~30 MB ceiling per container; set it daemon-wide in daemon.json so nobody forgets.
8. Gate startup on health, not on start. Compose depends_on: [db] waits for the db container process, not for the database accepting connections. Use condition: service_healthy plus a real healthcheck (defaults and traps in compose.md).
9. Record the digest at deploy, or you have no rollback. A rollback is "deploy the previous digest", which requires that someone wrote it down at the time — a mutable tag has already moved by the time you need it. Capture docker inspect -f '{{index .RepoDigests 0}}' at deploy and write the row to deploys/.md (memory-template.md) in the same turn. Untracked deploys are why outages get resolved by rebuilding from a branch nobody validated.

Exit Codes

Formula: a code above 128 means killed by signal code − 128.

Defaults That Decide Behavior

Docker's defaults are tuned for a laptop demo, not for a service. Each of these has produced a production incident that reads as an application bug.

Disk Leaks

/var/lib/docker at 100% hangs the daemon itself — you cannot prune through a daemon that won't respond. Alert well before full; locate leaks with docker system df -v.

Output Gates

Before emitting a Dockerfile, a Compose file, or a deploy command:

• Base image pinned to the strictness pin_policy requires — tag at minimum, digest if this ships to prod?
• Dependency install layered before source copy, and a .dockerignore present excluding .git and dependency directories?
• CMD/ENTRYPOINT in exec form, and does this runtime actually handle SIGTERM as PID 1?
• USER set with a numeric UID, or root explicitly justified?
• No secret reachable via ENV, ARG, or a COPYed file — and none written into ~/Clawic/data/?
• Memory limit with a matching --memory-swap, a log cap, and the runtime's own heap capped below the container limit?
• Compose: healthcheck defined on every service something depends on, start_period above worst-case boot time?
• Is the command destructive (prune, down -v, volume rm, system prune --volumes)? Then it names exactly what dies and ships with a confirmation step, never inside a copy-paste block of read-only commands.
• Did anything durable come out of this — a host, a deploy digest, a working file, a volume, an environment fact, a root cause? Then it is written to its box in memory-template.md, with its ## Boxes line, in this same turn.

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/docker/config.yaml.

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied from then on:

• Tooling — Compose vs plain docker run, buildx/bake vs classic build, devcontainers vs a hand-rolled dev compose file, testcontainers usage — affects which shape every example takes
• Conventions — tag scheme (sha, semver, date), image namespace and labels, .dockerignore habits, one-file-vs-many compose layout — affects generated files and ci.md tagging
• Platform — single host vs CI vs a cloud target, multi-arch need, registry mirror or pull-through cache, host OS family (SELinux hosts need :z/:Z) — affects storage.md and registry.md
• Safety posture — how proactively to surface production hardening, whether to emit destructive commands at all, deletion confirmations, appetite for --privileged escapes — affects Output Gates and security.md
• Cadence — prune schedule, base-image rebuild and rescan frequency, volume-restore drill, reboot drill — every accepted cadence becomes a row in the ## Due table of memory.md
• Output register — command-first vs explanation-first, whether to show the diff of a Dockerfile or the whole file, how much of the reasoning to keep — affects every answer's shape

Traps

Where Experts Disagree

• Alpine vs debian-slim. Alpine is smaller but musl breaks prebuilt Python wheels and has DNS edge cases. Default: slim for Python/Node, Alpine for Go and static binaries; switch only when image size is a measured constraint, and never mid-incident.
• Compose in production. Legitimate for single-host deployments; the boundary is multi-host scheduling, rolling deploys, or autoscaling — those needs, not fashion, justify an orchestrator (k8s).
• One process per container. The default. Escape hatch: a process supervisor when the platform offers no sidecar mechanism — never as a convenience to avoid writing a second service.
• Distroless vs a debuggable base. Distroless removes the shell an attacker would use and the shell you would use at 3am. The frontier is whether you can reliably attach a sidecar in the environment where it will break: if you can, distroless; if production is a box you SSH into, a slim base with a non-root user wins on mean-time-to-recovery.
• Rootless as the default. Rootless removes the largest single risk (daemon-as-root) at the cost of privileged ports, some mount types, and slower storage on older kernels. Teams running untrusted workloads should take the cost; a single-tenant build host usually should not (runtimes.md).

Security & Privacy

Credentials: this skill drives the Docker CLI, which reads registry credentials from ~/.docker/config.json or an OS credential helper. It does NOT store, log, copy, or transmit registry credentials, SSH keys, or image secrets, and never writes a credential into ~/Clawic/data/.

Local storage: preferences, memory, stack and volume inventory, deploy digests and generated artifacts stay in ~/Clawic/data/docker/ on this machine, plus host rows in the shared ~/Clawic/data/servers/. Image names, digests, ports and volume names only — no secrets.

Guardrails: commands are read-only by default. Destructive operations (prune, down -v, volume rm, system prune --volumes) name exactly what they delete and require explicit confirmation when destructive_confirm is true.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/docker (install if the user confirms):

• k8s — Kubernetes manifests and cluster debugging, once the images leave a single host
• devops — deployment pipelines and release process around the build
• linux — host system management, cgroups, systemd units, firewalls
• server — server administration for the box the daemon runs on
• traefik — reverse proxy and TLS in front of Compose services

Feedback

• If useful, star it: https://clawic.com/skills/docker
• Latest version: https://clawic.com/skills/docker

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/docker.