Bonus guide: LNbits, a lightning wallet/accounts system

LNbits is a free and open-source lightning-network wallet/accounts system.

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

Difficulty: Easy

Status: Tested v3

LNbits

Table of contents

  1. Bonus guide: LNbits, a lightning wallet/accounts system
    1. Preparations
      1. Install dependencies
      2. Firewall & reverse proxy
    2. LNbits
      1. Installation
      2. Configuration
      3. First start
      4. Autostart on boot
      5. LNbits in action
      6. Remote access over Tor (optional)
    3. For the future: LNbits update
    4. Uninstall

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 themes

  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 (or your equivalent IP address).

LNbits in action

  • Access the LNbits homepage in your browser by browsing to https://raspibolt.local:4003 (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:

LNbits 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:

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, you can access this onion address from any device.

For the future: LNbits update

Updating to a new release 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