Docker Cleanup Assistant

Project roadmap

1. 01

   Define what counts as unused

   ~1.5h

   Write README.md: the categories (containers stopped for over N days, dangling images, images not used by any container and older than N days, volumes not attached to any container, unused networks, and build cache), the protection rules (a keep label such as cleanup.keep=true, and name patterns in a config file), the command options (--host user@server, --older-than, --dry-run and --yes for automation), and the log format. Done when: README.md defines every category, rule and option.

2. 02

   List unused resources

   ~2.5h

   For each category, collect items with their id, name, size and age, using docker commands with --format and --filter, or the Engine API with curl --unix-socket /var/run/docker.sock (for example /containers/json?all=true and /system/df). Parse with awk into one table format, convert sizes to bytes, and apply the age and protection rules. Done when: listing on a machine with test containers, images and volumes shows exactly the unused, unprotected items with sizes.

3. 03

   Let the user choose

   ~2h

   Show the candidates numbered and grouped by category, with the total space each group would free. Let the user pick items (such as 1,3,5-8, a whole category, or all), then show the final list and total, and require typing yes (not just y) to continue. --dry-run shows what would be removed and stops there. Done when: removals only happen after an explicit yes, and dry runs never delete anything.

4. 04

   Remove and log

   ~1.5h

   Remove the chosen items in a safe order (containers first, then images, volumes and networks), checking each is still unused right before deleting it, since things may have changed. Continue after a failure, record every result (removed, skipped or failed with the reason and size) in a log file, and print the space actually freed. Done when: the log records each removal, and an item that started being used in the meantime is skipped.

5. 05

   Clean remote servers over SSH

   ~1.5h

   With --host, run the listing and removal commands on another server over ssh -o BatchMode=yes, reusing one connection for all commands (ControlMaster). Keep the choice and confirmation on your own machine. Check that Docker is available on the remote host first. Done when: cleaning a remote test server works with the same safety steps.

6. 06

   Handle errors and automation

   ~1h

   Handle Docker not running, no permission to use the socket, and nothing to clean (a friendly message). With --yes plus explicit categories, allow unattended runs (for example from cron), still respecting protection rules and logging. Use a lock file so two runs never overlap. Done when: each error prints a clear message, and unattended runs work.

7. 07

   Test it safely

   ~2h

   Write bats-core tests using a fake docker command placed first on the PATH that returns prepared output and records what would be removed, so no real resources are touched: age and protection rules, selection parsing, the confirmation requirement, dry runs, and the removal order. Also do one real run in a disposable Docker setup. Run shellcheck. Done when: the tests pass, and shellcheck reports no warnings.

Resources

• DocsDocker: prune unused objects
• Docsdocker system df reference
• DocsDocker Engine API
• DocsGNU Awk user's guide
• Docsbats-core documentation