Intro

Umbrel is a great app that lets you build and own a personal server. Think of having your own fleet of AWS or GCP or Azure cloud services at your doorstep(literally at your doorstep).

In this blog, I will talk about my experience while publishing an app(Trillium Note) on the Umbrel App Store and also the mistakes to avoid while doing this.

Pre-Requisites

1. Love for Open-source(must have)
2. Little Software development knowledge
3. Some familiarity with Docker(optional, I didn't have any)
4. Patience(a hell lot!)

Step-by-Step Guide

1 - Find the app you like which is not in Umbrel Store.

In my case, it was AppFlowy(an Open-source Notion Alternative).

(Mistakes to avoid)

But it was a huge mistake for me to think that I can take an app still in its Development stage and try and publish it. Because many things broke and in the process of fixing those I ended up being discouraged and quit altogether.

(Solution)

Instead, find an app that is well in the production stage and has a community where you can look up for help if stuck(which you will trust me).

Been there, done that. I chose "Trilium Note" next. I didn't quit.

2 - Dockerize your chosen app.

You have to dockerize the app you want to see in the Umbrel App Store. To dockerize, you will have to make a dockerfile according to the one-page doc published by Umbrel Team.

(Mistakes to avoid)

Don't just start writing the Dockerfile from scratch(like I did). You will hit a lot of roadblocks also it's a very inefficient way.

(Solution)

Instead, check if the app already has a Dockerfile and also check if it has a docker image in the docker hub which supports ARM and x86 architecture(a requirement for an app that has to be installed in the Umbrel App Store). If you followed step 1 then best case it will be true for your app, otherwise, you can go ahead and make a Dockerfile from scratch.

Note: Umbrel entirely works on Docker images in the background which is a good thing but also bad. We will discuss these aspects in another blog.

3 - Fork & Clone Umbrel-App repo to your machine.

If you followed steps 1 & 2 correctly you have your docker image already. Now it's just a matter of minutes before you see your chosen app running on Umbrel(hopefully). Just fork the umbrel-app repo in your GitHub and then clone the forked repo in your local machine.

Now the steps from here are simple but crucial.

3.1 - Make a directory inside the cloned umbrel-app repo.

3.2 - Make 3 files with the name as shown below.

3.3 - Configure the files according to the one-page doc by Umbrel.

(Mistakes to avoid)

Don't just blindly follow the one-page doc here(it is a bit outdated). I did that and faced a lot of challenges.

(Solution)

Instead, look for an app directory that is already hosted in the umbrel app store and closely uses the things/resources that your app is going to use and try and replicate it. In my case, it was Plex.

I was facing an issue while running the app as it was supposed to be run as a server and not an app. I found plex was also running as a server on the Umbrel store and just replicated their files and made some changes and bam!!! the app magically started running.

4 - Install Umbrel on your machine or VM for running the app.

If you are running Ubuntu or Debian system you can directly install and run Umbrel with just one command:

curl -L https://umbrel.sh | bash

If not, you can run a VM with Ubuntu. Then install Umbrel and follow the required steps to install your app on Umbrel and run it.

(Mistakes to avoid)

If you have arrived here and something is not working don't panic(like I did) and especially don't quit. It's just a matter of a few lines of code here and there and everything will be sorted out.

(Solution)

Instead, check for the error code that is being thrown. I faced a number of weird errors whose answers were not even on Google or Stackoverflow. But if you followed step 3's hack to configure then this step will be a breeze.

5 - Let's take a test drive of the newly installed app.

Now we mainly have to check if all the functions that were working fine in the machine actually do work here or not.

(Mistakes to avoid)

Don't get overwhelmed by this process(like I did). Some features like data storage and login/signup features have to work properly otherwise it will be chaos.

(Solution)

One thing you can do is:

• make some changes inside the app.
• then try to stop and re-run the Umbrel app

cd umbrel/scripts
./stop

After fully stopped inside the same path:

./start

• and then check if the changes are still intact or not. i.e. current state == previous state

If the changes are there then you are good to go ahead else you have issues with the mounting of storage location in the Dockerfile or in the docker-compose file(do have a look there).

6 - Finally the moment arrived.

Congratulations. You made it till here. You can now submit your app to the Umbrel App Store. You are just a pull request away. Just follow the one-page doc for this.

(Mistakes to avoid)

A cleanup of the commit messages will save you a lot of time and effort before opening the PR. Don't be that guy who opens a PR with this type of commit message.

(Solution)

Instead, keep your commit messages up to the point. If you have already committed so many commits like me then do not worry you can always squash commits in Github before opening a PR.

Also, gather an icon in SVG format so that the app will be displayed properly in the Umbrel App Store. Some screenshots of the app are also a great finish touch that should be added to the PR itself.

Outro

I hope this blog helps you publish your favorite app in the Umbrel App Store. It took me nearly 3 weeks to publish my first app and the PR and I wrote this blog to help someone like me in those tough times. I gave up every day but didn't quit and at last, I was able to push an app into the Umbrel App Store.

Umbrel is really a cool product that takes takes the power from the big companies and provides that in the consumer's hands which is really a once-in-a lifetime thing. This is what the Apple did with IBM. Umbrel is still in its very early stage and it really has the potential to transition into something. I have really all-in in Umbrel and I have already set up Umbrel in my home and using it as a personal server replacing my google drive altogether.

Best of Luck.

Pk. Signing off.