[GUIDE] Installing charge-lnd (in a docker) to automate your fee policies

Update: I’ve published this on Y’alls as well, for those of you who wish to tip anonymously Y'alls: How to automatically update your routing f

Greetings, all

I’m happy to report that I now have charge-lnd working smoothly on Umbrel, in a docker. Getting this to work took me a few weeks, and generous help and a lot of patience from Jorijn (one of the developers of charge-lnd) and my friend @yuvadm. Thanks guys!

I wanted to create a guide for all of you who are non-technical (like me), so that you can simply follow along with the steps and get auto-fee management on your node. As you probably know, Umbrel is notoriously finicky about you playing with it’s core files, so my main objective here was to install all files either on the SSD, to prevent you from losing your configurations during updates, or within a docker container, so that no core system functionality or apps are disturbed

Alright, let’s begin:

1. Log in to your Umbrel’s ssh via a command line tool on your computer (Terminal on Mac, for example):

ssh -t umbrel@Umbrel.local

You’ll need your admin password, which is the one you set on the back end.

2. Create a directory on the SSD for the config file (so it doesn’t get erased upon updates or SD card reflashes)

mkdir -p /mnt/data/upgrades/charge-lnd

3. Create a config file there:

sudo nano /mnt/data/upgrades/charge-lnd/charge.config

4. Populate the file with the rules you want, using the sample config file

You can change these rules at any time, and add to them as you go along, so I suggest starting with something basic.

If you need an explanation of how the parameters and rules work, here is a list of the parameters and their explanations.

Here is my config file, for a starting reference point:

# 'default' is special, it is used if no other policy matches a channel
strategy = static
base_fee_msat = 0
fee_ppm = 97

# don't let charge-lnd set fees (strategy=ignore) for channels to/from the specified nodes
node.id = 021c97a90a411ff2b10dc2a8e32de2f29d2fa49d41bfbb52bd416e460db0747d0d

strategy = ignore

# charge non-routing (private=true) peers a bit more for our service
chan.private = true
strategy = static
fee_ppm = 150

# 'proportional' can also be used to auto balance (lower fee rate when low remote balance & higher rate when higher remote balance)
# fee_ppm decreases linearly with the channel balance ratio (min_fee_ppm when ratio is 1, max_fee_ppm when ratio is 0
strategy = proportional
min_fee_ppm = 50
max_fee_ppm = 250

5. Now, we need to find the IP of your docker.

Run this command:

sudo nano ~/umbrel/.env

Find the line with LND_IP in it, and copy that IP address. Exit without saving.

6. Run the docker

The way charge-lnd works is by running the container “one time” - rather than keeping it open and alive persistently. This is different from other docker installations that Umbrel uses, but it doesn’t matter. We can ask our Pi to run the docker from the files hosted on the web.

First, make sure that you are in the right directory…

cd ~

Now, create the docker w/ the file you’ve already created as the config file. Don’t forget to replace the IP address with the one you found above.

docker run --rm -it --network=umbrel_main_network \
-e LND_DIR=/data/.lnd \
-e CONFIG_LOCATION=/app/charge.config \
-v /home/umbrel/umbrel/lnd:/data/.lnd \
-v /mnt/data/upgrades/charge-lnd/charge.config:/app/charge.config \

If everything works as expected, you’ll see a list of all of your channels, and the changes that have been made according to your rules / policies.

Check that you’re happy with how it’s applying rules.

If not, go ahead and edit the charge.config file on your hard disk that we created, then run the above “run” command again.

7. Now, Automate it!

Once you’re happy with everything, you can optionally set up a “crontab” job to automatically run this command every X minutes or hours.

Simply type:

crontab -e

The system will create a new crontab file, since none exists.

In this file, you can put the following, all on one line (make sure to update the IP address in this to yours):

0 * * * * docker run --rm --network=umbrel_main_network  -e GRPC_LOCATION=YOUR.LND.IP.ADDRESS:10009 -e LND_DIR=/data/.lnd -e CONFIG_LOCATION=/app/charge.config -v /home/umbrel/umbrel/lnd:/data/.lnd  -v /mnt/data/upgrades/charge-lnd/charge.config:/app/charge.config accumulator/charge-lnd:latest

This will run your charge-lnd script once every hour. This is the maximum recommended frequency by charge-lnd, as running it more frequently can result in failed routes or other confusion and chatter on the network.

If you wish to run it more/less frequently, that’s up to you, and you can find the instructions for changing the 0 * * * * part of the command above here: https://crontab.guru

That’s all!

If you’ve followed the steps above correctly, everything should work just fine, and update your routing policies every hour on the hour.

This guide was created with the help and support of a LOT of people MUCH smarter than me - and of course, it leverages the awesome (and free) script written by accumulator - so make sure to support their work.

With that said, if you appreciate this guide and would like to see me create MORE guides like this, you’re welcome to tip myself or any of the folks who helped me using Telegram @LNTXBot:

/tip 100 @The_Lorax_LN
/tip 100 @jorijn
/tip 100 @yuvadm

Thanks for reading, I hope you enjoyed this guide.

Happy routing!

EDIT: Removed docker login, it’s no longer necessary


Great guide! I needed this.

The Docker login I did in #5 did not work in my environment, so I’ll leave the one I used.

docker login docker.pkg.github.com --username <your_github_user_name> --password-stdin <generated_token_not_password>

everything else worked correctly? I was worried that I had some mistakes in the ~/umbrel type thing etc.

Thanks, I don’t think there was a problem.
The only thing is that some people might miss it if you don’t tell them that they need to enter the IP again in the following command as well.

1 Like

Good call. I went ahead and updated this.
Hope it increases your routing fees :slight_smile:

1 Like

hey @The_Lorax. small suggestion for step #6
the below command might be better to find LND_IP (less tech savvy won’t have to worry about accidentally saving the file, just saying)

cat ~/umbrel/.env | grep LND_IP

I’m trying this with no experience in Terminal on my Mac outside of changing my Node Alias and color…

With that being said, I can’t get past step 4. I copied and pasted what you’ve shown but then do I need to hit ‘write out’? Then I have a lot of other options after I hit write out if that is the right step as it says ‘file name to write’ such as DOS format, Mac format, Append, prepend, etc.

Any comments for a real beginner would be greatly appreciated.


Great tutorial The_Lorax!

Your twitter story on the 18th of july was my inspiration to get started with getumbrel and lightning!
Hope to open a channel to you soon, waiting for some incoming liquidity.

I sent you some sats via Telegram.

1 Like

Hey! Thanks for the sats. Kind of you.
And thanks for the channel. Glad my thread impacted you!

You need to write out, so Ctrl+X, then just hit enter, to save the file with the same file name it’s offering you (we definitely don’t want to change that file name). It should be offering you the file name of charge.config if you did everything right (that’s the file that the program looks for). If not, you can save it as that, and as long as you’re in the right directory, it will ;pick up that file

1 Like

Thanks! I skipped to 6. and copied the IP address and am now trying to jump into 7. but when I paste the command I can’t move lines to change my IP address. I’m assuming this is something basic that I’m missing. I’m entering this command (#7.) after logging into SSH Umbrel as I did in step 1.

After copied the command, why don’t you use Notepad or something to replace the IP address with the one you got in step 6 and then paste it line by line?

1 Like

Correct input for me was: ‘docker login docker.pkg.github.com --username <your_github_user_name> --password <generated_token_not_password>’

I removed Step 5, it’s not necessary anymore.

I was able to get Step 6 entered but this is what I got back and didn’t see any of my channels being updated as you noted I should:

Traceback (most recent call last):
File “/usr/local/bin/charge-lnd”, line 5, in
from charge_lnd.charge_lnd import main
File “/usr/local/lib/python3.9/site-packages/charge_lnd/charge_lnd.py”, line 146, in
success = main()
File “/usr/local/lib/python3.9/site-packages/charge_lnd/charge_lnd.py”, line 30, in main
config = Config(arguments.config)
File “/usr/local/lib/python3.9/site-packages/charge_lnd/config.py”, line 18, in init
with open(config_file, “r”) as f:
IsADirectoryError: [Errno 21] Is a directory: ‘/app/charge.config’

Any idea what could be going on with this error shown?

A couple other things:

  1. When I try to make sure I’m in the right directory and type cd ~ after logging into ssh-Umbrel by typing my password - Nothing happens. Am I possibly not in the right directory?
  2. I think I accidentally ran the step 6 command without updating my IP address once, not sure if that could have messed something up with this command
  3. I simply copy and pasted the sample config file in step 4 without updating any lines. As a dumb questions here I’m thinking I may have needed to update with my channel ID information before writing the config file out?

Thanks, I know my questions are probably pretty unintelligent but maybe there’s someone even less savvy with command line out there than me that will get find some of this useful!

Hi unfortunately I don’t know what the deal is with the error above, I think maybe there should be something above what you pasted that I’m not seeing, or I just don’t understand it (I’m not a coder, after all).

If you do cd ~ and you’re already in the home directory, nothing will happen.

After updating the OS, I was able to make it work again by recreating the charge.config.

sudo rmdir ~/umbrel/apps/charge-lnd/charge.config

create the “charge.config” again.

sudo nano ~/umbrel/apps/charge-lnd/charge.config

Tried your steps but got:

Error writing /home/umbrel/umbrel/apps/charge-lnd/charge.config: Is a directory

Any tips what I did wrong? (total noob who can barely make directory)

Edit: Apparently somehow it is needed to delete directory this way:
rmdir ~/umbrel/apps/charge-lnd


mkdir ~/umbrel/apps/charge-lnd

    Finally once again:

sudo nano ~/umbrel/apps/charge-lnd/charge.config

1 Like

I encountered this problem when I updated to 0.4.0 last month.
At that time, I deleted “~/umbrel/apps/charge-lnd” and followed the instructions from step 2.

I thought I just had to recreate the charge.config as I wrote earlier.

Yes, it’s been brought to my attention that anything saved in the /umbrel/directory or below it will be rewritten on software update. I need to update the guide a little bit and change the directory, the crontab, etc. I’ll try to do it now.

1 Like