highperfocused/lnbits
1
0
Fork 0
mirror of https://github.com/lnbits/lnbits.git synced 2025-04-13 22:39:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

Updated LNbits Documentation (markdown)

arbadacarba 2023-07-11 18:25:48 +02:00
parent d6175334fc
commit b840020868
1 changed files with 5 additions and 420 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

425
LNbits-Documentation.md

@ -20,13 +20,13 @@ LNbits works based on the LNURL protocol which means that requests are valid in
## Install LNbits
You can choose between the most common package managers like `poetry` and `nix`.
By default, LNbits will use SQLite as its database. You can also use PostgreSQL which is recommended for applications with a high load (see guide below).
If you have problems installing LNbits using [these instructions](https://github.com/lnbits/lnbits/blob/main/docs/guide/installation.md), please have a look at the Troubleshooting section.
By default, LNbits will use SQLite as its database. You can also use PostgreSQL which is recommended for applications with a high load.
If you have problems installing LNbits using [these instructions](https://github.com/lnbits/lnbits/blob/main/docs/guide/installation.md) please have a look at the Troubleshooting section.
For everyone new to this, you will find a step-by-step guide for most options including getting your LNbits into Clearnet [here](https://ereignishorizont.xyz/lnbits-server/en/) that [Axel](https://twitter.com/AxelHamburch) made or the one from [Hannes](https://github.com/trezorHannes/) on [how to set up LNbits on a VPS](https://github.com/TrezorHannes/vps-lnbits).
For everyone new to this, you will also find a step-by-step guide for getting your LNbits into Clearnet [here in a detailed guide](https://ereignishorizont.xyz/lnbits-server/en/) that [Axel](https://twitter.com/AxelHamburch) made or the one from [Hannes](https://github.com/trezorHannes/) on [how to set up LNbits on a VPS](https://github.com/TrezorHannes/vps-lnbits).
If you are more experienced go on with Additional Guides -> Clearnet after installation.
LNbits SaaS (recommended)
### LNbits SaaS
When you´re not into the technical stuff and neither want to host your funding source nor your lnbits yourself there is a [LNbits as Software-as-a-service](https://lnbits.com/#) you can use. It is basically like LNbits in a cloud but you can define the funding source (e.g. your Node, a LNbits wallet, the LNtipbot, fakewallet etc) and environmnent variables yourself - which mostly is not the case on other cloud-solutions.
@ -42,12 +42,8 @@ If you need ports or look for folders mentioned here that you cannot find please
### Funding sources
<details><summary>Have a look at the options</summary>
LNbits is not a node management software but a ⚡️LN only accounting system on top of a funding source.
After the first installation you can visit your LNbits at http://localhost:5000/. To modify the funding source go to your super-user-URL shown in the logs and select a funding source within "Manage Server" (DarthCoin has made a [guide on this here](https://darthcoin.substack.com/p/lnbits-saas-a-solution-for-schools?utm_source=profile&utm_medium=reader2)
) or edit the `.env` file by modifying `LNBITS_BACKEND_WALLET_CLASS` to your needed source. You will find the .env file within your lnbits/ or lnbits/apps/data folder by extending the command to list files in your directory by```ls -a```
@ -168,31 +164,6 @@ Client for Lightning-compatible Lite Channels aka "Hosted". [More details here](
</ul>
</details>
<details><summary>Funding source only available via tor (e.g. Umbrel)</summary>
<ul>
<details><summary>Connecting over Tor</summary>
If you want to keep your LN node behind Tor but still want to have a LNbits instance on clearnet (https / domain), you can also install it on a separate machine with Linux OS, in the same LAN as your node or on a VPS remotely, following the normal [install instructions](https://github.com/lnbits/lnbits/wiki/LNbits-Documentation#install-options).
Add Tor service on that Linux machine so you could connect to your Tor only LN node.
Once you installed LNbits you can use the funding source from your Tor only LN node using the .onion address. See the previous section how to configure in the .env file the funding sources.
In this way you can manage the separate LNbits instance and change the funding source anytime against any other LN node.
</details>
<details><summary>Connecting over Tailscale</summary>
For a more stable and faster connection with your Tor node, you can use also [Tailscale](https://tailscale.com/). This is a private VPN encrypted connection towards your node. Umbrel and other platforms already have included this app, easy to install.
Once is installed, you will get a private IP like 10.10.1.x for your LN node. Same for your LNbits server.
Now go to your LNbits .env file and edit it with your specific funding source, using that Tailscale IP as host.
</details>
</ul>
</details>
<details><summary>Funding source is in a cloud</summary>
@ -238,12 +209,11 @@ This wiki has a section about [switching funding sources](https://github.com/lnb
</details>
<details><summary>Activate AdminUI (aka Manage Server)</summary>
<details><summary>Difference between admin and superuser</summary>
The LNbits Admin UI lets you change LNbits settings via the LNbits frontend. It is disabled by default and the first time you set the enviroment variable LNBITS_ADMIN_UI=true in the .env the settings are initialized and saved to the database and will be used (as long the UI is enabled). **From there on the according settings from the database instead those of the .env file are used.**
On restart of LNbits you will find the link to the superuser-AdminUI in your terminal resp. in your logs. Save if good and never share it. When the AdminUI is opened we can move on.
First lfets unterstand what each user can / not do.
For bundle-nodes please find a description on [how to activate the admin-ui here](https://github.com/lnbits/lnbits/wiki/LNbits-Extensions)
@ -278,395 +248,10 @@ Enviroment variable: LNBITS_ALLOWED_USERS, comma-seperated list of user IDs.
By defining these users LNbits will no longer be useable by the public. Only defined users and admins can then access the LNbits frontend.
***
**How to activate manually**
Hints:
- You will find the .env file in the lnbits/data folder of your installation by extending the command to list files in your directory to ```ls -a```
- On MyNode, Umbrel and Citadel the .env is named different and located here /apps/lnbits/docker-compose.yml
- On MyNode you will find your logs in http://mynode.local/status. If start up messages have scrolled off, then http://mynode.local/apps and Restart LNbits and you should be able to see the line stating the SuperUser URL.
```
$ sudo systemctl stop lnbits.service
$ cd ~/lnbits
$ sudo nano .env
```
-> set: `LNBITS_ADMIN_UI=true`
Start LNbits in the terminal window
```
$ poetry run lnbits
```
It will now show you the super user account in your log entries (!):
`SUCCESS | ✔️ Access super user account at: https://127.0.0.1:5000/___wallet?usr=5711d7___..`
The `/wallet?usr=..` is your super user account. You just have to append it to your normal LNbits web domain.
After that you will find the __`Admin` / `Manage Server`__ between `Wallets` and `Extensions`
This is where you can define the interface access. Use e.g. TOPUP to fund dedicated wallets, restrict access rights to your extensions only for admins or generally deactivate them for everyone, define users and their access to certain extensions. Basically everything you did in the classic settings of the .env file.
Be careful: If you set `RESET TO DEFAULTS` a new super user account is created. The old one is then no longer valid!
To get these new settings running we need a last command
```
sudo systemctl start lnbits.service
```
</details>
<details><summary>Install missing extensions after update</summary>
Now that the extensions are taken out of core and you have made yourself Admin by following the ToDos from "Activate Admin-UI" ☝️ you will need to get access to the extensions you have used before including the data you saved (yes, its still in the database).
Totes sorry for that, but this is the only way we can keep the core of LNbits not only clean but safe for you.
Please be aware to only install, what you are using, to keep all possible attack vectors small.
For the process after this [Calle](https://gist.github.com/callebtc) made another [tutorial on how to become the boss over your extensions in your instance again](https://github.com/lnbits/lnbits/blob/main/docs/guide/extension-install.md#install-new-extension).
If you experience trouble and your window differs from the documented one try CTRL+F5 to update your browser-cache (yes, seriously!).
If you want to install a bunch/all extensions you need to add this (not recommended!!) to your env
````
LNBITS_EXTENSIONS_DEFAULT_INSTALL="watchonly,satspay,streamalert,tipjar,lnticket,invoices,boltcards,paywall,subdomains,discordbot,bleskomat,jukebox,splitpayments,withdraw,example,tpos,smtp,livestream,ngrok,events,lndhub,lnurlpayout,diagonalley,copilot,lnurlpos,deezy,lnaddress,satsdice,offlineshop,lnurlp,usermanager,cashu,nostrnip5,gerty,scrub,hivemind,boltz,market,lnurldevice"
````
Further info on this in the section [Extensions](https://github.com/lnbits/lnbits/wiki/LNbits-Extensions)
</details>
<details><summary>Clearnet https / Reverse Proxy</summary>
LNbits works based on the LNURL protocol which requests are valid in two forms: either as https:// clearnet link (no self-signed certificates allowed) or as http:// v2/v3 onion link. To offer LNbits services like LNURLp/w QR codes or NFC Cards, that can be used in the wild, you will need to open LNbits to clearnet.
<details><summary>Reverse proxy for https or nip-05 using Caddy (recommended!)</summary>
Caddy is an open-source, HTTP/2-enabled web server that is designed to be simple, fast, and secure. It supports automatic HTTPS encryption, HTTP/2, and other modern web technologies out of the box, with minimal configuration required. Caddy is known for its user-friendly configuration syntax, which is designed to be easy to read and write. It also features a plugin system that allows users to extend its functionality with a wide variety of third-party plugins.
Use Caddy to make your LNbits installation accessible on clearnet via a dedicated sub/domain and https certficate.
Point your domain to the IP of the server you're running LNbits on by creating an `A` record.
Install Caddy on the server
https://caddyserver.com/docs/install#debian-ubuntu-raspbian
```
sudo caddy stop
```
Create a Caddyfile
```
sudo nano Caddyfile
```
Assuming your LNbits is running on port `5000` add:
```
lnbits.yourdomain.com {
handle /api/v1/payments/sse* {
reverse_proxy 0.0.0.0:5000 {
header_up X-Forwarded-Host lnbits.yourdomain.com
transport http {
keepalive off
compression off
}
}
}
reverse_proxy 0.0.0.0:5000 {
header_up X-Forwarded-Host lnbits.yourdomain.com
header_up X-Forwarded-Proto https
}
}
```
Save and exit `CTRL + x`
```
sudo caddy start
```
For the Nip05-extension change the Caddyfile to this
```
my.lnbits.instance {
reverse_proxy {your_lnbits}
}
nip.5.domain {
route /.well-known/nostr.json {
rewrite * /nostrnip5/api/v1/domain/{domain_id}/nostr.json
reverse_proxy {your_lnbits}
}
}
```
If you feel you want to be guided in doing this AND understand more about your LNbits and SSH in general please refer to the [step-by-step guide on LNbits over Caddy from Axel here](https://ereignishorizont.xyz/lnbits-server/en/)
</details>
<details><summary>Reverse proxy with automatic https using nginx</summary>
**One tip: Dont use this. Its is unnessecarily complicated to set up. Rather use the caddy version ☝️😅**
We will refer to our domain as yourdomain.com, and for our LNbits subdomain we’ll refer to as lnbits.yourdomain.com.
SSH onto your device and use your package manager to install the necessary packages.
```
sudo add-apt-repository ppa:certbot/certbot <-- This adds the certbot repository
sudo apt update
sudo apt install nginx certbot
```
DNS configuration
Now we need to set up an A record pointing lnbits.yourdomain.com to your public machine IP at your Domain-Provider´s Interface.
If you’re not behind a VPN, ifconfig.me will show you your IP.
If you run on dynDNS instead of having an own fixed IP it’s also recommended that you set up a DNS updater, so that your A record automatically updates to your latest IP in case your ISP changes it. Some providers have dedicated applications for this. Others utilise a single unique string URL that when hit, is updated with hitter’s IP. If you use a provider that employs this method (or delegated your domain to one who does), feel free to use the following python script:
https://gitlab.com/Fragments-form-function/multi-scripts/-/blob/master/DNS-Script.py
Download/copy it, place it on your server and follow its further instructions.
Port-Forwarding in your router
On your home router forward port 443 and point it to the IP of the device you install nginx + certbot on like e.g. the IP of your Raspberry PI.
Settings could look like this
````
Name: LNbits NGINX HTTPS
IP address: IP RASPBERRY
Source port/WAN: 443
Destination port/LAN: 443
Protocol: TCP
````
(Just) If your ISP does not allow you to port-forward a standard port such as 443, you may choose another port and change the nginx configuration accordingly and include this in your config
```
location / {
proxy_pass $forward_scheme://$server:$port;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Proto $scheme;
}
````
Both if you are using 443 or any other port we now move along with the
SSL Certificate
We assume here, that a challenge txt is fine for you. If you´d like to use another method for your certificate check https://certbot.eff.org/instructions?ws=nginx&os=debianbuster.
On the device you installed certbot on, run:
```
sudo certbot certonly --manual --preferred-challenges dns
```
Certbot will ask you for the domain and to place a TXT record for _acme-challenge.lnbits.yourdomain.com with a string it gives as the value. Give it the lowest TTL you can(5 mins is fine), as you’ll remove this TXT record once validated.
Once the TXT record is in place open another SSH terminal window and run
```
dig -t txt _acme-challenge.lnbits.yourdomain.com
```
every few minutes until the string appears. This can take 15-30 minutes. Your challenge won’t timeout.
Once the record is successfully retrieved from dig hit Enter on certbot to receive your certificate. If it didn’t work, retry, give it more time. It can take a while for DNS to propagate.
Your new certificate should be at /etc/letsencrypt/live/lnbits.yourdomain.com/. Remember this path as we’ll need it shortly.
Configuring nginx reverse-proxy
Navigate to /etc/nginx/sites-available/ so that we can define a config file there.
We start doing so with the nano text editor
```
nano reverse-proxy.conf
```
Once inside, you’ll want set up a new server block dedicated to LNbits. This is where the magic happens.
```
server {
listen 443 ssl; # Here, you'll tell nginx to listen on port 443 for SSL connections
server_name lnbits.yourdomain.com;
access_log /var/log/nginx/reverse-access.log; # Go to for troubleshooting
error_log /var/log/nginx/reverse-error.log; # Go to for troubleshooting
location / {
proxy_pass http://10.13.37.5:5000 # Change this to point to your LNbits private IP:port (localhost if bundle node or at-home installation or from your VPS or even cloud supplier where LNbits runs on)
proxy_set_header Upgrade $http_upgrade;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header Host $host;
proxy_http_version 1.1; # Ensures that replies are re-written to lnbits.yourdomain.com (as opposed to the private IP or .onion)
}
ssl on; # This is important and declares connections should be secured with SSL.
ssl_certificate /etc/letsencrypt/live/lnbits.yourdomain.com/fullchain.pem; # Point to the fullchain.pem
ssl_certificate_key /etc/letsencrypt/live/lnbits.yourdomain.com/privkey.pem; # Point to the private key
```
Now we test and restart our services
```
sudo nginx -t
sudo systemctl reload reverse-proxy.conf
````
You´re done :)
</details>
<details><summary>Running behind an apache2 reverse proxy over https</summary>
Install apache2 and enable apache2 mods
```
apt-get install apache2 certbot
a2enmod headers ssl proxy proxy-http
```
create a ssl certificate with letsencrypt
```
certbot certonly --webroot --agree-tos --text --non-interactive --webroot-path /var/www/html -d lnbits.org
```
create a apache2 vhost at: /etc/apache2/sites-enabled/lnbits.conf
```
cat <<EOF > /etc/apache2/sites-enabled/lnbits.conf
<VirtualHost *:443>
ServerName lnbits.org
SSLEngine On
SSLProxyEngine On
SSLCertificateFile /etc/letsencrypt/live/lnbits.org/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/lnbits.org/privkey.pem
Include /etc/letsencrypt/options-ssl-apache.conf
LogLevel info
ErrorLog /var/log/apache2/lnbits.log
CustomLog /var/log/apache2/lnbits-access.log combined
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
RequestHeader set "X-Forwarded-SSL" expr=%{HTTPS}
ProxyPreserveHost On
ProxyPass / http://localhost:5000/
ProxyPassReverse / http://localhost:5000/
<Proxy *>
Order deny,allow
Allow from all
</Proxy>
</VirtualHost>
EOF
```
restart apache2
```
service restart apache2
```
</details>
<details><summary>Using https without reverse proxy</summary>
The most common way of using LNbits via https is to use a reverse proxy such as Caddy, nginx, or ngriok. However, you can also run LNbits via https without additional software. This is useful for development purposes or if you want to use LNbits in your local network.
We have to create a self-signed certificate using `mkcert`. Note that this certiciate is not "trusted" by most browsers but that's fine (since you know that you have created it) and encryption is always better than clear text.
**Install mkcert**
You can find the installation instructions for `mkcert` [here](https://github.com/FiloSottile/mkcert).
Install mkcert on Ubuntu:
```
sudo apt install libnss3-tools
curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
chmod +x mkcert-v*-linux-amd64
sudo cp mkcert-v*-linux-amd64 /usr/local/bin/mkcert
```
**Create certificate**
To create a certificate, first `cd` into your LNbits folder and execute the following command on Linux:
```
openssl req -new -newkey rsa:4096 -x509 -sha256 -days 3650 -nodes -out cert.pem -keyout key.pem
```
This will create two new files (`key.pem` and `cert.pem `).
Alternatively, you can use mkcert ([more info](https://kifarunix.com/how-to-create-self-signed-ssl-certificate-with-mkcert-on-ubuntu-18-04/)):
```
# add your local IP (192.x.x.x) as well if you want to use it in your local network
mkcert localhost 127.0.0.1 ::1
```
You would want to then pass the certificate files to uvicorn when starting LNbits:
```
./venv/bin/uvicorn lnbits.__main__:app --host 0.0.0.0 --port 5000 --ssl-keyfile ./key.pem --ssl-certfile ./cert.pem
```
</details>
<details><summary>Run bundle node (over Tor) + LNbits via clearnet domain</summary>
If you want your setup to stay behind Tor then only apps, POS and wallets that have tor activated can communicate with your wallets.
Most likely you will have trouble when people try to redeem your voucher through onion or when importing your LNbits wallets into a wallet-app that doesn't support Tor. If you plan to let LNbits wallets interact with clearnet (domain/IP) shops and services you should consider [setting up hybrid mode for your node](https://github.com/TrezorHannes/Dual-LND-Hybrid-VPS).
Also If you want to run LNbits on your Umbrel but want it to be reached through clearnet, [Uxellodunum made an extensive guide](https://community.getumbrel.com/t/how-to-configure-umbrel-lnbits-app-without-tor/604) on how to do it.
</details>
<details><summary>Tor LN node + LNBits over Tailscale/Wireguard</summary>
Let's consider you have a bundle Tor node (Umbrel, myNode, Citadel etc) and you want to run a LNBits instance on another machine but not in the same LAN.
The option is to use [Tailscale](https://tailscale.com) as a private VPN tunnel. Usually Tailscale come already available in almost all these bundle nodes (Umbrel, myNode, Citadel etc) so with just one click you can install it and get a private IP. All the communication is secured and encrypted, Tailscale is based on Wireguard protocol and is free.
Install Tailscale on your LNbits machine (with the same Tailscale account) and get a private IP for this machine too.
Now, configure your new LNbits instance to point to the Tailscale IP of your Tor node (see the instructions to edit the .env config file and please add LNBITS_ADMIN_UI=true if its not given there). And done! Tailscale will use its tunnel to communicate between both machines.
For a documentation on Wireguard please have a look at Hannes Tutorial about how to [setup VPS-LNbits with WireGuard VPN](https://github.com/TrezorHannes/vps-lnbits-wg).
</details>
</details>
<details><summary>LNbits as a systemd service</summary>
Systemd is great for taking care of your LNbits instance. It will start it on boot and restart it in case it crashes. If you want to run LNbits as a systemd service on your Debian/Ubuntu/Raspbian server create a file at `/etc/systemd/system/lnbits.service` with the following content:
```
# Systemd unit for lnbits
# /etc/systemd/system/lnbits.service
[Unit]
Description=LNbits
# you can uncomment these lines if you know what you're doing
# it will make sure that lnbits starts after lnd (replace with your own backend service)
#Wants=lnd.service
#After=lnd.service
[Service]
# replace with the absolute path of your LNbits installation
WorkingDirectory=/home/lnbits/lnbits
# same here. run `which poetry` if you can't find the poetry binary
ExecStart=/home/lnbits/.local/bin/poetry run lnbits
# replace with the user that you're running LNbits on
User=lnbits
# Making a file masking of denying on reading files to all other users
UMask=0027
Restart=always
TimeoutSec=120
RestartSec=30
Environment=PYTHONUNBUFFERED=1
[Install]
WantedBy=multi-user.target
```
Save the file and run the following commands:
```
sudo systemctl enable lnbits.service
sudo systemctl start lnbits.service
```
</details>
<details><summary>Update LNbits</summary>