Migrating Your Umbrel Data to a New Path or Drive Array

Umbrel is a fantastic project that has become one of my favorites in recent years. It runs on plain Linux, works well on Raspberry Pi with a pre-built image that don’t have a full-fledged server, and is incredibly easy to set up. In fact, it’s so popular that more than half of the new Lightning nodes going live on the network last year were running on Umbrel.


Under the hood, Umbrel is built on robust technology: Docker! However, this is not your standard, simple docker-compose.yml project. If you’ve tried running or editing one of the compose files, you’ll quickly notice that you’re missing a lot of environment variables, and you won’t get very far. This makes simple tasks, like moving your data to a different folder or new drive array, a bit more complicated. In this post, I’ll walk you through how to move the data folder with minimal effort.

Under the hood

First, let’s take a quick look at how things are built under the hood. Umbrel relies on a systemd script called umbrel-startup on startup. This script calls two other scripts in your Umbrel folder: script/start and script/stop. These two child scripts are responsible for exporting environment variables and calling the various compose files that orchestrate the containers Umbrel apps rely on. Directories, ports, etc. are usually defined by environment variables, which means changing the data folder location of your Umbrel is as simple as editing the systemd script that brings up the system.

To confirm the current location of your data folder, you can do a quick cat:

cat /etc/systemd/system/umbrel-startup.service

Here, our path is already non-standard (Umbrel installs in the home directory by default) and shows /mnt/umbreldata.

Let’s change it to /mnt/newdir

Note: As always, when making changes to your system, make sure you have a backup of your data and proceed with caution.

Moving to our new directory

1. Shut down all running containers.
This is quite easy.

  • Check the status of the running containers:
    systemctl status docker
    systemctl status docker.socket
    systemctl status containerd

2. Copy over the data to /mnt/newdir.
This will take some time as the entire node’s blockchain data will need to copy over! We add a few rsync arguments to make things more verbose and easily track progress.

  • Run the following command:
    rsync -azh --info=progress2 --stats --inplace /mnt/umbreldata/ /mnt/newdir

3. Edit and reload systemd.

  • Edit the umbrel-startup.service file:

  • Change the ExecStart and ExecStop lines to the following:


4. Reload then restart Docker and Umbrel.

  • Run the following commands:
    systemctl daemon-reload
    systemctl start docker
    systemctl start umbrel-startup

Wrap up!

You should now be good to go! Congratulations, you’ve successfully migrated your Umbrel data folder to a new location.