Our Docker registry ran out of disk space the other day. After a bit of investigation into what was filling up the disk, I found that one of the issues was our CI creating an image for every development branch, which were not cleaned up when the branch was deleted.

After a very quick scan of the interwebs for deleting images and tags from a Docker registry, I found the v2 registry API() that can be used for doing such a thing. Unfortunately, the way I figured out was a little long winded. I had to get the list of registries (images) in the registry (using GET /_catalog), then get the tags for those registries (GET /<image>/), then download the manifest for the image tag (GET /<image>/manifests/<tag>), create a digest for it (a sha256sum), then finally request the delete (DELETE /<image>/manifests/sha256:<digest>). Phew.

Wanting to remove quite a few images, I thought I would write a bit of scripting to help me out. I initially downloaded the list of tags for the problem image, and then used while, read and curl to iterate through them and do the required steps for deletion. Being a little cautious, I tried it only on a few and it seemed to work. Going on to the registry docker container, I was then able to garbage collect() the blobs related to those tags into oblivion to free the first bit of space.

Being happy with the start, I decided I needed a little more power, so set about creating a script for the whole process, from get the list of images and tags, selecting which ones to delete, all the way to the deletion.

I started out writing a bash script and then I thought about how easy it would be with Javascript, as it is built for async and dealing with web requests.

The end result was clean-docker-registry, a small npm-installable command.

clean-docker-registry [-a ] [-u ]  []

           Registry URL
        eg ${process.argv0} https://registry.example.com/v2
     []        Registry to fetch the tags for and delete tags from.
                         If not given, the tags for all (the first 100)
                         registries will be fetched and listed
     -a   Authorization header to include in requests
     -u            Username for BASIC authentication (will prompt for
                         password)

The command allows you to connect to a registry, and authenticate with either BASIC auth, or an Authorization header. It will download the list of images on the registry and allow you select the images to delete. Once selected, it will confirm before deleting them from the registry.