Welcome to LNDg, an advanced web interface designed for analyzing Lightning Network Daemon (LND) data and automating node management tasks.
Choose your preferred installation method:
Easily install LNDg directly from popular platforms like Umbrel, Citadel, Start9, and RaspiBlitz. Follow the instructions provided by your chosen platform.
This method requires Docker and Docker Compose to be installed on your system.
1. Prepare Installation:
# Clone the repository
git clone https://github.com/cryptosharks131/lndg.git
# Change directory to the repository
cd lndg
# Customize the docker-compose.yaml file
nano docker-compose.yaml
Replace the contents of docker-compose.yaml
with your desired volume paths and settings. An example configuration is shown below:
services:
lndg:
build: .
volumes:
# Adjust paths according to your setup
- /home/<user>/.lnd:/root/.lnd:ro
- /home/<user>/<path-to>/lndg/data:/app/data:rw
command:
- sh
- -c
# Customize network ('mainnet' or 'testnet') and RPC address/port if needed
- python initialize.py -net 'mainnet' -rpc '127.0.0.1:10009' -wn && python controller.py runserver 0.0.0.0:8889 > /var/log/lndg-controller.log 2>&1
# Use host network mode for simplicity, adjust if needed
network_mode: "host"
2. Build and Deploy:
# Build and deploy the Docker container in detached mode
docker-compose up -d
# Retrieve the admin password for the initial login
cat data/lndg-admin.txt
- This example configuration will host LNDg at
http://<your-machine-ip>:8889
. - Log in to LNDg using the username
lndg-admin
and the password retrieved fromdata/lndg-admin.txt
.
This method provides a hands-on approach to setting up LNDg.
1. Install LNDg:
# Clone the repository
git clone https://github.com/cryptosharks131/lndg.git
# Change directory
cd lndg
# Ensure Python virtualenv is installed (example for Debian/Ubuntu)
sudo apt update && sudo apt install -y virtualenv
# Set up a Python 3 virtual environment
virtualenv -p python3 .venv
# Install required dependencies
.venv/bin/pip install -r requirements.txt
# Initialize settings (use --help for options)
# Add -wn or --whitenoise to serve static files if not using a separate webserver
.venv/bin/python initialize.py -wn
# Install whitenoise if the -wn flag was used
.venv/bin/pip install whitenoise
# Retrieve the admin password
cat data/lndg-admin.txt
# Run the development server (adjust IP/port if needed)
.venv/bin/python manage.py runserver 0.0.0.0:8889
- The initial login user is
lndg-admin
. The password is indata/lndg-admin.txt
. - Access LNDg at
http://<your-machine-ip>:8889
.
2. Setup Backend Controller:
The controller.py
script manages backend database updates, automated rebalancing, HTLC stream data, and p2p trade secrets. Set it up to run persistently using systemd
(recommended) or supervisord
.
-
Systemd:
- Option 1 (Script):
sudo bash systemd.sh
- Option 2 (Manual): Manual Systemd Setup Instructions
- Option 1 (Script):
-
Supervisord:
- Configure Supervisord:
.venv/bin/python initialize.py -sd
- Install Supervisord:
.venv/bin/pip install supervisor
- Start Supervisord:
supervisord
- Configure Supervisord:
Alternatively, use your preferred task scheduler (like cron
) to run controller.py
.
# Navigate to the lndg directory
cd lndg
# Stop the current containers
docker-compose down
# Rebuild the image without using cache
docker-compose build --no-cache
# Start the updated containers
docker-compose up -d
# OPTIONAL: Remove unused Docker objects
docker system prune -f
# Navigate to the lndg directory
cd lndg
# Pull the latest changes
git pull
# Install any new dependencies
.venv/bin/pip install -r requirements.txt
# Apply any database migrations
.venv/bin/python manage.py migrate
# Restart the LNDg service (web server and controller)
# Example for systemd:
# sudo systemctl restart lndg-web.service
# sudo systemctl restart lndg-controller.service
# If using supervisord:
# supervisorctl restart lndg-web
# supervisorctl restart lndg-controller
# If using the development server, stop and restart it:
# .venv/bin/python manage.py runserver 0.0.0.0:8889
If using a webserver like Nginx with uWSGI (see below), restart the uWSGI service:
sudo systemctl restart uwsgi.service
As mentioned in the Manual Installation, the controller.py
needs to run persistently. Use systemd
or supervisord
for reliable operation.
For continuous operation and better performance, especially in non-DEBUG mode, use a dedicated webserver like Nginx instead of the Django development server. Using a webserver also handles static file serving, making the whitenoise
dependency optional.
A helper script is included for setting up Nginx:
sudo bash nginx.sh
Remember to restart the uwsgi.service
after updates if using this setup.
LNDg uses SQLite3 by default. You can configure it to use a PostgreSQL database for potentially better performance in high-usage scenarios.
See the Postgres Setup Guide for instructions.
- Custom LND Settings: If not using default LND settings (e.g., non-default ports, network), use flags during
initialize.py
(check--help
) or editlndg/settings.py
directly. - Static Files (Manual Install): If running manually without a separate webserver (like Nginx), you MUST use the
-wn
flag withinitialize.py
and installwhitenoise
to serve static files (.css, .js). Running the development server (manage.py runserver
) withDEBUG=False
withoutwhitenoise
or a webserver will cause issues. - Updating Settings: Modify
lndg/settings.py
directly or re-runinitialize.py <options> -f
to update settings. - Admin Credentials: Manage login credentials via the admin interface at
http://<your-lndg-ip:port>/lndg-admin
. - Firewall: Ensure your firewall allows incoming connections on the port LNDg is running on (default: 8889).
Monitor changes your peers make to channel policies and track connection events for your open channels.
Open up to 10 channels simultaneously in a single transaction, potentially reducing on-chain fees.
Add, monitor, and remove watchtowers connected to your LND node.
Receive suggestions for adjusting outbound fee rates based on the last 7 days of payment and forwarding data. Enable Auto-Fees to act on these suggestions automatically. Note: Allow ~24 hours after a manual change before making another adjustment on the same channel.
Get recommendations for new peers based on your node's successful routing history, considering:
- Volume Score: Based on the count and volume of transactions routed through the peer.
- Savings By Volume (ppm): Estimated sats saved on rebalances if peered directly, relative to the volume routed through the peer.
Aggregate payment and forwarding data provides:
- Outbound Flow: Amount routed outbound vs. amount rebalanced in.
- Revenue: Total earned, profit (revenue - cost), and assisted revenue (earned due to this channel's inbound).
- Inbound Flow: Amount routed inbound vs. amount rebalanced out.
- Updates: Number of channel updates (correlates to
channel.db
size).
A dedicated P&L page tracks overall node metrics and profitability.
Initial username is lndg-admin
. Change it via the /lndg-admin
page.
LNDg suggests actions to optimize Auto-Rebalancing (AR).
Enable this setting (AR-Autopilot
) to automatically implement the suggestions from the AR Actions page.
Listen for and record HTLC failure events to the dashboard.
Access data programmatically via the /api
endpoint. Available resources include:
payments
, paymenthops
, invoices
, forwards
, onchain
, peers
, channels
, rebalancer
, settings
, pendinghtlcs
, failedhtlcs
.
Append ?format=json
for JSON output.
Automatically attempts to reconnect to peers associated with inactive channels (max once every 3 minutes per peer).
LNDg can automatically update channel fees based on performance suggestions.
Customize Auto-Fees (AF) behavior via the settings page:
AF-Enabled
: Set to1
to enable Auto-Fees globally. Individual channels must also be enabled.AF-FailedHTLCs
: Minimum daily failed HTLC count to potentially trigger a fee increase (based on flow).AF-Increment
: Base increment size (ppm) for fee changes. Suggestions are multiples of this value.AF-MaxRate
: Maximum fee rate (ppm) AF can set.AF-MinRate
: Minimum fee rate (ppm) AF can set.AF-Multiplier
: Multiplies theAF-Increment
for larger fee adjustments.AF-UpdateHours
: Minimum hours between AF adjustments for a single channel (default: 24).AF-LowLiqLimit
: Outbound liquidity (%) threshold below which the "Low Liquidity" fee algorithm applies.AF-ExcessLimit
: Outbound liquidity (%) threshold above which the "Excess Liquidity" fee algorithm applies.
- AF adjustments occur only if
AF-UpdateHours
have passed since the last LNDg fee update for that channel. - Channels below
AF-LowLiqLimit
% outbound liquidity may see fee increases based on failed HTLCs and incoming flow. - Channels above
AF-ExcessLimit
% outbound liquidity may see fee decreases based on lack of flow or assisted revenue. - Channels between these limits adjust based on overall flow patterns.
- View AF change history in the "Autofees" tab.
Automatically manage channel liquidity to maintain outbound capacity on profitable routes. See the Quick Start Guide.
The goal is to move funds (rebalance) into the local side (outbound capacity) of channels that frequently route payments out successfully. This ensures liquidity is available to earn routing fees.
Configure Auto-Rebalancer (AR) globally:
AR-Enabled
: Set to1
to activate AR (default: 0).AR-Target%
: Default rebalance amount as a percentage of channel capacity (e.g., 0.05 means 5%). Used if not set per-channel (default: 5).AR-Time
: Maximum time (minutes) to search for a rebalance route (default: 5).AR-MaxFeeRate
: Absolute maximum fee rate (ppm) allowed for any rebalance attempt (default: 100).AR-MaxCost%
: Maximum rebalance fee limit as a percentage of the target inbound channel's current outbound fee rate (e.g., 0.65 means 65%) (default: 65).AR-Outbound%
: Channels with more outbound liquidity than this percentage are considered potential sources for rebalancing funds from (default: 75). They must also not be targeted for receiving inbound liquidity.
AR-Autopilot
: Set to1
to automatically act on AR suggestions (default: 0).AR-WaitPeriod
: Time (minutes) to wait before retrying a rebalance on a channel after a failure (default: 30).AR-Variance
: Randomly vary the target rebalance amount by this percentage (default: 0).AR-Inbound%
: Default inbound target (iTarget%
) for newly monitored channels (default: 100).AR-APDays
: Number of days of historical data for Autopilot decisions (default: 7).AR-Workers
: Number of parallel rebalance attempts to run concurrently (default: 1).
-
Configure Target Channels (Receiving Inbound Liquidity): a. Go to the "Active Channels" section on the LNDg dashboard. b. Identify channels you want to refill with outbound liquidity (these are your profitable outbound routes). c. Click the "Enable" button in the far-right column for these target channels. d. The page will refresh, showing
AR-Target: 100%
. e. Adjust theAR-Target
percentage for each channel. This represents the desired remote (inbound) liquidity percentage. E.g.,0.60
means you want 60% inbound / 40% outbound liquidity. Press Enter to save. f. Important: Enable all channels valuable for outbound routing, even if you don't actively target them for refilling. Set theirAR-Target
to100%
to prevent AR from using them as a source for rebalancing funds away from them. -
Update Global Settings: a. Go to the "Update Auto Rebalancer Settings" section. b. Set
Enabled: 1
to activate the rebalancer. c. Configure other global settings (Target Amount (%)
,Target Time (min)
,Target Outbound Above (%)
,Global Max Fee Rate (ppm)
,Max Cost (%)
) as needed. d. Click "OK" to submit. -
Monitor Rebalances: a. Check the "Last 10 Rebalance Requests" section to view the queue and status of attempts.
Notes on AR Logic:
- Rebalances aim to decrease inbound liquidity below the channel-specific
AR-Target%
. - Channels with outbound liquidity above the global
AR-Outbound%
are potential sources to push funds from, unless they are themselves enabled with anAR-Target
. - Successful attempts or failures due to incorrect payment info are retried immediately.
- Other failures trigger a wait period (
AR-WaitPeriod
) before retrying on that channel.
(Requires accept-keysend=true
in lnd.conf)