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


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


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 {
      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



  • 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 | 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
    $ 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


  • 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

  • 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

  • Select the wallet that you want to use as backend, e.g. the LND REST API

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

    # ClicheWallet
    # SparkWallet
    # CoreLightningWallet
    # LnbitsWallet
    # LndRestWallet
    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
    # EclairWallet
  • Edit the LND REST wallet parameters with the following lines

  • 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

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

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
    ExecStart=/home/lnbits/.local/bin/poetry run lnbits --port 5000 --host --debug --reload
    # Hardening measures
  • 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
  • Reload Tor configuration and get your connection address.

    $ sudo systemctl reload tor
    $ sudo cat /var/lib/tor/hidden_service_lnbits/hostname
  • 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


🚨 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