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

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

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

Configuration

  • 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
    
  • Build the static files

    $ ./venv/bin/python build.py
    

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

    # RaspiBolt: systemd unit for LNBits
    # /etc/systemd/system/lnbits.service
    
    Description=LNBits
    After=lnd.service
    PartOf=lnd.service
    
    [Service]
    WorkingDirectory=/home/lnbits/lnbits
    
    ExecStart=/home/lnbits/lnbits/venv/bin/uvicorn lnbits.__main__:app --port 5000
    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.9.4
    $ git checkout 0.9.4
    $ ./venv/bin/pip install -r requirements.txt
    $ ./venv/bin/python build.py
    $ 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 -
    $ userdel -r lnbits
    > userdel: lnbits mail spool (/var/mail/lnbits) not found
    $ exit
    




« Back: + Lightning