Btrfs is a copy-on-write filesystem that supports many advanced storage technologies, making it a good fit for Docker. Btrfs is included in the mainline Linux kernel. Docker’s btrfs storage driver leverages many Btrfs features for image and container management. Among these features are block-level operations, thin provisioning, copy-on-write snapshots, and ease of administration. Most notably, Docker can use the BTRFS snapshot technology to create the overlay filesystems.

On my DIY Debian NAS I have decided to use the BTRFS storage driver of Docker for the Docker containers. I’ve used the guide from the Docker documentation site ( https://docs.docker.com/engine/storage/drivers/btrfs-driver/ ) and adjusted it to my needs. I’ve created a big BTRFS storage volume and created on that volume multiple subvolumes for different purposes. One of those subvolumes (@docker) will be used as the subvolume for the Docker containers.

I’ve mounted the BTRFS storage volume on /storage. First, we will create a subvolume named @docker:

btrfs subvolume create /storage/@docker

After creating the subvolume we need to stop Docker and copy the current docker directory to a backup directory, as we still need the contents of that directory.

systemctl stop docker
sudo cp -au /var/lib/docker /var/lib/docker.bk
sudo rm -rf /var/lib/docker/*

Mount the subvolume on the docker directoy and add the mount to the /etc/fstab:

sudo mount -t btrfs -L <label of your BTRFS volume> -o subvol=@docker,noatime /var/lib/docker

echo "LABEL=<label of your BTRFS volume> /var/lib/docker btrfs subvol=@docker,defaults,noatime 0 0" >> /etc/fstab

And copy the contents of the docker directory back:

sudo cp -au /var/lib/docker.bk/* /var/lib/docker/

Configure Docker to use the btrfs storage driver. This is required even though /var/lib/docker is now using a BTRFS filesystem. Edit or create the file /etc/docker/daemon.json. If it is a new file, add the following contents. If it is an existing file, add the key and value only, being careful to end the line with a comma if it isn’t the final line before an ending curly bracket (}).

{
  "storage-driver": "btrfs"
}

Start the docker service and check if the BTRFS storage driver is being used:

systemctl start docker

docker info

Server:
 ...
 Server Version: 28.2.2
 Storage Driver: btrfs
  Btrfs:
 ...

And we’re done! Docker will now make use of the BTRFS filesystem symantics!

In this example, I didn’t use any of the other mount options for the BTRFS filesystem, but you can easily add things like compression or auto defragmentation to the Docker subvolume by adding those options to the mount options. See https://btrfs.readthedocs.io/en/latest/btrfs-man5.html for the available mount options.