For People In A Hurry: How To Mount Docker Storage On An External Drive

README.md

Note

This is a quick reference guide on how to set up your Docker usage such that docker images are stored on an external drive.

Why Do This?

If, like me, you are constantly having to worry about limited disk space on your host device where you doing your development, it would likely benefit you to have the images stored separately.

Warning

This guide makes a loose assumption that your external drive will be mounted on the following:

• /home/$USER/Mounts

Modify the above file path based on where you have actually mounted your external drive. This guide aims to shift docker storage onto external drive via the following 2 directories:

• /home/$USER/Mounts/docker
• /home/$USER/Mounts/containerd

Instructions 📘

🔵 STEP 1 — Verify External Drive

Check mount:

df -h
mount

Confirm external path exists:

ls /home/$USER/Mounts

🔵 STEP 2 — Stop Docker + containerd COMPLETELY

Stop everything:

sudo systemctl stop docker.socket
sudo systemctl stop docker.service
sudo systemctl stop containerd

Kill leftovers:

sudo pkill -9 dockerd
sudo pkill -9 containerd

Verify nothing remains:

ps aux | egrep "docker|containerd"

Expected:

Only grep process visible

🔵 STEP 3 — Clear Runtime State

sudo rm -rf /run/containerd/*

Why:

containerd caches runtime state avoids “still using old root” issues

🔵 STEP 4 — Create New Directories

Example:

sudo mkdir -p /home/$USER/Mounts/docker
sudo mkdir -p /home/$USER/Mounts/containerd

Set permissions:

sudo chown root:root /home/$USER/Mounts/docker
sudo chown root:root /home/$USER/Mounts/containerd

sudo chmod 711 /home/$USER/Mounts/docker
sudo chmod 711 /home/$USER/Mounts/containerd

🔵 STEP 5 — Copy Existing Docker Data (Optional)

If migrating Docker root:

sudo rsync -aHAX --numeric-ids /var/lib/docker/ /home/$USER/Mounts/docker/

If old Docker root already elsewhere:

Adjust source accordingly

🔵 STEP 6 — Copy Existing containerd Data

sudo rsync -aHAX --numeric-ids /var/lib/containerd/ /home/$USER/Mounts/containerd/

Verify sizes:

sudo du -sh /var/lib/containerd
sudo du -sh /home/user/Mounts/containerd

They should closely match.

🔵 STEP 7 — Configure Docker Root

Edit:

sudo nano /etc/docker/daemon.json

Example:

{
    "data-root": "/home/$USER/Mounts/docker"
}

Optional NVIDIA runtime example:

{
    "data-root": "/home/$USER/Mounts/docker",
    "runtimes": {
        "nvidia": {
            "args": [],
            "path": "nvidia-container-runtime"
        }
    }
}

🔵 STEP 8 — Configure containerd Root

Edit:

sudo nano /etc/containerd/config.toml

Find:

root = "/var/lib/containerd"

Change to:

root = "/home/$USER/Mounts/containerd"

Leave state unchanged:

state = "/run/containerd"

🔵 STEP 9 — Restart Services CLEANLY

Reload systemd:

sudo systemctl daemon-reexec
sudo systemctl daemon-reload

Start containerd FIRST:

sudo systemctl start containerd

Then Docker:

sudo systemctl start docker

🔵 STEP 10 — Verify Migration

Check Docker:

docker images
docker ps -a

Verify image(s) still exists.

Check Docker root:

docker info | grep "Docker Root Dir"

Expected:

/home/$USER/Mounts/docker

Check containerd root:

containerd config dump | grep root

Expected:

/home/$USER/Mounts/containerd

🔵 STEP 11 — Confirm Old Paths Are NOT Used

Check for active use:

sudo lsof +D /var/lib/containerd
sudo lsof +D /var/lib/docker

If no output:

Safe to remove old directories

🔵 STEP 12 — Remove Old Storage (ONLY AFTER VALIDATION)

Example:

sudo rm -rf /var/lib/containerd
sudo rm -rf /var/lib/docker

ONLY if:

• Everything works.
• Images visible.
• Containers running successfully.

🟥 Looking To Undo The Above? ⬇️

Instructions 📘

sudo systemctl stop docker.socket
sudo systemctl stop docker.service
sudo systemctl stop containerd

sudo pkill -9 dockerd
sudo pkill -9 containerd

sudo rm -rf /run/containerd/*

Remove the data-root variable from /etc/docker/daemon.json:

sudo nano /etc/docker/daemon.json

Comment out the previously-added root and state variables:

sudo nano /etc/containerd/config.toml

sudo systemctl daemon-reexec
sudo systemctl daemon-reload

sudo systemctl start containerd

sudo systemctl start docker

Verify ✔️

docker images
docker ps -a

🟥 Unable to Build Docker Images (Post-Migration) ?

It could potentially be due to corrupted BuildKit bbolt database in data-root.

To fix this issue, refer to the steps below:

sudo systemctl stop docker

sudo rm -rf /home/$USER/Mounts/docker/buildkit

sudo systemctl start docker