How to Check Available Space on Remote Docker and Docker Layer Caching

Introduction

This article explains how to check disk space usage on Remote Docker environments and Docker Layer Caching (DLC) volumes. Monitoring available space helps prevent build failures and manage storage effectively.

Prerequisites

A CircleCI project configured with setup_remote_docker
Basic familiarity with Docker commands

Instructions

Check Docker Layer Caching Space Usage

To view how much space is currently used on the DLC volume with Remote Docker, run this command in your job:

ssh remote-docker 'sudo df' | grep '/var/lib/docker' | awk '{print $4}'

This displays the available space in kilobytes on the Docker storage directory.

You can store this value in an environment variable for use in additional steps:

DLC_AVAILABLE_SPACE=$(ssh remote-docker 'sudo df' | grep '/var/lib/docker' | awk '{print $4}')

Check Docker Daemon Disk Usage

To see detailed information about disk space used by Docker images, containers, and volumes, use the docker system df command:

docker system df

This provides a human-readable summary showing total space, active resources, and reclaimable space for each Docker resource type.

Outcome

After running these commands, you will see disk space information for your Remote Docker environment. This helps you understand storage usage and identify when you may need to clean up cached layers or optimize your Docker images.

Additional Notes

DLC has a storage limit of 15 GiB per organization
Cached layers expire after 3 days without use
CircleCI automatically removes images when the storage limit is exceeded

Additional Resources