Skip to content

Free space on the Docker host

Use this procedure to remove replaceable Docker artifacts from docker.local.isabelsoler.es. Keep application directories, backups, volumes, stopped containers, and local builds unless their removal is separately approved. Docker's reclaimable volume count does not identify disposable data.

Measure usage and record service state

Connect with the existing SSH access:

    ssh igresc@docker.local.isabelsoler.es
    df -hT /
    df -i /
    docker system df
    docker ps -a --format 'table {{.ID}}\t{{.Names}}\t{{.Status}}'
    docker buildx ls
    du -x -h --max-depth=1 /home/igresc /var/cache /var/log /tmp 2>/dev/null
    journalctl --disk-usage

Treat unprivileged du totals as incomplete where directories are inaccessible. Do not print credentials, environment files, resolved Compose configuration, or unfiltered container inspection output.

On a host with containers, record each container's image, state, health, start time, and restart count. Retain the volume and network lists for comparison:

    docker inspect --format '{{.Id}} {{.Name}} {{.Image}} {{.State.Status}} {{if index .State "Health"}}{{(index .State "Health").Status}}{{else}}none{{end}} {{.State.StartedAt}} {{.RestartCount}}' $(docker ps -aq)
    docker volume ls -q
    docker network ls -q

Remove reviewed downloaded images

  1. List untagged images and inspect each proposed image by ID:
 docker image ls --filter dangling=true --no-trunc --format '{{.ID}}'
 docker image inspect --format '{{.Id}} {{json .RepoTags}} {{json .RepoDigests}}' '<reviewed-image-id>'
  1. Select images with no tags, at least one registry digest, and no reference from any container, including stopped containers. Preserve images without a registry digest because they may be the only copy of a local build.
  2. Save each selected image ID and its exact registry digest in a cleanup record. Confirm that the registry still provides that manifest:
 docker manifest inspect '<repository>@sha256:<digest>' >/dev/null

If the lookup fails, retain the image. Docker Hub rate limits can prevent verification even when a manifest exists. Retry after access recovers.

  1. Immediately before removal, recheck the tags, digests, and container references. Remove only the reviewed image ID:
 docker image rm --no-prune '<reviewed-image-id>'

Keep --no-prune to prevent removal of unreviewed parent images. Do not add --force if Docker refuses removal. Resolve the changed reference or retain the image.

Use Docker image removal for individual targets. Broad system or volume pruning can remove containers or persistent data. Leave tagged images in place to preserve cached deployment and rollback versions.

Remove old build cache

Confirm the builder name with docker buildx ls. For the host's default builder, remove unused cache that has not been used for seven days:

    docker buildx prune --builder default --force --filter until=168h

The Buildx prune documentation defines until by last use. The installed Docker CLI routes docker builder prune through Buildx, whose available flags differ from the older CLI. Use the installed command's --help before adapting examples.

Verify space and recover artifacts

Repeat the disk and Docker usage checks. Compare every container's state, health, start time, restart count, and image with the saved baseline. Confirm that container IDs, volumes, and networks are unchanged. A successful cleanup increases filesystem availability without restarting workloads.

If a removed image is needed again, restore its recorded version:

    docker pull '<repository>@sha256:<digest>'

Pulling by digest preserves the version. Rebuild deleted cache from the original build inputs. Do not restart applications as part of cache recovery.

docs/runbooks/docker-disk-cleanup.md