README.md

LNDg

Lite GUI web interface to analyze lnd data and manage your node with automation.

Start by choosing one of the following installation methods:
Docker Installation | Umbrel Installation | Manual Installation

Docker Installation (requires docker and docker-compose be installed)

Build and deploy

1. Clone respository git clone https://github.com/cryptosharks131/lndg.git
2. Change directory into the repo cd lndg
3. Customize docker-compose.yaml if you like and then build/deploy your docker image: docker-compose up -d
4. LNDg should now be available on port 8889

Updating

docker-compose down
docker-compose build --no-cache
docker-compose up -d

Notes

1. Unless you save your db.sqlite3 file before destroying your container, this data will be lost and rebuilt when making a new container. However, some data such as rebalances from previous containers cannot be rebuilt.
2. You can make this file persist by initializing it first locally touch /root/lndg/db.sqlite3 and then mapping it locally in your docker-compose file under the volumes. /root/lndg/db.sqlite3:/lndg/db.sqlite3:rw

Umbrel Installation

Build and deploy

1. Log into your umbrel via ssh
2. Clone respository git clone https://github.com/cryptosharks131/lndg.git
3. Change directory cd lndg
4. Initialize the database file touch db.sqlite3
5. Copy and replace the contents of the docker-compose.yaml with the below: nano docker-compose.yaml

services:
  lndg:
    build: .
    volumes:
      - /home/umbrel/umbrel/lnd:/root/.lnd:ro
      - /home/umbrel/lndg/db.sqlite3:/lndg/db.sqlite3:rw
    command:
      - sh
      - -c
      - python initialize.py -net 'mainnet' -server '10.21.21.9:10009' -d && python manage.py migrate && python manage.py collectstatic --no-input && supervisord && python manage.py runserver 0.0.0.0:8000
    ports:
      - 8889:8000
networks: 
  default: 
    external: true
    name: umbrel_main_network

5. Deploy your docker image: docker-compose up -d
6. You can now access LNDg via your browser on port 8889: http://umbrel.local:8889

Updating

docker-compose down
docker-compose build --no-cache
docker-compose up -d

Manual Installation

Step 1 - Install lndg

1. Clone respository git clone https://github.com/cryptosharks131/lndg.git
2. Change directory into the repo cd lndg
3. Make sure you have python virtualenv installed apt install virtualenv
4. Setup a python3 virtual environment virtualenv -p python3 .venv
5. Install required dependencies .venv/bin/pip install -r requirements.txt
6. Initialize some settings for your django site (see notes below) .venv/bin/python initialize.py
7. Migrate all database objects .venv/bin/python manage.py migrate
8. Generate some initial data for your dashboard .venv/bin/python jobs.py
9. Run the server via a python development server .venv/bin/python manage.py runserver 0.0.0.0:8889

Step 2 - Setup Backend Data and Automated Rebalancing

The files jobs.py and rebalancer.py inside lndg/gui/ serve to update the backend database with the most up to date information and rebalance any channels based on your lndg dashboard settings and requests. A refresh interval of at least 15-30 seconds is recommended for the best user experience.

Recommend Setup With Supervisord or Systemd

1. Supervisord
   a) Setup supervisord config .venv/bin/python initialize.py -sd
   b) Install Supervisord .venv/bin/pip install supervisor
   c) Start Supervisord supervisord

2. Systemd (2 options)
   Option 1 - Bash script install sudo bash systemd.sh
   Option 2 - Manual Setup Instructions

Alternatively, you may also make your own task for these files with your preferred tool (task scheduler/cronjob/etc).

Notes

1. If you are not using the default settings for LND or you would like to run a LND instance on a network other than mainnet you can use the correct flags in step 6 (see initialize.py --help) or you can edit the variables directly in lndg/lndg/settings.py.
2. Some systems have a hard time serving static files (docker/macOs) and installing whitenoise and configuring it can help solve this issue. You can use initialize.py -wn to setup whitenoise and install it with .venv/bin/pip install whitenoise.
3. If you want to recreate a settings file, delete it from lndg/lndg/settings.py and rerun. initialize.py
4. If you plan to run this site continuously, consider setting up a proper web server to host it (see Nginx below).

Setup lndg initialize.py options

1. -ip or --nodeip - Accepts only this host IP to serve the LNDg page - default: *
2. -dir or --lnddir - LND Directory for tls cert and admin macaroon paths - default: ~/.lnd
3. -net or --network - Network LND will run over - default: mainnet
4. -server or --rpcserver - Server address to use for rpc communications with LND - default: localhost:10009
5. -sd or --supervisord - Setup supervisord to run jobs/rebalancer background processes - default: False
6. -wn or --whitenoise - Add whitenoise middleware (docker requirement for static files) - default: False
7. -d or --docker - Single option for docker container setup (supervisord + whitenoise) - default: False
8. -dx or --debug - Setup the django site in debug mode - default: False

Updating

1. Make sure you are in the lndg folder cd lndg
2. Pull the new files git pull
3. Migrate any database changes .venv/bin/python manage.py migrate

Nginx Webserver

If you would like to serve the dashboard at all times, it is recommended to setup a proper production webserver to host the site.
A bash script has been included to help aide in the setup of a nginx webserver. sudo bash nginx.sh

Key Features

API Backend

The following data can be accessed at the /api endpoint:
payments paymenthops invoices forwards onchain peers channels rebalancer settings

Auto-Rebalancer

Here are some notes to help you get started using the Auto-Rebalancer (AR).

The objective of the Auto-Rebalancer is to "refill" the liquidity on the local side (i.e. OUTBOUND) of profitable and lucarative channels. So that, when a forward comes in from another node there is always enough liquidity to route the payment and in return collect the desired routing fees.

1. The AR variable AR-Enabled must be set to 1 (enabled) in order to start looking for new rebalance opportunities.
2. The AR variable AR-Target% defines the % size of the channel capacity you would like to use for rebalance attempts. Example: If a channel size is 1M Sats and AR-Target% = 0.05 LNDg will select an amount of 5% of 1M = 50K for rebalancing.
3. The AR variable AR-Time defines the maximum amount of time we will spend looking for a route. Example: 5 minutes
4. The AR variable AR-MaxFeeRate defines the maximum amount in ppm a rebalance attempt can ever use for a fee limit. This is the maximum limit to ensure the total fee does not exceed this amount. Example: AR-MaxFeeRate = 800 will ensure the rebalance fee is always less than 800 sats.
5. The AR variable AR-MaxCost% defines the maximum % of the ppm being charged on the INBOUND receving channel that will be used as the fee limit for the rebalance attempt. Example: If your fee to node A is 1000ppm and AR-MaxCost% = 0.5 LNDg will use 50% of 1000ppm = 500ppm max fee limit for rebalancing.
6. The AR variable AR-Outbound% helps identify all the channels that would be a candidate for rebalancing targetd channels. Rebalances will only consider any OUTBOUND channel that has more outbound liquidity than the current AR-Outbound% setting AND the channel is not currently being targeted as an INBOUND receving channel for rebalances. Example: AR-Outboud% = 0.6 would make all channels with an outbound capacity of 60% or more AND not enabled under AR on the channel line to be a candidate for rebalancing.
7. Channels need to be targeted in order to be refilled with outbound liquidity and in order to control costs as a first prioirty, all calculations are based on the specific INBOUND receving channel.
8. Enable INBOUND receving channels you would like to target and set an inbound liquidity Target% on the specific channel. Rebalance attempts will be made until inbound liquidity falls below this channel settting.
9. The INBOUND receving channel is the channel that later routes out real payments and earns back the fees paid. Target channels that have lucrative outbound flows.
10. Attempts that are successful or attempts with only incorrect payment information are tried again immediately. Example: If a rebalancing for 50k was sucessful, AR will try another 50k immediately with the same parameters.
11. Attempts that fail for other reasons will not be tried again for 30 minutes after the stop time. This allows the liquidity in the network to move around for 30 mins before trying another rebalancing attempt that previously failed.

Steps to start the Auto-Rebalancer:

1. Update Global Settings
   a. Go to section Update Auto Rebalancer Settings
   b. Select the global settings (sample below):
   c. Click OK button to submit

Enabled: 1
Target Amount (%): 0.03
Target Time (min): 5
Target Outbound Above (%): 0.4
Global Max Fee Rate (ppm): 200
Max Cost (%): 0.5

2. Update Channel Specific Settings
   a. Go to Active Channels section
   b. Find the channel you would like to activate for rebalancing
   c. On far right column Click the Enable button to activate rebalancing
   d. The dashboard will refresh and show AR-Target 100%
   e. Adjust the AR-Target to desired % of liquidity you want to keep on remote INBOUND side. Example select 0.60 if you want 60% of the channel capacity on Remote/INBOUND side which would mean that there is 40% on Local/OUTBOUND side
   f. Hit Enter
   g. Dashboard will refresh in the browser

3. Repeat Step-2 for each channel that you want to queue for rebalancing. Try to keep always keep a rebalance active and searching.

4. Go to section Last 10 Rebalance Requests - that will show the list of the rebalancing queue and status.

If you want a channel not to be picked for rebalancing (i.e. it is already full with OUTBOUND capacity that you desire), enable the channel and set the AR-Target% to 100. The rebalancer will ignore the channel while selecting the channels for outbound candidates and since its INBOUND can never be above 100% it will never trigger a rebalance.

Preview Screens

Main Dashboard

Peers, Balances, Routes and Pending HTLCs All Open In Separate Screens

Browsable API at /api (json format available with url appended with ?format=json)

View Keysend Messages (you can only receive these if you have accept-keysend=true in lnd.conf)