Apps Portability with UmbrelOS
Learn how to make your UmbrelOS apps portable by storing them on an encrypted external drive, ensuring secure data and seamless transitions to a new mini PC without reinstalling or reconfiguring.
Table of Content
- Data Security with UmbrelOS
- Apps Portability with UmbrelOS
In today's world where data security is non-negotiable, UmbrelOS paired with a mini PC and an encrypted external drive offers a robust solution for safeguarding your private cloud. Our previous article, Data Security with UmbrelOS, detailed how to protect your data using this setup.
Now, we’re taking it a step further by exploring how to enhance flexibility through app portability. By storing your apps and their data on the same encrypted external drive, you can effortlessly transition to a new mini PC—whether due to hardware failure or the need for a performance upgrade—saving valuable time on data transfers, app reinstallation, and reconfiguration.
Understanding the UmbrelOS App File System
In UmbrelOS, all apps are stored in the /home/umbrel/umbrel/app-data directory. When you install a new app, UmbrelOS creates a dedicated folder for it within this directory. This folder’s location is defined by a variable called APP_DATA_DIR, which holds the app’s configurations, data, and related services, such as databases. Each app runs as one or more Docker containers—lightweight, isolated environments that power the app’s functionality. The configuration for these containers is stored in a file called docker-compose.yml within the app’s folder. This file uses relative paths, such as {APP_DATA_DIR}/data, to reference the app’s data files. Understanding this structure is crucial for making your apps portable, as it shows where and how app data is stored.
Moving Apps to an External Drive
Relocating your apps and their data to an external drive might seem challenging, but there’s a straightforward way to achieve it without disrupting UmbrelOS. One approach could be to modify the APP_DATA_DIR variable to point to a new location on the external drive. However, this is not recommended, as UmbrelOS could reset this variable during system restarts or upgrades, which could break your apps.
A better solution is to use a Linux feature called a bind mount. By mounting the UmbrelOS app directory (/home/umbrel/umbrel/app-data) to a directory on your external drive, such as /mnt/extdrive/apps, you redirect all app-related files to the external drive. In this setup, any file or folder created or accessed in /home/umbrel/umbrel/app-data is physically stored on the external drive. This approach is seamless because it requires no changes to UmbrelOS configurations or the apps’ docker-compose.yml files, ensuring that future updates to UmbrelOS or its apps work without issues.
Setting Up Apps on an External Drive
To make your UmbrelOS apps portable by storing them on an encrypted external drive, follow these steps carefully. This process involves backing up your apps, copying them to the external drive, and redirecting UmbrelOS to use the new storage location. By the end, your apps and their data will be ready to move to another mini PC with ease.
Prerequisites:
- Ensure your external drive is mounted at /mnt/extdrive. You can verify this by running df -h in the terminal and checking for /mnt/extdrive.
- Back up critical data before proceeding, as errors could affect app functionality.
We'll need to use the terminal:
- Grants root access to the operating system.
sudo -i- Before making changes, stop all running apps to prevent data corruption. In the UmbrelOS web interface, navigate to the “Apps” section and stop each app.
- Always back up your apps to avoid data loss. Create a backup directory and move the current app data there.
mkdir -p /home/umbrel/umbrel/app-data-backup
mv /home/umbrel/umbrel/app-data/* /home/umbrel/umbrel/app-data-backup/- Copy the backed-up app data to a new directory on the external drive. The -a flag ensures all files, including permissions, are preserved.
mkdir -p /mnt/extdrive/apps
cp -a /home/umbrel/umbrel/app-data-backup/. /mnt/extdrive/apps/- Verify the copy by listing the files on the external drive.
ls -l /mnt/extdrive/apps- Use a bind mount to redirect the UmbrelOS app directory to the external drive.
mount --bind /mnt/extdrive/apps /home/umbrel/umbrel/app-data- Verify the mount by checking that the app folders are listed.
ls -l /home/umbrel/umbrel/app-data- The bind mount created above is temporary and will reset on reboot. To make it permanent you have two options:
- If you've followed the article Data Security with UmbrelOS, you can add the bind mount command right after the mount operation of the encrypted external hard drive in the script inside the unlock_disk.sh file
- Edit the /etc/fstab file and test the fstab configuration to ensure it works. If no errors appear, the mount is configured correctly.
echo "/mnt/extdrive/apps /home/umbrel/umbrel/app-data none bind 0 0" >> /etc/fstab
mount -a- Start all apps. In the UmbrelOS web interface, check that all apps are running correctly and their data is accessible. Test key app functionalities to confirm everything works as expected.
- Only after verifying that all apps are functioning correctly, remove the backup directory to free up space.
rm -r /home/umbrel/umbrel/app-data-backupCaution: Do not delete the backup until you’re certain the external drive setup is working.
Your UmbrelOS apps and their data are now stored on the external drive, making them fully portable.
Transferring Your Apps to a New UmbrelOS Instance
With your UmbrelOS apps and data stored on an encrypted external drive, moving them to a new mini PC is straightforward, allowing you to maintain your setup without reinstalling or reconfiguring apps. This section guides you through transferring the external drive to another mini PC running UmbrelOS, ensuring a smooth transition.
Prerequisites:
- The original mini PC, which was running UmbrelOS with the external drive, is powered off, and the drive has been safely ejected.
- The new mini PC is already running UmbrelOS. Verify that it’s the same version as the original mini PC to avoid compatibility issues.
- You have administrative access to the new mini PC’s terminal.
- On the new mini PC, make sure there no apps installed.
Back to the terminal:
- Grants root access to the operating system.
sudo -i- Connect the external drive to the new mini PC. If the drive is encrypted, you can decrypt and mount it following the steps outlined in our Data Security with UmbrelOS article. Ensure the drive is mounted at /mnt/extdrive. The apps should be located at /mnt/extdrive/apps.
- Redirect the UmbrelOS app directory to the external drive using a bind mount as described above.
mount --bind /mnt/extdrive/apps /home/umbrel/umbrel/app-data- Verify the mount by listing the app folders.
ls -l /home/umbrel/umbrel/app-data- All apps location on the external hard drive, automatically appear on the UmbrelOS web interface with status "not running". Start all apps.
systemctl restart umbrel- In the UmbrelOS web interface, confirm that all apps are running and their data is intact. Test key functionalities to ensure everything works as expected.
Important Note: While this process is generally seamless, some apps may have configurations tied to the specific UmbrelOS instance (e.g., instance name or network settings). If an app doesn’t work as expected, check its configuration files in /mnt/extdrive/apps/[app-name] or consult the app’s documentation for instance-specific settings. You may need to adjust these manually.
Congratulations! Your apps and data are now fully operational on the new mini PC, with no need for reinstallation or extensive reconfiguration.
Flexibility with UmbrelOS
By leveraging an encrypted external drive, you’ve unlocked a powerful way to secure and mobilize your UmbrelOS apps. From understanding the app file system to setting up a bind mount and transferring your setup to a UmbrelOS instance, this guide has walked you through creating a portable, secure, and resilient UmbrelOS environment. This approach not only safeguards your data but also saves time and effort when upgrading hardware or recovering from failures, all without the hassle of reinstalling or reconfiguring apps.
With your apps now ready to move seamlessly between devices, you’re in full control of your private cloud. We encourage you to test this setup, explore additional backup strategies, and share your experiences with the UmbrelOS community.
👀 Umbrel
