absolute-dotfiles/docs/specs/2026-07-19-docker-nuke-design.md

docker-nuke — Design

Date: 2026-07-19 Status: Approved Target: ~/.local/bin/docker-nuke

Purpose

Recover a wedged Docker Desktop on macOS with a single command, and capture enough forensic state beforehand to triage why it wedged.

The script exists because Docker Desktop periodically becomes unresponsive on this machine and the manual recovery (quit app, hunt stray processes, kill, relaunch, wait) is slow and easy to get wrong.

Context

Observed environment at design time:

• Docker Desktop is the only runtime. Daemon 29.6.1, 27 running containers.
• /usr/local/bin/docker is the real CLI.
• ~/bin contains dangling OrbStack symlinks (docker, docker-compose, kubectl, orb, orbctl) pointing into a gutted ~/.orbstack/bin/. Out of scope here; noted for separate cleanup.
• sample, spindump, lsof, vm_stat, fs_usage all available.
• Docker logs: ~/Library/Containers/com.docker.docker/Data/log/{host,vm}.
• The data volume is 100% full — 653 MB free of 926 GB. Docker.raw is 140 GB on disk (215 GB apparent). This is the likely root cause of the recurring hangs. Out of scope for this script, but it is why disk capture is a first-class part of the dump.

Non-goals

• No container-state snapshot/replay. Containers without a restart policy stay stopped after a nuke. Recording running state requires querying the daemon — precisely what is broken when the script is needed — so it would be unreliable exactly when it matters. Docker's own restart policies cover what matters.
• No sudo on the default path. Root launchd helper cleanup is opt-in via --deep so the normal path never blocks on a password prompt.
• No disk cleanup or pruning. The script never deletes Docker data.
• No fix for the full disk. Surfaced in the dump, handled separately.

Behavior

1. Health check

Run docker info under a 6s hard timeout.

• Times out or fails → Docker is wedged. Proceed immediately, no prompt.
• Succeeds → print daemon version and container count, then require y/N confirmation. --force skips the prompt.

Rationale: zero friction in the case the tool exists for, while a healthy daemon cannot be bounced by an accidental invocation.

2. Pre-kill dump

Capture happens before any kill, because killing destroys the state being triaged. Written to ~/.local/state/docker-nuke/<UTC-timestamp>/.

The full dump always runs — there is no flag to skip or reduce it. The only run that produces no dump is --dry-run. Stack sampling is included unconditionally, accepting roughly 10-15s of added latency before the kill begins, because stack traces are the one signal that cannot be reconstructed after the processes die. --no-restart still produces a complete dump.

File	Contents	Diagnostic value
ps.txt	Docker procs with STAT, %cpu, %mem, elapsed, full command	U/D state means stuck in kernel, not user space
sample-<pid>.txt	2s stack samples of com.docker.backend, com.docker.krun	Shows where it is hung
disk.txt	df -h all volumes, Docker.raw apparent + on-disk size	Would have caught the current full-disk issue
memory.txt	vm_stat, memory pressure	Detects pressure-induced stalls
socket.txt	docker.sock existence, permissions, listener	Distinguishes dead daemon from dead socket
docker-info.txt	docker info / docker version output + whether each timed out
logs/	Last 2000 lines of Docker host + vm logs	Restart rotates these away
crashes/	Recent Docker entries from ~/Library/Logs/DiagnosticReports
summary.txt	Verdict, timings, recovery outcome — written at end of run	The file actually read during triage

Robustness requirement: every capture step runs under its own timeout. sample can itself hang on a truly wedged process. A failed or timed-out step records the failure in summary.txt and continues. The dump can never block recovery.

Log tails are capped at 2000 lines to keep dumps small — relevant given only 653 MB free.

Retention: keep the 10 most recent dump directories, prune older ones at the end of a run.

3. Kill, escalating

Three stages, re-checking liveness between each:

1. osascript quit of Docker Desktop, wait up to 8s — lets it clean up if merely slow
2. SIGTERM everything still alive, wait up to 5s
3. SIGKILL the remainder

4. Restart

open -a Docker, then poll docker info every 2s up to 90s. Skipped with --no-restart.

5. Report

On success: daemon version, container count, elapsed recovery time, dump path. On failure: what is still running, the dump path, and suggested next steps.

Process targeting

The most correctness-sensitive part. Matched two ways:

• Anything under /Applications/Docker.app (pgrep -f '/Applications/Docker.app')
• Exact process names: com.docker.backend, com.docker.build, com.docker.krun, com.docker.vpnkit, com.docker.virtualization, vpnkit
• Hung CLI clients: pgrep -x docker

Critical hazard: a naive pgrep -f docker matches the string docker in this script's own name and command line, so docker-nuke would kill itself mid-run. Matching is therefore anchored to the app bundle path and exact process names, and $$ / $PPID are always filtered from the result set. pgrep -f docker must never be used.

Interface

Flag	Effect
-f, --force	Skip the confirmation when Docker looks healthy
-n, --no-restart	Kill only, leave Docker down
--dry-run	Report what would be killed and dumped; change nothing
--deep	Also stop root launchd helpers (com.docker.vmnetd); prompts for sudo
-h, --help	Usage

Exit codes:

• 0 — Docker killed and (unless --no-restart) confirmed responsive again
• 1 — daemon did not come back within the restart timeout
• 2 — aborted by user at the healthy-daemon confirmation

Constants

HEALTH_TIMEOUT=6      GRACEFUL_WAIT=8      TERM_WAIT=5
RESTART_TIMEOUT=90    POLL_INTERVAL=2      SAMPLE_DURATION=2
SAMPLE_TIMEOUT=10     DUMP_RETENTION=10    LOG_TAIL_LINES=2000
DUMP_ROOT="$HOME/.local/state/docker-nuke"

Implementation notes

• Bash. timeout is available via coreutils but must not be assumed — provide a run_timeout helper that uses timeout/gtimeout when present and falls back to a background-process-and-poll implementation.
• Care with set -euo pipefail: pgrep exits non-zero when it matches nothing, which is a normal condition here, not an error.

Verification plan

Docker is healthy with 27 running containers, so testing is staged:

1. Safe, non-disruptive: --help, --dry-run, health check on a healthy daemon, the confirmation guard, dump creation and contents, retention pruning.
2. Disruptive: a real end-to-end nuke. Bounces all 27 containers. Requires explicit user go-ahead before running.