Skip to main content

Umbrel

Install umbrelOS on a Raspberry Pi 5

Mayank Chhabra edited this page on Mar 5 · 14 revisions

Note

umbrelOS is designed for the Umbrel Home. Support for other devices is best-effort and not guaranteed. Some features like external storage support and Migration Assistant are not available - see our feature comparison for more details.

umbrelOS can be installed on a Raspberry Pi 5 in a number of configurations. The two most common are:

Installing umbrelOS on the NVMe or USB drive

In this configuration, you will install umbrelOS directly on an NVMe drive or USB drive, which will be automatically partitioned to store umbrelOS and your data.

Note

Booting from NVMe or USB instead of a microSD card is only supported on Raspberry Pi 5 for umbrelOS 1.2.0 and later. Booting from NVMe or USB is not supported on Raspberry Pi 4. Additionally, certain NVMe drives may not be compatible with specific NVMe HATs. It is crucial to check the compatibility of your NVMe drive with the HAT you are using before proceeding. HAT manufacturers typically provide lists of compatible drives and known quality issues on their websites. Using a drive not on the compatible list may result in instability or failure to boot. Also, make sure to check the quality of your NVMe SSD, as some drives are of poor quality or have reported issues that could affect performance and reliability.

What you will need

  • Raspberry Pi 5
  • Official Raspberry Pi power supply
  • Ethernet cable
  • Either an NVMe drive + HAT or USB drive (depending on your preference)

Steps


Tip

If you have an early Raspberry Pi 5 model, you may need to update the bootloader firmware in order to be able to boot from NVMe. If this is the case, please follow the official Raspberry Pi documentation on how to update the bootloader firmware: https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#bootloader_update_stable


  1. Download the latest umbrelOS image for Rasberry Pi 5.

  2. Download Balena Etcher on your computer. It is required to flash the umbrelOS image that you downloaded in the previous step to your NVMe or USB drive.

  3. Attach your NVMe drive or USB drive to your computer. For the NVMe drive, you will need to use a USB adapter to connect it to your computer.

  4. Flash the umbrelOS image to your NVMe drive or USB drive using Balena Etcher. Once the flashing process is complete, safely eject the drive from your computer.

  5. Attach the NVMe drive or USB drive to your Raspberry Pi 5.

  6. Connect your Raspberry Pi 5 to your network using an Ethernet cable.

  7. Power on your Raspberry Pi 5 using the official Raspberry Pi power supply. Third-party power supplies often cannot deliver the required current or maintain a stable voltage, leading to system instability, microSD card corruption, and corruption or data loss on connected hard drives.

  8. And that's it! Wait for a few minutes for umbrelOS to boot up. You can access umbrelOS by navigating to http://umbrel.local on any device connected to the same network.


Warning

The boot order on your Raspberry Pi 5 is set to boot from a microSD card preferentially before booting from NVMe or USB. Make sure that you do not have a bootable microSD card inserted when booting from NVMe or USB. If you have a microSD card inserted, the Raspberry Pi 5 will boot from the microSD card instead of the NVMe or USB drive.



Installing umbrelOS on a microSD card and using an external SSD for storage


Warning

Installing umbrelOS on a microSD card is not recommended primarily because microSD cards have a limited number of write cycles. Over time, frequent read and write operations can cause the microSD card to wear out and fail, leading to system instability, data corruption, and potential data loss. Also, microSD cards generally offer lower performance and durability compared to NVMe or USB drives, which are better suited for the continuous operation required by umbrelOS. For a more reliable and long-lasting setup, it is advisable to boot from NVMe or USB storage.

In this configuration, you will install umbrelOS on a microSD card and then use a separate external SSD to store your data.

What you will need

  • Raspberry Pi 5
  • Official Raspberry Pi power supply
  • Ethernet cable
  • microSD card (32GB or larger)
  • External SSD

Steps

  1. Download the latest umbrelOS image for Rasberry Pi 5.

  2. Download Balena Etcher on your computer. It is required to flash the umbrelOS image that you downloaded in the previous step to your microSD card.

  3. Attach your microSD card to your computer (you may need a microSD card reader).

  4. Flash the umbrelOS image to your microSD card using Balena Etcher. Once the flashing process is complete, safely eject the card from your computer.

  5. Insert the microSD card into your Raspberry Pi 5.

  6. Attach your external SSD to your Raspberry Pi 5 using an available USB port.

  7. Connect your Raspberry Pi 5 to your network using an Ethernet cable.

  8. Power on your Raspberry Pi 5 using the official Raspberry Pi power supply. Third-party power supplies often cannot deliver the required current or maintain a stable voltage, leading to system instability, microSD card corruption, and corruption or data loss on connected hard drives.

  9. And that's it! Wait for a few minutes for umbrelOS to boot up. You can access umbrelOS by navigating to http://umbrel.local on any device connected to the same network.

Installieren von Apps über Comandline

3.1 Test using an umbrelOS development environment on your local machine

The umbrelOS development environment (umbrel-dev) requires a Docker environment that exposes container IPs to the host. This is how Docker natively works on Linux and can be done with OrbStack on macOS and WSL 2 on Windows.

1. Install OrbStack on macOS or WSL 2 with Docker Desktop on Windows.

2. Clone the getumbrel/umbrel repo.

From the root of the cloned repo, run the following command to view the available umbrel-dev commands:

npm run dev help

To start the development environment, run the following command:

npm run dev

Note

If this is your first time running the development environment, it may take a while to build the OS image locally on your machine.

Once initialized, umbrelOS will be accessible at http://umbrel-dev.local.

3. Copy the app's directory (with any .gitkeep files excluded) to the app-store directory on umbrel-dev.

To do this, we run the following command on our local machine:

rsync -av --exclude=".gitkeep" <path-to-your-forked-repo-on-local-machine>/btc-rpc-explorer umbrel@umbrel-dev.local:/home/umbrel/umbrel/app-stores/getumbrel-umbrel-apps-github-53f74447/

If you are asked for a password during the transfer, use the password that you set when you created your umbrelOS account.

4. Install the app.

From the umbrelOS homescreen, go to the App Store and navigate to BTC RPC Explorer. Click on the "Install" button and wait for the app to install.

You can also install the app from the command line. umbrelOS provides a web terminal that can be accessed via Settings > Advanced Settings > Terminal > umbrelOS, or you can use the umbrel-dev scripts to install the app using the umbreld RPC server:

npm run dev client -- apps.install.mutate -- --appId btc-rpc-explorer
umbreld ... # zum installeren auf dem Umbrel

 

That's it! Our BTC RPC Explorer app should now be accessible at http://umbrel-dev.local:3002

To uninstall the app, you can right-click on the app's icon on your homescreen and click on the "Uninstall" button. You can also uninstall the app using the umbrel-dev scripts:

npm run dev client -- apps.uninstall.mutate -- --appId btc-rpc-explorer

Veraltet und wohl aus früheren Versionen

Can you try again to install manually: 

~/umbrel/scripts/app uninstall tailscale

Then

~/umbrel/scripts/app install tailscale

You can replace the name of the app as it's listed here: https://github.com/getumbrel/umbrel-apps/tree/master

Let me know if any issue

Back to top