getumbrel / umbrel-apps

Umbrel App Framework If you can code in any language, you already know how to develop an app for Umbrel. There is no restriction on the kinds of programming languages, frameworks, or databases that you can use. Apps run inside isolated Docker containers, and the only requirement is that they should serve a web-based UI. > Some server apps might not have a UI at all. In that case, the app should serve a simple web page listing the connection details, QR codes, setup instructions, and anything else needed for the user to connect. The user is never expected to have CLI access on Umbrel. To keep this document short and easy, we won't go into the app development itself, and will instead focus on packaging and testing an existing app. Let's jump into action by packaging BTC RPC Explorer, a Node.js based app, for Umbrel. There are 4 steps: • 🛳 Containerizing the app using Docker • ☂️ Packaging the app for umbrelOS • 🛠 Testing the app on umbrelOS • Test using an umbrelOS development environment on your local machine • Test using umbrelOS running on a physical device • 🚀 Submitting the app ___ • 🛳  Containerizing the app using Docker 1\. Let's start by cloning BTC RPC Explorer on our system: 2\. Next, we'll create a in the app's directory: A good Dockerfile: • [x] Uses a lightweight base image - this results in less storage consumption and faster app installs. • [x] Uses multi-stage builds for smaller image size. • [x] Excludes development files in the final image. • [x] Has only one service per container. • [x] Doesn't run the service as root. • [x] Uses remote assets that are verified against a checksum. • [x] Results in deterministic image builds. 3\. We're now ready to build the Docker image of BTC RPC Explorer. Umbrel supports both 64-bit ARM and x86 architectures, so we'll use to build, tag, and push multi-architecture Docker images of our app to Docker Hub. This way, the same app can be installed on both ARM and x86 devices. > You need to enable "experimental features" in Docker to use . ___ • ☂️  Packaging the app for umbrelOS 1\. Let's fork the getumbrel/umbrel-apps repo on GitHub, clone our fork locally, create a new branch for our app, and then switch to it: 2\. It's now time to pick an ID for our app. An app ID should only contain lowercase alphabetical characters and dashes, and should be human readable and recognizable. For this app we'll go with . We need to create a new subdirectory in the apps directory with the same name as our app ID and move into it: 3\. Within the app's directory, we'll now create the skeleton for our app with the following files: • - Used to start and stop your app's Docker containers • - An app manifest file so that Umbrel knows the name and version of the app • - A shell script to export environment variables used within and share with other installed apps We'll now create a file in this directory to define our application. > New to Docker Compose? It's a simple tool for defining and running Docker applications that can have multiple containers. Follow along with the tutorial, we promise it's not hard if you already understand the basics of Docker. Let's copy-paste the following template into a text editor and modify it according to our app. Our app manifest YAML file tells Umbrel details about our app such as the name, description, dependencies, port number to access the app, etc. > There are currently two manifest versions: and . Version is the basic version and is sufficient for most apps. However, if your app requires the use of hooks (scripts that are run at different stages of the app lifecycle), you need to use version . Hooks allow you to perform custom actions at different stages of the app's lifecycle, such as before the app starts (pre-start), after the app installs (post-install), and more. If your app doesn't need to use hooks, you can stick with manifest version . When submitting a new app, leave the and fields empty. Use the following values: The section within the app manifest gives Umbrel a list of app IDs that must be already installed in order for the user to install BTC RPC Explorer and also function. The shell script is a simple script to export environmental variables that your can read. These environment variables are also accessible when other apps start through their files. Most applications will not require this feature. If we (for example) wanted to share BTC RPC Explorer's Address API with other apps; that would look like this: 4\. For our app, we'll update with , with , with , and with . Since BTC RPC Explorer doesn't need to store any persistent data and doesn't require access to Bitcoin Core's or LND's data directories, we can remove the entire block. > The digest is a unique, immutable identifier for the Docker image. This will supersede the tag in the file. The reason we want to pull an image by its digest, is that we are guaranteed to get the exact same image every time, and this image will be the same image that was tested and verified to work on umbrelOS. It is important to make sure that this digest is the multi-architecture digest, and not the digest for a specific architecture. BTC RPC Explorer is an application with a single Docker container, so we don't need to define any other additional services (like a database service, etc) in the compose file. > If BTC RPC Explorer needed to persist some data we would have created a new directory next to the file. We'd then mount the volume in the to make the directory available at inside the container. Updated file: 5\. Next, let's set the environment variables required by our app to connect to Bitcoin Core, Electrum server, and for app-related configuration (as required by the app). So the final version of would be: 6\. We're pretty much done here. The next step is to commit the changes, push it to our fork's branch, and test out the app on Umbrel. ___ • 🛠  Testing the app on umbrelOS 🚨 This is the current…