layout	title	parent	grand_parent	nav_exclude	has_toc
default	LNbits	+ Lightning	Bonus Section	true	false

Bonus guide: LNbits, a lightning wallet/accounts system

{: .no_toc }

LNbits{:target="_blank"} is a free and open-source lightning-network wallet/accounts system.

⚠️ USE WITH CAUTION - LNbits wallet is still in BETA

Difficulty: Easy {: .label .label-green }

Status: Tested v3 {: .label .label-green }

Table of contents {: .text-delta }

TOC {:toc}

Preparations

Install dependencies

Install necessary dependencies using the apt package manager.

$ sudo apt update
$ sudo apt install software-properties-common
$ sudo add-apt-repository ppa:deadsnakes/ppa
$ sudo apt install python3.9 python3.9-distutils

Firewall & reverse proxy

Enable NGINX reverse proxy to route external encrypted HTTPS traffic internally to LNbits.

$ sudo nano /etc/nginx/streams-enabled/lnbits-reverse-proxy.conf

upstream lnbits {
  server 127.0.0.1:5000;
}
server {
  listen 4003 ssl;
  proxy_pass lnbits;   
}

Test and reload NGINX configuration.

$ sudo nginx -t
$ sudo systemctl reload nginx

Configure the firewall to allow incoming HTTPS requests.

$ sudo ufw allow 4003/tcp comment 'allow LNbits SSL'
$ sudo ufw status

LNbits

Installation

Create a new user and add it to the "lnd" group.

$ sudo adduser --disabled-password --gecos "" lnbits
$ sudo adduser lnbits lnd

Create a data directory for LNbits and give ownership to the new user.
```
$ sudo mkdir /data/lnbits
$ sudo chown -R lnbits:lnbits /data/lnbits
```

Open a new "lnbits" user session and create symlinks to the LND and LNbits data directories.

$ sudo su - lnbits
$ ln -s /data/lnd /home/lnbits/.lnd
$ ln -s /data/lnbits /home/lnbits/.lnbits

Install poetry and update PATH environment variable.

$ curl -sSL https://install.python-poetry.org | python3 -
$ export PATH="/home/lnbits/.local/bin:$PATH"

Download the source code directly from GitHub, create a virtual environment and install all dependencies.

$ git clone https://github.com/lnbits/lnbits.git
$ cd lnbits  
$ git checkout 0.10.9
$ poetry env use python3.9
$ poetry install --only main

Only if secp256k1 build fails, run:
```
$ poetry add setuptools wheel
```

Configuration

Create data dir and copy the example configuration file and open it.
```
$ cp .env.example .env
$ nano .env
```

Change the default path of the LNbits data folder

#LNBITS_DATA_FOLDER="./data"
LNBITS_DATA_FOLDER="/home/lnbits/.lnbits"

Choose the colour theme for the webpage, e.g. "bitcoin". You can choose among the following options: autumn, bitcoin, classic, flamingo, freedom, mint, monochrome and salvador.

LNBITS_THEME_OPTIONS="bitcoin"

Select the wallet that you want to use as backend, e.g. the LND REST API
```
LNBITS_BACKEND_WALLET_CLASS=LndRestWallet
```

Comment out all wallet parameters blocks execpt the one you selected just above, e.g. LndRestWallet

# ClicheWallet
#CLICHE_ENDPOINT=ws://127.0.0.1:12000

# SparkWallet
#SPARK_URL=http://localhost:9737/rpc
#SPARK_TOKEN=myaccesstoken

# CoreLightningWallet
#CORELIGHTNING_RPC="/home/bob/.lightning/bitcoin/lightning-rpc"

# LnbitsWallet
#LNBITS_ENDPOINT=https://legend.lnbits.com
#LNBITS_KEY=LNBITS_ADMIN_KEY

# LndRestWallet
LND_REST_ENDPOINT=https://127.0.0.1:8080/
LND_REST_CERT="/home/bob/.config/Zap/lnd/bitcoin/mainnet/wallet-1/data/chain/bitcoin/mainnet/tls.cert"
LND_REST_MACAROON="/home/bob/.config/Zap/lnd/bitcoin/mainnet/wallet-1/data/chain/bitcoin/mainnet/admin.macaroon or HEXSTRING"
# To use an AES-encrypted macaroon, set
# LND_REST_MACAROON_ENCRYPTED="eNcRyPtEdMaCaRoOn"

[...]

# EclairWallet
#ECLAIR_URL=http://127.0.0.1:8283
#ECLAIR_PASS=eclairpw

Edit the LND REST wallet parameters with the following lines

LND_REST_ENDPOINT=https://127.0.0.1:8080
LND_REST_CERT="/home/lnbits/.lnd/tls.cert"
LND_REST_MACAROON="/home/lnbits/.lnd/data/chain/bitcoin/mainnet/admin.macaroon"

Save (Ctrl+o) and close (Ctrl+x).
Restrict read/write permission to the "lnbits" user only.
```
$ chmod 600 /home/lnbits/lnbits/.env
```

First start

Make sure we are in the LNbits app directory and start the application.
```
$ cd ~/lnbits
$ poetry run lnbits --port 5000 --host 0.0.0.0
```

Now point your browser to the secure access point provided by the nginx web proxy, for example https://raspibolt.local:4003 (or your node's IP address like https://192.168.0.20:4003).

Your browser will display a warning because we use a self-signed SSL certificate. Click on "Advanced" and proceed to the LNbits web interface.

Stop LNbits in the terminal with Ctrl-C and exit the "lnbits" user session.
```
$ exit
```

Autostart on boot

As user "admin", create the service file.

$ sudo nano /etc/systemd/system/lnbits.service

Paste the following configuration. Save (Ctrl+o) and close the file (Ctrl+x) afterwards.

# RaspiBolt: systemd unit for LNbits
# /etc/systemd/system/lnbits.service

[Unit]
Description=LNbits
After=lnd.service
PartOf=lnd.service

[Service]
WorkingDirectory=/home/lnbits/lnbits

ExecStart=/home/lnbits/.local/bin/poetry run lnbits --port 5000 --host 0.0.0.0 --debug --reload
User=lnbits
Restart=always
TimeoutSec=120
RestartSec=30
StandardOutput=journal
StandardError=journal

# Hardening measures
PrivateTmp=true
ProtectSystem=full
NoNewPrivileges=true
PrivateDevices=true

[Install]
WantedBy=multi-user.target

Enable the service, start it, and check the status and log output.

$ sudo systemctl enable lnbits.service
$ sudo systemctl start lnbits.service
$ sudo systemctl status lnbits.service
$ sudo journalctl -f -u lnbits

You can now access LNbits from within your local network by browsing to https://raspibolt.local:4003{:target="_blank"} (or your equivalent IP address).

LNbits in action

Access the LNbits homepage in your browser by browsing to https://raspibolt.local:4003{:target="_blank"} (or your equivalent IP address)
Type a wallet name, e.g. "My LNbits wallet #1"
Click on "ADD NEW WALLET" button. You will land on the wallet homepage:

You can fund your wallet and then send or receive lightning payments. You can also enable one or more extensions built by the community. Below is a list of resources to learn how to use LNbits and the extensions:

Awesome LNbits{:target="_blank"}: a list of resources for the extensions and projects built on LNbits
the LNbits Youtube channel{:target="_blank"}
the LNbits GitHub channel

Remote access over Tor (optional)

Add the following three lines in the "location-hidden services" section in the torrc file. Save and exit.

$ sudo nano /etc/tor/torrc

############### This section is just for location-hidden services ###
# Hidden service LNbits
HiddenServiceDir /var/lib/tor/hidden_service_lnbits/
HiddenServiceVersion 3
HiddenServicePort 80 127.0.0.1:5000

Reload Tor configuration and get your connection address.

$ sudo systemctl reload tor
$ sudo cat /var/lib/tor/hidden_service_lnbits/hostname
> abcdefg..............xyz.onion

With the Tor browser{:target="_blank"}, you can access this onion address from any device.

For the future: LNbits update

Updating to a new release{:target="_blank"} is straight-forward, but make sure to check out the release notes first.

From user "admin", stop the service and open a "lnbits" user session.
```
$ sudo systemctl stop lnbits
$ sudo su - lnbits
```

Fetch the latest GitHub repository information, display the release tags (use the latest 0.8.0 in this example), and update:

$ cd /home/lnbits/lnbits
$ git fetch
$ git reset --hard HEAD
$ git tag | grep -E "v[0-9]+.[0-9]+.[0-9]+$" | sort --version-sort | tail -n 1
> 0.10.9
$ git checkout 0.10.9
$ poetry install --only main
$ exit

Start the service again.
```
$ sudo systemctl start lnbits
```

Uninstall

🚨 Warning: Before uninstalling LNbits, you might want to empty all your LNbits wallets.

Stop and disable the systemd service and then delete the service file

$ sudo systemctl disable lnbits.service
$ sudo systemctl stop lnbits.service
$ sudo rm /etc/systemd/system/lnbits.service

Display the UFW firewall rules and notes the numbers of the rules for LNbits (e.g., X and Y below)

$ sudo ufw status numbered
> [...]
> [X] 4003                   ALLOW IN    Anywhere                   # allow LNbits SSL
> [...]
> [Y] 4003 (v6)              ALLOW IN    Anywhere (v6)              # allow LNbits SSL

Delete the two LNbits rules (check that the rule to be deleted is the correct one and type “y” and “Enter” when prompted)
```
$ sudo ufw delete Y
$ sudo ufw delete X
```

Delete the nginx reverse proxy configuration file

$ sudo rm /etc/nginx/streams-enabled/lnbits-reverse-proxy.conf

Test and reload nginx configuration

$ sudo nginx -t
> nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
> nginx: configuration file /etc/nginx/nginx.conf test is successful
$ sudo systemctl reload nginx

Delete the "lnbits" user. Do not worry about the userdel: mempool mail spool (/var/mail/mempool) not found.

$ sudo su -
$ rm -r /data/lnbits
$ userdel -r lnbits
> userdel: lnbits mail spool (/var/mail/lnbits) not found
$ exit

<< Back: + Lightning

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

lnbits.md

lnbits.md

Bonus guide: LNbits, a lightning wallet/accounts system

Preparations

Install dependencies

Firewall & reverse proxy

LNbits

Installation

Configuration

First start

Autostart on boot

LNbits in action

Remote access over Tor (optional)

For the future: LNbits update

Uninstall

Files

lnbits.md

Latest commit

History

lnbits.md

File metadata and controls

Bonus guide: LNbits, a lightning wallet/accounts system

Preparations

Install dependencies

Firewall & reverse proxy

LNbits

Installation

Configuration

First start

Autostart on boot

LNbits in action

Remote access over Tor (optional)

For the future: LNbits update

Uninstall