Migration of Docker root directory

[Muhammad-Ahmed-Zia]

What is the proper procedure for migrating the Docker root directory to external storage without breaking CasaOS App Management?

By default, CasaOS installs all Docker containers, images, and volumes to the host's primary root drive (typically /var/lib/docker). For users running CasaOS on single-board computers (like a Raspberry Pi) or small boot SSDs, this partition quickly runs out of space.

If we want to change the global Docker root directory (data-root) to a mounted external storage drive (e.g., /media/devmon/HDD1), what is the safest and most compliant procedure to ensure that casaos-app-management completely recognizes the transition and successfully tracks existing/new containers?

[SufyExpert]

Migrating the Docker daemon's storage root requires stopping the Docker and CasaOS engine components, moving the existing assets safely, and updating the Docker daemon schema.

Follow this step-by-step procedure via CLI:

1. Stop CasaOS and Docker Services

Before moving any data, you must halt all write operations by stopping both CasaOS services and the underlying Docker engine:

sudo systemctl stop casaos-app-management.service
sudo systemctl stop casaos.service
sudo systemctl stop docker.service
sudo systemctl stop docker.socket

2. Configure Docker to use the New Path

Create or modify the Docker daemon configuration file located at /etc/docker/daemon.json. Add or update the "data-root" key to point to your mounted external drive:

{
  "data-root": "/media/devmon/HDD1/docker-root"
}

3. Migrate Existing Docker Data

Sync your existing data, containers, layers, and volumes over to the new directory while preserving all original file permissions and timestamps:

# Ensure the target directory exists
sudo mkdir -p /media/devmon/HDD1/docker-root

# Sync the data safely
sudo rsync -aP /var/lib/docker/ /media/devmon/HDD1/docker-root/

4. Start the Engines and Verify

Reload the system configurations and start the services back up:

sudo systemctl daemon-reload
sudo systemctl start docker.service
sudo systemctl start casaos.service
sudo systemctl start casaos-app-management.service

Verify that Docker is successfully operating out of the new directory by checking the execution layout:

docker info | grep "Docker Root Dir"

(It should accurately print: Docker Root Dir: /media/devmon/HDD1/docker-root)

5. Clean Up Old Assets

Once you have verified that your Web UI is active and all of your CasaOS apps spin up properly with their data intact, you can safely remove the legacy storage directory to reclaim space on your primary drive:

sudo rm -rf /var/lib/docker