Skip to main content Link Search Menu Expand Document (external link)

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. Remote access over Tor (optional)
    3. For the future: LNBits update


Install dependencies

  • Install necessary dependencies using the apt package manager.

    $ sudo apt install libffi-dev libpq-dev python3-venv

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
  • Download the source code directly from GitHub, create a virtual environment, and install all dependencies with pip.

    $ git clone --branch 0.9.4 lnbits
    $ cd lnbits
    $ python3 -m venv venv
    $ ./venv/bin/pip install setuptools wheel --upgrade
    $ ./venv/bin/pip install -r requirements.txt
    $ ./venv/bin/pip install pylightning


  • Create a new configuration file for LNBits and paste the following content. Save and exit.

    $ nano .env
    # RaspiBolt: LNBits configuration
    # /home/lnbits/lnbits/.env
  • Restrict read/write permission.

    $ chmod 600 /home/lnbits/lnbits/.env

First start

  • Make sure we are in the LNBits app directory and start the application.

    $ cd ~/lnbits
    $ ./venv/bin/uvicorn lnbits.__main__:app --port 5000

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 and exit.

    # RaspiBolt: systemd unit for LNBits
    # /etc/systemd/system/lnbits.service
    ExecStart=/bin/sh -c 'cd /home/lnbits/lnbits && ./venv/bin/uvicorn lnbits.__main__:app --port 5000'
    # Hardening measures
  • Enable the service, start it, and check the log output.

    $ sudo systemctl enable lnbits.service
    $ sudo systemctl start 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).

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
    $ git checkout 0.8.0
    $ ./venv/bin/pip install -r requirements.txt
    $ exit
  • Start the service again.

    $ sudo systemctl start lnbits

« Back: + Lightning