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
http://<your-machine-ip>:8889.lndg-admin and the password retrieved from data/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
lndg-admin. The password is in data/lndg-admin.txt.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.
sudo bash systemd.shOption 2 (Manual): Manual Systemd Setup Instructions
Supervisord:
.venv/bin/python initialize.py -sd.venv/bin/pip install supervisorsupervisordAlternatively, 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.
initialize.py (check --help) or edit lndg/settings.py directly.-wn flag with initialize.py and install whitenoise to serve static files (.css, .js). Running the development server (manage.py runserver) with DEBUG=False without whitenoise or a webserver will cause issues.lndg/settings.py directly or re-run initialize.py <options> -f to update settings.http://<your-lndg-ip:port>/lndg-admin.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:
1. Outbound Flow: Amount routed outbound vs. amount rebalanced in.
2. Revenue: Total earned, profit (revenue - cost), and assisted revenue (earned due to this channel's inbound).
3. Inbound Flow: Amount routed inbound vs. amount rebalanced out.
4. 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 to 1 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 the AF-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-UpdateHours have passed since the last LNDg fee update for that channel.AF-LowLiqLimit% outbound liquidity may see fee increases based on failed HTLCs and incoming flow.AF-ExcessLimit% outbound liquidity may see fee decreases based on lack of flow or assisted revenue.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 to 1 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 to 1 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).