How to Guide: Setup Bitcoin running on Umbrel to store the blockchain on an external SSD.

Umbrel Bitcoin Node: Store Blockchain Data on an External SSD

Unsupported workaround for UmbrelOS. Test after every UmbrelOS or Bitcoin app update.

This keeps Umbrel and its other apps on the internal drive, while moving only Bitcoin’s large data directory to an external SSD.

Paths used

Umbrel Bitcoin host data path:
/home/umbrel/umbrel/app-data/bitcoin/data

External SSD mount:
/home/umbrel/umbrel/external/bitcoin

Container paths:
/data                 → host data path
/data/bitcoin         → Bitcoin Core blockchain data

1. Confirm the external drive is mounted

findmnt -T /home/umbrel/umbrel/external/bitcoin

Expected source:

/dev/sdc1

Do not continue unless the external drive is mounted and has enough free space.

2. Stop Bitcoin

umbreld client apps.stop.mutate --appId bitcoin

sudo docker ps --filter name=bitcoin \
  --format 'table \t'

The Docker list should be empty.

3. Copy existing Bitcoin data to the SSD

sudo rsync -aHAX --numeric-ids --info=progress2 \
  /home/umbrel/umbrel/app-data/bitcoin/data/ \
  /home/umbrel/umbrel/external/bitcoin/

Verify without changing anything:

sudo rsync -aHAXn --numeric-ids --itemize-changes \
  /home/umbrel/umbrel/app-data/bitcoin/data/ \
  /home/umbrel/umbrel/external/bitcoin/

sudo du -sh \
  /home/umbrel/umbrel/app-data/bitcoin/data \
  /home/umbrel/umbrel/external/bitcoin

The dry run should show no changes, and both directories should be roughly the same size.

Do not delete the original yet.

sudo test ! -e /home/umbrel/umbrel/app-data/bitcoin/data.internal-backup \
  && echo 'Backup name is free'

sudo mv -T \
  /home/umbrel/umbrel/app-data/bitcoin/data \
  /home/umbrel/umbrel/app-data/bitcoin/data.internal-backup

sudo ln -sT \
  /home/umbrel/umbrel/external/bitcoin \
  /home/umbrel/umbrel/app-data/bitcoin/data

Verify:

ls -ld /home/umbrel/umbrel/app-data/bitcoin/data
readlink -e /home/umbrel/umbrel/app-data/bitcoin/data
findmnt -T /home/umbrel/umbrel/app-data/bitcoin/data

Expected:

data -> /home/umbrel/umbrel/external/bitcoin
source: /dev/sdc1

5. Start Bitcoin and verify its live filesystem

Start Bitcoin from Umbrel’s UI, or:

umbreld client apps.start.mutate --appId bitcoin

Then check:

sudo docker exec bitcoin_app_1 sh -c 'df -h /data/bitcoin'
sudo docker logs --tail 20 bitcoin_app_1

/data/bitcoin must report the external SSD filesystem. Logs should show Bitcoin loading its existing chain and then UpdateTip sync lines.

6. Reboot test

Stop Bitcoin, reboot Umbrel, start Bitcoin again from Umbrel’s UI, and repeat:

findmnt -T /home/umbrel/umbrel/app-data/bitcoin/data
sudo docker exec bitcoin_app_1 sh -c 'df -h /data/bitcoin'

Only after this passes should the internal rollback copy be removed:

sudo rm -rf -- \
  /home/umbrel/umbrel/app-data/bitcoin/data.internal-backup

After every update or reboot

readlink -e /home/umbrel/umbrel/app-data/bitcoin/data
findmnt -T /home/umbrel/umbrel/app-data/bitcoin/data

It must resolve to the external SSD and show /dev/sdc1.

Important notes

  • Do not use /etc/fstab as the persistence mechanism on current UmbrelOS; system changes can be discarded by updates.
  • Do not uninstall/reinstall Bitcoin to perform this migration.
  • Do not delete the internal copy until Bitcoin has resumed from the external drive and survived a reboot.
  • If Bitcoin ever appears to start from block zero, stop it immediately and re-check the symlink and mount source.