How to setup Umbrel to work with an existing bitcoind and lnd

Recently, I stumbled upon a fancy looking Umbrel OS that lets you run a Bitcoin and a Lightning Network node on your dedicated machine without hassle.

If that is what you're looking for, head straight to their Github page and follow all the instructions.

However, if you're like me and already running your own instance of bitcoind and lnd, it gets trickier.

Umbrel wasn't designed to support such setup so you will have to hack it a bit to make it work.

Fear not, I did most of the heavy lifting for you.

Please note that I may or may not maintain my fork so this tutorial may not work depending on how apart Umbrel's packages and my fork are.

First create some necessary directories for the user data and the source code:

mkdir -p ~/.umbrel/db/jwt-public-key
mkdir -p ~/source/umbrel && cd ~/source/umbrel

Then clone all the repositories (run these commands one by one):

git clone https://github.com/getumbrel/umbrel.git
git clone https://github.com/getumbrel/umbrel-dashboard.git
git clone https://github.com/mariodian/umbrel-manager.git
git clone https://github.com/getumbrel/umbrel-middleware.git

#1 Install Umbrel Dashboard

cd umbrel-dashboard
yarn

Create .env file with necessary environment variables for the package:

cat >.env <<EOL
VUE_APP_MIDDLEWARE_API_URL=http://localhost:3005
VUE_APP_MANAGER_API_URL=http://localhost:3006
EOL

Build the dashboard:

yarn build

#2 Install Umbrel Middleware

cd ../umbrel-middleware
yarn install

Set the necessary environment variables. You will have to customize the red ones, at the very least.

DEVICE_HOST should be set up to http://127.0.0.1 if you only want to run it on your local machine.

PORT=3005
DEVICE_HOST=http://bitcoin.server.com # Edit
RPC_USER=iasdf342389n*(#NNUIXWB4879SAHK1hkasdfkhjhsf # Edit
RPC_PASSWORD=4298nbadsfhhJHFO#oiu923hkajg9u23h96 # Edit
TLS_FILE=$HOME/.lnd/tls.cert
MACAROON_DIR=$HOME/.lnd/data/chain/bitcoin/mainnet/
JWT_PUBLIC_KEY_FILE=$HOME/.umbrel/db/jwt-public-key/jwt.pem

But if your lnd's setup is non-standard then you will have to change those accordingly, too.

cat >.env <<EOL
PORT=$PORT
DEVICE_HOST=$DEVICE_HOST
LND_HOST=127.0.0.1
LND_NETWORK=mainnet
RPC_USER=$RPC_USER
RPC_PASSWORD=$RPC_PASSWORD
TLS_FILE=$TLS_FILE
MACAROON_DIR=$MACAROON_DIR
JWT_PUBLIC_KEY_FILE=$JWT_PUBLIC_KEY_FILE
EOL

#3 Install Umbrel Manager

cd ../umbrel-manager
yarn install

Set the necessary environment variables:

PORT=3006
# You can skip these two if you don't want to use tor
BITCOIN_P2P_HIDDEN_SERVICE_FILE=/var/lib/tor/bitcoin_hidden_service/hostname # Edit
UMBREL_DASHBOARD_HIDDEN_SERVICE_FILE=/var/lib/tor/umbrel_hidden_service/hostname

Again, customize the red one to match your Tor's bitcoin setup. If you don't want to use Tor you can skip the last two lines altogether.

Create .env file with your settings:

cat >.env <<EOL
PORT=$PORT
DEVICE_HOST=$DEVICE_HOST
# You can skip the following two if you don't want to use tor
BITCOIN_P2P_HIDDEN_SERVICE_FILE=$BITCOIN_P2P_HIDDEN_SERVICE_FILE
UMBREL_DASHBOARD_HIDDEN_SERVICE_FILE=$UMBREL_DASHBOARD_HIDDEN_SERVICE_FILE
JWT_PUBLIC_KEY_FILE=$HOME/.umbrel/db/jwt-public-key/jwt.pem
JWT_PRIVATE_KEY_FILE=$HOME/.umbrel/db/jwt-public-key/jwt.key
USER_FILE=$HOME/.umbrel/db/user.js
SHUTDOWN_SIGNAL_FILE=$HOME/source/umbrel/umbrel/signals/shutdown
REBOOT_SIGNAL_FILE=$HOME/source/umbrel/umbrel/signals/reboot
UMBREL_VERSION_FILE=$HOME/source/umbrel/umbrel/info.json
UPDATE_STATUS_FILE=$HOME/source/umbrel/umbrel/statuses/update-status.json
UPDATE_SIGNAL_FILE=$HOME/source/umbrel/umbrel/signals/update
EOL

#4 Set up Systemd services

If you run Systemd, fetch my service files so that it's easier to run Umbrel after the system start.

cd /lib/systemd/system

sudo wget https://gist.githubusercontent.com/mariodian/f689efcdc50ad7b96e8ec7bacab74e6c/raw/6105077f65592798324b59aee38e62a0e4257e45/umbrel-manager.service
sudo wget https://gist.githubusercontent.com/mariodian/c33dd42ece6bc83cce4a2f205292ee4a/raw/db7e8b78f00148d9051ebd29126327a121ef85e0/umbrel-middleware.service

You will have to change the path in ExecStart and PIDFile in both files to match your environment.

Reload systemd after any changes:

sudo systemctl daemon-reload

#5 Set up HTTP Proxy (Optional)

Create a HTTP proxy so that all request will be directed from your hostname to Umbrel if you want to access it from another machine.

sudo -s

NGINX_HOST=bitcoin.server.com # Edit

Make sure to change the red strings to match your setup.

Next, create the virtual host for your HTTP server be it either Nginx (preferred) or Apache 2.

Nginx (Option 1)

If your preferred host is e.g. umbrel.server.com then the highlighted string will be umbrel instead of bitcoin.

cat >/etc/nginx/sites-available/bitcoin <<EOL # Edit
server {
    listen         80 default_server;
    listen         [::]:80 default_server;
    server_name    $NGINX_HOST;

    location /api/ {
        proxy_pass http://127.0.0.1:3005/;
    }

    location /manager-api/ {
        proxy_pass http://127.0.0.1:3006/;
    }

    location / {
	root /home/satoshi/source/umbrel/umbrel-dashboard/dist; # Edit
    }
}
EOL

exit

Enable the host and reload nginx:

sudo ln -s /etc/nginx/sites-available/bitcoin /etc/nginx/sites-enabled/
sudo systemctl reload nginx

Now you can open your Umbrel Dashboard on http://127.0.0.1 to verify that it works.

Apache 2 (Option 2)

If your preferred host is e.g. umbrel.server.com then the highlighted strings will be umbrel instead of bitcoin.

cat >/etc/apache2/sites-available/bitcoin <<EOL # Edit
<VirtualHost *:80>
    ServerName $NGINX_HOST

    <Location "/api/">
        ProxyPass http://127.0.0.1:3005/
    </Location>
    
    <Location "/manager-api/">
        ProxyPass http://127.0.0.1:3006/
    </Location>
    
    <Directory /home/satoshi/source/umbrel/umbrel-dashboard/dist> # Edit
        Require all granted
        AllowOverride all
    </Directory>
</VirtualHost>

Enable the host and reload apache. In the case of apache you will need to provide the whole hostname rather than just the first part.

sudo a2ensite bitcoin.server.com.conf # Edit
sudo systemctl reload apache2

Now you can open your Umbrel Dashboard on http://127.0.0.1 to verify that it works.

#6 Open ports in firewall (Optional)

In the case you want to access your Umbrel Dashboard from a different machine you will have to open the port 80 in your firewall:

sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT

You may need to tinker with port-forwarding on your router too. Unfortunately, that is beyond the scope of this tutorial.

#7 Set up Tor services (Optional)

If you set up Umbrel to use hidden services, open /etc/tor/torrc as root and find the following:

## Once you have configured a hidden service, you can look at the
## contents of the file ".../hidden_service/hostname" for the address
## to tell people.
##
## HiddenServicePort x y:z says to redirect requests on port x to the
## address y:z.

Add the following lines to set up hidden service for bitcoind and Umbrel Dashboard.

If you've already set up the hidden server for bitcoind before, skip the first two lines.

HiddenServiceDir /var/lib/tor/bitcoin_hidden_service/
HiddenServicePort 8333 127.0.0.1:8333

HiddenServiceDir /var/lib/tor/umbrel_hidden_service/
HiddenServicePort 80 127.0.0.1:80

Reload Tor settings:

sudo systemctl reload tor

#8 Setup SSL (Optional)

To access the Umbrel Dashboard remotely and via SSL (HTTPS), feel free to obtain a free certificate from Let's Encrypt.

Only run one of the following depending whether you use Nginx or Apache 2.

Make sure you customize the red string according to your chosen hostname.

Nginx (Option 1)

Generate the certificate:

sudo letsencrypt --nginx -d bitcoin.server.com # Edit

Reload nginx:

sudo systemctl reload nginx

Apache 2 (Option 2)

Generate the certificate:

sudo letsencrypt --apache -d bitcoin.server.com

Reload apache:

sudo systemctl reload apache2

When you use apache you may need to enable the SSL config for the virtual host manually depending on your Linux distro:

sudo a2ensite bitcoin.server.com-le-ssl.conf # Edit
sudo systemctl reload apache2

Update Umbrel config

If you've decided to go for the SSL option, you will have to change the http:// to https:// in your Umbrel config.

cd ~/source/umbrel

OLD_DEVICE_HOST=$DEVICE_HOST
NEW_DEVICE_HOST=https://bitcoin.server.com # Edit

sed -i "s|$OLD_DEVICE_HOST|$NEW_DEVICE_HOST|g" umbrel-manager/.env
sed -i "s|$OLD_DEVICE_HOST|$NEW_DEVICE_HOST|g" umbrel-middleware/.env

#9 Start Umbrel

First, check that Umbrel Manager and Umbrel Middleware are running correctly:

yarn start ~/source/umbrel/umbrel-manager/

If it doesn't output any error, hit the Ctrl + C (or CMD + C on Mac) to kill the process.

Check the middleware too and if it doesn't output any error kill the process too:

yarn start ~/source/umbrel/umbrel-middleware/

If you run into any error, I'm sorry I can't help you because this way of setting up Umbrel isn't officially supported.

It's likely you set up something wrong or I failed to keep the umbrel-manager package up to date with the upstream repository.

If you don't run into any issue, you can run both processes via Systemd:

sudo systemctl start umbrel-manager.service
sudo systemctl start umbrel-middleware.service

To run these services automatically after the system start up, execute this commands:

sudo systemctl enable umbrel-manager.service umbrel-middleware.service

#10 Setup Umbrel user

Go to the Umbrel Dashboard through your browser at the hostname or the IP address you set up and click START when it loads (it may take a while).

Fill out your name and lnd password (this is the password that you use to unlock your lnd wallet).

When you get to the screen that says "note down your secret words", click NOTE DOWN LATER instead of NEXT.

This is because I haven't changed the UI flow of Umbrel for when the lnd wallet already exists. I may or may not code it later.

If everything goes correctly, you should be taken to the "one last thing" page.

Then just click NEXT.

After one more screen you will be taken to the dashboard where you can see your bitcoin and lightning node's status along with some other info.

Enjoy!

If you found this tutorial helpful, please consider donating some sats. Figuring out how to setup this up took a lot of time. Your support is very much appreciated!