docs: update admin ui readme.md (#3402)
Co-authored-by: Dein Name <deine.email@example.com> Co-authored-by: Arc <33088785+arcbtc@users.noreply.github.com>
This commit is contained in:
DoktorShift
GitHub
parent
2b1b5cadaa
commit
25c8dd18e0
7 changed files with 1165 additions and 397 deletions
|
|
@ -1,18 +1,45 @@
|
|||
---
|
||||
layout: default
|
||||
title: Basic installation
|
||||
nav_order: 2
|
||||
---
|
||||
<a href="https://lnbits.com" target="_blank" rel="noopener noreferrer">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://i.imgur.com/QE6SIrs.png">
|
||||
<img src="https://i.imgur.com/fyKPgVT.png" alt="LNbits" style="width:300px">
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
   [](https://extensions.lnbits.com/) [<img src="https://img.shields.io/badge/community_chat-Telegram-24A1DE">](https://t.me/lnbits) <img src="https://img.shields.io/badge/supported_by-%3E__OpenSats-f97316">
|
||||
|
||||
# Basic installation
|
||||
|
||||
Note that by default LNbits uses SQLite as its database, which is simple and effective but you can configure it to use PostgreSQL instead which is also described in a section below.
|
||||
> [!NOTE]
|
||||
> **Default DB:** LNbits uses SQLite by default (simple & effective). You can switch to PostgreSQL — see the section below.
|
||||
|
||||
## Option 1: AppImage (LInux)
|
||||
## Table of contents
|
||||
|
||||
### AppImage (Linux)
|
||||
- [Option 1: AppImage (Linux)](#option-1-appimage-linux)
|
||||
- [Option 2: UV (recommended for developers)](#option-2-uv-recommended-for-developers)
|
||||
- [Option 2a (Legacy): Poetry — Replaced by UV](#option-2a-legacy-poetry--replaced-by-uv)
|
||||
- [Option 3: Install script (Debian/Ubuntu)](#option-3-install-script-debianubuntu)
|
||||
- [Option 4: Nix](#option-4-nix)
|
||||
- [Option 5: Docker](#option-5-docker)
|
||||
- [Option 6: Fly.io](#option-6-flyio)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Optional: PostgreSQL database](#optional-postgresql-database)
|
||||
- [Using LNbits](#using-lnbits)
|
||||
- [Additional guides](#additional-guides)
|
||||
- [Update LNbits (all methods)](#update-lnbits-all-methods)
|
||||
- [SQLite → PostgreSQL migration](#sqlite--postgresql-migration)
|
||||
- [LNbits as a systemd service](#lnbits-as-a-systemd-service)
|
||||
- [Reverse proxy with automatic HTTPS (Caddy)](#reverse-proxy-with-automatic-https-caddy)
|
||||
- [Apache2 reverse proxy over HTTPS](#apache2-reverse-proxy-over-https)
|
||||
- [Nginx reverse proxy over HTTPS](#nginx-reverse-proxy-over-https)
|
||||
- [HTTPS without a reverse proxy (self-signed)](#https-without-a-reverse-proxy-self-signed)
|
||||
- [LNbits on Umbrel behind Tor](#lnbits-on-umbrel-behind-tor)
|
||||
- [FreeBSD notes](#freebsd-notes)
|
||||
|
||||
Go to [releases](https://github.com/lnbits/lnbits/releases) and pull latest AppImage, or:
|
||||
## Option 1: AppImage (Linux)
|
||||
|
||||
**Quickstart**
|
||||
|
||||
1. Download latest AppImage from [releases](https://github.com/lnbits/lnbits/releases) **or** run:
|
||||
|
||||
```sh
|
||||
sudo apt-get install jq libfuse2
|
||||
|
|
@ -21,19 +48,19 @@ chmod +x LNbits-latest.AppImage
|
|||
LNBITS_ADMIN_UI=true HOST=0.0.0.0 PORT=5000 ./LNbits-latest.AppImage # most system settings are now in the admin UI, but pass additional .env variables here
|
||||
```
|
||||
|
||||
LNbits will create a folder for db and extension files in the folder the AppImage runs from.
|
||||
- LNbits will create a folder for DB and extension files **in the same directory** as the AppImage.
|
||||
|
||||
> [!NOTE]
|
||||
> **Next steps**
|
||||
> Install complete → **[Running LNbits](#run-the-server)**
|
||||
> Update LNBits → **[Update LNbits (all methods)](#update-lnbits-all-methods)**
|
||||
|
||||
## Option 2: UV (recommended for developers)
|
||||
|
||||
It is recommended to use the latest version of UV. Make sure you have Python version `3.12` installed.
|
||||
> [!IMPORTANT]
|
||||
> **It is recommended to use the latest version of UV & Make sure you have Python version 3.12 installed.**
|
||||
|
||||
### Install Python 3.12
|
||||
|
||||
## Option 2 (recommended): UV
|
||||
|
||||
It is recommended to use the latest version of UV. Make sure you have Python version 3.10 or higher installed.
|
||||
|
||||
### Verify Python version
|
||||
### Verify Python
|
||||
|
||||
```sh
|
||||
python3 --version
|
||||
|
|
@ -46,15 +73,7 @@ curl -LsSf https://astral.sh/uv/install.sh | sh
|
|||
export PATH="$HOME/.local/bin:$PATH"
|
||||
```
|
||||
|
||||
### (old) Install Poetry
|
||||
|
||||
```sh
|
||||
# If path 'export PATH="$HOME/.local/bin:$PATH"' fails, use the path echoed by the install
|
||||
curl -sSL https://install.python-poetry.org | python3 -
|
||||
export PATH="$HOME/.local/bin:$PATH"
|
||||
```
|
||||
|
||||
### install LNbits
|
||||
### Install LNbits
|
||||
|
||||
```sh
|
||||
git clone https://github.com/lnbits/lnbits.git
|
||||
|
|
@ -62,10 +81,78 @@ cd lnbits
|
|||
git checkout main
|
||||
uv sync --all-extras
|
||||
|
||||
# or poetry
|
||||
# poetry env use 3.12
|
||||
# poetry install --only main
|
||||
cp .env.example .env
|
||||
# Optional: set funding source and other options in .env (e.g., `nano .env`)
|
||||
```
|
||||
|
||||
### Run the server
|
||||
|
||||
```sh
|
||||
uv run lnbits
|
||||
# To change port/host: uv run lnbits --port 9000 --host 0.0.0.0
|
||||
# Add --debug to the command above and set DEBUG=true in .env for verbose output
|
||||
```
|
||||
|
||||
### LNbits CLI
|
||||
|
||||
```sh
|
||||
# Useful for superuser ID, updating extensions, etc.
|
||||
uv run lnbits-cli --help
|
||||
```
|
||||
|
||||
### Update LNbits
|
||||
|
||||
```sh
|
||||
cd lnbits
|
||||
# Stop LNbits with Ctrl + X or your service manager
|
||||
# sudo systemctl stop lnbits
|
||||
|
||||
# Update code
|
||||
git pull --rebase
|
||||
|
||||
uv sync --all-extras
|
||||
uv run lnbits
|
||||
```
|
||||
|
||||
#### Use Admin UI → Extensions → "Update All" to bring extensions up to the proper level
|
||||
|
||||
> [!NOTE]
|
||||
> **Next steps**
|
||||
> Install complete → **[Running LNbits](#run-the-server)**
|
||||
> Update LNBits → **[Update LNbits (all methods)](#update-lnbits-all-methods)**
|
||||
|
||||
## Option 2a (Legacy): Poetry — _Replaced by UV_
|
||||
|
||||
<details>
|
||||
<summary><strong>Poetry install and update (legacy workflow)</summary>
|
||||
|
||||
This legacy section is preserved for older environments.
|
||||
**UV is the recommended (and faster) tool** for new installs. Use Poetry only if you have personal preferences or must support an older workflow.
|
||||
|
||||
> 
|
||||
> **It is recommended to use the latest version of Poetry & Make sure you have Python version 3.12 installed.**
|
||||
|
||||
### Verify Python version
|
||||
|
||||
```sh
|
||||
python3 --version
|
||||
```
|
||||
|
||||
### Install Poetry
|
||||
|
||||
```sh
|
||||
# If path 'export PATH="$HOME/.local/bin:$PATH"' fails, use the path echoed by the install
|
||||
curl -sSL https://install.python-poetry.org | python3 - && export PATH="$HOME/.local/bin:$PATH"
|
||||
```
|
||||
|
||||
### Install LNbits
|
||||
|
||||
```sh
|
||||
git clone https://github.com/lnbits/lnbits.git
|
||||
cd lnbits
|
||||
poetry env use 3.12
|
||||
git checkout main
|
||||
poetry install --only main
|
||||
cp .env.example .env
|
||||
# Optional: to set funding source amongst other options via the env `nano .env`
|
||||
```
|
||||
|
|
@ -73,50 +160,53 @@ cp .env.example .env
|
|||
#### Running the server
|
||||
|
||||
```sh
|
||||
uv run lnbits
|
||||
# To change port/host pass 'uv run lnbits --port 9000 --host 0.0.0.0'
|
||||
|
||||
# or poetry
|
||||
# poetry run lnbits
|
||||
# adding --debug in the start-up command above to help your troubleshooting and generate a more verbose output
|
||||
# Note that you have to add the line DEBUG=true in your .env file, too.
|
||||
poetry run lnbits
|
||||
# To change port/host: poetry run lnbits --port 9000 --host 0.0.0.0
|
||||
# Add --debug to help troubleshooting (also set DEBUG=true in .env)
|
||||
```
|
||||
|
||||
#### LNbits-cli
|
||||
#### LNbits CLI
|
||||
|
||||
```sh
|
||||
# A very useful terminal client for getting the supersuer ID, updating extensions, etc
|
||||
uv run lnbits-cli --help
|
||||
# A very useful terminal client for getting the superuser ID, updating extensions, etc.
|
||||
poetry run lnbits-cli --help
|
||||
```
|
||||
|
||||
#### Updating the server
|
||||
|
||||
```sh
|
||||
cd lnbits
|
||||
# Stop LNbits with `ctrl + x` or with service manager
|
||||
# Stop LNbits with Ctrl + X or with your service manager
|
||||
# sudo systemctl stop lnbits
|
||||
|
||||
# Update LNbits
|
||||
git pull --rebase
|
||||
|
||||
# Check your poetry version with
|
||||
# poetry env list
|
||||
# If version is less 3.12, update it by running
|
||||
# poetry env use python3.12
|
||||
# poetry env remove python3.9
|
||||
# poetry env list
|
||||
# Check your Poetry Python version
|
||||
poetry env list
|
||||
# If version is less than 3.12, update it:
|
||||
poetry env use python3.12
|
||||
poetry env remove python3.X
|
||||
poetry env list
|
||||
|
||||
# Run install and start LNbits with
|
||||
# poetry install --only main
|
||||
# poetry run lnbits
|
||||
|
||||
uv sync --all-extras
|
||||
uv run lnbits
|
||||
|
||||
# use LNbits admin UI Extensions page function "Update All" do get extensions onto proper level
|
||||
# Reinstall and start
|
||||
poetry install --only main
|
||||
poetry run lnbits
|
||||
```
|
||||
|
||||
## Option 2: Install script (on Debian/Ubuntu)
|
||||
#### Use Admin UI → Extensions → "Update All" to bring extensions up to the proper level
|
||||
|
||||
> 
|
||||
> **Next steps**
|
||||
> Install complete → **[Running LNbits](#run-the-server)**
|
||||
> Update LNBits → **[Update LNbits (all methods)](#update-lnbits-all-methods)**
|
||||
|
||||
</details>
|
||||
|
||||
## Option 3: Install script (Debian/Ubuntu)
|
||||
|
||||
<details>
|
||||
<summary><strong>Show install script</strong> (one-line setup)</summary>
|
||||
|
||||
```sh
|
||||
wget https://raw.githubusercontent.com/lnbits/lnbits/main/lnbits.sh &&
|
||||
|
|
@ -124,11 +214,19 @@ chmod +x lnbits.sh &&
|
|||
./lnbits.sh
|
||||
```
|
||||
|
||||
Now visit `0.0.0.0:5000` to make a super-user account.
|
||||
- You can use `./lnbits.sh` to run, but for more control: `cd lnbits` and use `uv run lnbits` (see Option 2).
|
||||
|
||||
`./lnbits.sh` can be used to run, but for more control `cd lnbits` and use `uv run lnbits` (see previous option).
|
||||
> 
|
||||
> **Next steps**
|
||||
> Install complete → **[Running LNbits](#run-the-server)**
|
||||
> Update LNBits → **[Update LNbits (all methods)](#update-lnbits-all-methods)**
|
||||
|
||||
## Option 3: Nix
|
||||
</details>
|
||||
|
||||
## Option 4: Nix
|
||||
|
||||
<details>
|
||||
<summary><strong>Show Nix instructions</strong> (flakes, cachix, run)</summary>
|
||||
|
||||
```sh
|
||||
# Install nix. If you have installed via another manager, remove and use this install (from https://nixos.org/download)
|
||||
|
|
@ -187,26 +285,36 @@ LNBITS_ADMIN_UI=true ./result/bin/lnbits --port 9000 --host 0.0.0.0
|
|||
SUPER_USER=be54db7f245346c8833eaa430e1e0405 LNBITS_ADMIN_UI=true ./result/bin/lnbits --port 9000
|
||||
```
|
||||
|
||||
## Option 4: Docker
|
||||
> 
|
||||
> **Next steps**
|
||||
> Update LNBits → **[Update LNbits (all methods)](#update-lnbits-all-methods)**
|
||||
|
||||
Use latest version from Docker Hub.
|
||||
</details>
|
||||
|
||||
## Option 5: Docker
|
||||
|
||||
<details>
|
||||
<summary><strong>Show Docker instructions</strong> (official image, volumes, extensions)</summary>
|
||||
|
||||
**Use latest image**
|
||||
|
||||
```sh
|
||||
docker pull lnbits/lnbits
|
||||
wget https://raw.githubusercontent.com/lnbits/lnbits/main/.env.example -O .env
|
||||
mkdir data
|
||||
docker run --detach --publish 5000:5000 --name lnbits --volume ${PWD}/.env:/app/.env --volume ${PWD}/data/:/app/data lnbits/lnbits
|
||||
docker run --detach --publish 5000:5000 --name lnbits \
|
||||
--volume ${PWD}/.env:/app/.env \
|
||||
--volume ${PWD}/data/:/app/data \
|
||||
lnbits/lnbits
|
||||
```
|
||||
|
||||
The LNbits Docker image comes with no extensions installed. User-installed extensions will be stored by default in a container directory.
|
||||
It is recommended to point the `LNBITS_EXTENSIONS_PATH` environment variable to a directory that is mapped to a Docker volume. This way, the extensions will not be reinstalled when the container is destroyed.
|
||||
Example:
|
||||
- The LNbits Docker image ships **without any extensions**; by default, any extensions you install are stored **inside the container** and will be **lost** when the container is removed, so you should set `LNBITS_EXTENSIONS_PATH` to a directory that’s **mapped to a persistent host volume** so extensions **survive rebuilds/recreates**—for example:
|
||||
|
||||
```sh
|
||||
docker run ... -e "LNBITS_EXTENSIONS_PATH='/app/data/extensions'" --volume ${PWD}/data/:/app/data ...
|
||||
```
|
||||
|
||||
Build the image yourself.
|
||||
**Build image yourself**
|
||||
|
||||
```sh
|
||||
git clone https://github.com/lnbits/lnbits.git
|
||||
|
|
@ -214,24 +322,39 @@ cd lnbits
|
|||
docker build -t lnbits/lnbits .
|
||||
cp .env.example .env
|
||||
mkdir data
|
||||
docker run --detach --publish 5000:5000 --name lnbits --volume ${PWD}/.env:/app/.env --volume ${PWD}/data/:/app/data lnbits/lnbits
|
||||
docker run --detach --publish 5000:5000 --name lnbits \
|
||||
--volume ${PWD}/.env:/app/.env \
|
||||
--volume ${PWD}/data/:/app/data \
|
||||
lnbits/lnbits
|
||||
```
|
||||
|
||||
You can optionally override the arguments that are passed to `poetry install` during the build process by setting the Docker build argument named `POETRY_INSTALL_ARGS`. For example, to enable the Breez funding source, build the Docker image with the command:
|
||||
You can optionally override the install extras for both **Poetry** and **UV** to include optional features during build or setup:
|
||||
|
||||
- with Poetry, pass extras via the `POETRY_INSTALL_ARGS` Docker build-arg (e.g., to enable the **Breez** funding source: `docker build --build-arg POETRY_INSTALL_ARGS="-E breez" -t lnbits/lnbits .`);
|
||||
- with UV, enable extras during environment sync (e.g., locally run `uv sync --extra breez` or `uv sync --all-extras`), and—**if your Dockerfile supports it**—you can mirror the same at build time via a build-arg such as `UV_SYNC_ARGS` (example pattern: `docker build --build-arg UV_SYNC_ARGS="--extra breez" -t lnbits/lnbits .`).
|
||||
|
||||
**Enable Breez funding source at build**
|
||||
|
||||
```sh
|
||||
docker build --build-arg POETRY_INSTALL_ARGS="-E breez" -t lnbits/lnbits .
|
||||
```
|
||||
|
||||
## Option 5: Fly.io
|
||||
> 
|
||||
> **Next steps**
|
||||
> Install complete → **[Running LNbits](#run-the-server)**
|
||||
> Update LNBits → **[Update LNbits (all methods)](#update-lnbits-all-methods)**
|
||||
|
||||
Fly.io is a docker container hosting platform that has a generous free tier. You can host LNbits for free on Fly.io for personal use.
|
||||
</details>
|
||||
|
||||
First, sign up for an account at [Fly.io](https://fly.io) (no credit card required).
|
||||
## Option 6: Fly.io
|
||||
|
||||
Then, install the Fly.io CLI onto your device [here](https://fly.io/docs/getting-started/installing-flyctl/).
|
||||
<details>
|
||||
<summary><strong>Deploy LNbits on Fly.io (free tier friendly)</summary>
|
||||
|
||||
After install is complete, the command will output a command you should copy/paste/run to get `fly` into your `$PATH`. Something like:
|
||||
**Fly.io is a docker container hosting platform that has a generous free tier. You can host LNbits for free on Fly.io for personal use.**
|
||||
|
||||
1. Create an account at [Fly.io](https://fly.io).
|
||||
2. Install the Fly.io CLI ([guide](https://fly.io/docs/getting-started/installing-flyctl/)).
|
||||
|
||||
```
|
||||
flyctl was installed successfully to /home/ubuntu/.fly/bin/flyctl
|
||||
|
|
@ -240,9 +363,9 @@ Manually add the directory to your $HOME/.bash_profile (or similar)
|
|||
export PATH="$FLYCTL_INSTALL/bin:$PATH"
|
||||
```
|
||||
|
||||
You can either run those commands, then `source ~/.bash_profile` or, if you don't, you'll have to call Fly from `~/.fly/bin/flyctl`.
|
||||
3. You can either run those commands, then `source ~/.bash_profile` or, if you don't, you'll have to call Fly from `~/.fly/bin/flyctl`.
|
||||
|
||||
Once installed, run the following commands.
|
||||
- Once installed, run the following commands.
|
||||
|
||||
```
|
||||
git clone https://github.com/lnbits/lnbits.git
|
||||
|
|
@ -256,9 +379,16 @@ You'll be prompted to enter an app name, region, postgres (choose no), deploy no
|
|||
|
||||
You'll now find a file in the directory called `fly.toml`. Open that file and modify/add the following settings.
|
||||
|
||||
Note: Be sure to replace `${PUT_YOUR_LNBITS_ENV_VARS_HERE}` with all relevant environment variables in `.env` or `.env.example`. Environment variable strings should be quoted here, so if in `.env` you have `LNBITS_ENDPOINT=https://demo.lnbits.com` in `fly.toml` you should have `LNBITS_ENDPOINT="https://demo.lnbits.com"`.
|
||||
> 
|
||||
> Be sure to replace `${PUT_YOUR_LNBITS_ENV_VARS_HERE}` with all relevant environment variables in `.env` or `.env.example`.
|
||||
> Environment variable strings should be quoted here. For example, if `.env` has
|
||||
> `LNBITS_ENDPOINT=https://demo.lnbits.com`, then in `fly.toml` use
|
||||
> `LNBITS_ENDPOINT="https://demo.lnbits.com"`.
|
||||
|
||||
Note: Don't enter secret environment variables here. Fly.io offers secrets (via the `fly secrets` command) that are exposed as environment variables in your runtime. So, for example, if using the LND_REST funding source, you can run `fly secrets set LND_REST_MACAROON=<hex_macaroon_data>`.
|
||||
> 
|
||||
> Don't enter secret environment variables here. Fly.io offers **secrets** (via `fly secrets`) that are exposed as env vars at runtime.
|
||||
> Example (LND REST funding source):
|
||||
> `fly secrets set LND_REST_MACAROON=<hex_macaroon_data>`
|
||||
|
||||
```
|
||||
...
|
||||
|
|
@ -313,26 +443,49 @@ sudo apt install python3.10-dev gcc build-essential
|
|||
poetry add setuptools wheel
|
||||
```
|
||||
|
||||
### Optional: PostgreSQL database
|
||||
> 
|
||||
>
|
||||
> **Next steps**
|
||||
> Install complete → **[Running LNbits](#run-the-server)**
|
||||
> Update LNbits → **[Update LNbits (all methods)](#update-lnbits-all-methods)**
|
||||
|
||||
If you want to use LNbits at scale, we recommend using PostgreSQL as the backend database. Install Postgres and setup a database for LNbits:
|
||||
## Troubleshooting
|
||||
|
||||
```sh
|
||||
# on debian/ubuntu 'sudo apt-get -y install postgresql'
|
||||
# or follow instructions at https://www.postgresql.org/download/linux/
|
||||
sudo apt install pkg-config libffi-dev libpq-dev
|
||||
|
||||
# Postgres doesn't have a default password, so we'll create one.
|
||||
# build essentials (Debian/Ubuntu)
|
||||
sudo apt install python3.10-dev gcc build-essential
|
||||
|
||||
# if secp256k1 build fails and you used poetry
|
||||
poetry add setuptools wheel
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
</details>
|
||||
|
||||
## Optional: PostgreSQL database
|
||||
|
||||
> [!TIP]
|
||||
> If you want to use LNbits at scale, we recommend using PostgreSQL as the backend database. Install Postgres and set up a database for LNbits.
|
||||
|
||||
```sh
|
||||
# Debian/Ubuntu: sudo apt-get -y install postgresql
|
||||
# or see https://www.postgresql.org/download/linux/
|
||||
|
||||
# Create a password for the postgres user
|
||||
sudo -i -u postgres
|
||||
psql
|
||||
# on psql
|
||||
ALTER USER postgres PASSWORD 'myPassword'; # choose whatever password you want
|
||||
# in psql
|
||||
ALTER USER postgres PASSWORD 'myPassword';
|
||||
\q
|
||||
# on postgres user
|
||||
# back as postgres user
|
||||
createdb lnbits
|
||||
exit
|
||||
```
|
||||
|
||||
You need to edit the `.env` file.
|
||||
**Configure LNbits**
|
||||
|
||||
```sh
|
||||
# add the database connection string to .env 'nano .env' LNBITS_DATABASE_URL=
|
||||
|
|
@ -343,44 +496,189 @@ LNBITS_DATABASE_URL="postgres://postgres:postgres@localhost:5432/lnbits"
|
|||
|
||||
# Using LNbits
|
||||
|
||||
Now you can visit your LNbits at http://localhost:5000/.
|
||||
Visit **[http://localhost:5000/](http://localhost:5000/)** (or `0.0.0.0:5000`).
|
||||
|
||||
Now modify the `.env` file with any settings you prefer and add a proper [funding source](./wallets.md) by modifying the value of `LNBITS_BACKEND_WALLET_CLASS` and providing the extra information and credentials related to the chosen funding source.
|
||||
### Option A — First-run setup in the Browser (UI)
|
||||
|
||||
Then you can restart it and it will be using the new settings.
|
||||
1. On the **first start**, LNbits will **prompt you to Setup a SuperUser**.
|
||||
2. After creating it, you’ll be **redirected to the Admin UI as SuperUser**.
|
||||
3. In the Admin UI, **set your funding source** (backend wallet) and other preferences.
|
||||
4. **Restart LNbits** if prompted or after changing critical settings.
|
||||
|
||||
You might also need to install additional packages or perform additional setup steps, depending on the chosen backend. See [the short guide](./wallets.md) on each different funding source.
|
||||
> [!IMPORTANT]
|
||||
> Use the **SuperUser only** for initial setup and instance settings (funding source, configuration, Topup).
|
||||
> For maintenance, create a separate **Admin** account. For everyday usage (payments, wallets, etc.), **do not use the SuperUser** — use admin or regular user accounts instead. Its a bad behaviour.
|
||||
> Read more about [SuperUser](./super_user.md) and [Admin UI](./admin_ui.md)
|
||||
|
||||
Take a look at [Polar](https://lightningpolar.com/) for an excellent way of spinning up a Lightning Network dev environment.
|
||||
### Option B — Configure via `.env`
|
||||
|
||||
1. Edit your `.env` with preferred settings (funding, base URL, etc.).
|
||||
2. Set a funding source by configuring:
|
||||
- `LNBITS_BACKEND_WALLET_CLASS`
|
||||
- plus the required credentials for your chosen backend (see **[wallets.md](./wallets.md)**).
|
||||
|
||||
3. **Restart LNbits** to apply changes.
|
||||
|
||||
---
|
||||
|
||||
> [!NOTE]
|
||||
> **Paths overview**
|
||||
>
|
||||
> - **SuperUser file:** `<lnbits_root>/data/.super_user`
|
||||
> Example: `~/lnbits/data/.super_user` • View: `cat ~/lnbits/data/.super_user`
|
||||
> - **Environment file:** `<lnbits_root>/.env` (for bare-metal installs)
|
||||
> - **Docker:** bind a host directory to `/app/data`.
|
||||
> On the host the SuperUser file is at `<host_data_dir>/.super_user`.
|
||||
> The container reads `/app/.env` (usually bind-mounted from your project root).
|
||||
|
||||
> [!TIP]
|
||||
> **Local Lightning test network**
|
||||
> Use **Polar** to spin up a safe local Lightning environment and test LNbits without touching your live setup.
|
||||
> https://lightningpolar.com/
|
||||
|
||||
> [!TIP]
|
||||
> **API comparison before updates**
|
||||
> Use **TableTown** to diff your LNbits instance against another (dev vs prod) or the upstream dev branch. Spot endpoint changes before updating.
|
||||
> Crafted by [Arbadacarbayk](https://github.com/arbadacarbaYK) - a standout contribution that makes pre-release reviews fast and reliable.
|
||||
> https://arbadacarbayk.github.io/LNbits_TableTown/
|
||||
|
||||
# Additional guides
|
||||
|
||||
## SQLite to PostgreSQL migration
|
||||
## Update LNbits (all methods)
|
||||
|
||||
If you already have LNbits installed and running, on an SQLite database, we **highly** recommend you migrate to postgres if you are planning to run LNbits on scale.
|
||||
> After updating, open **Admin UI → Extensions → “Update All”** to make sure extensions match the core version.
|
||||
|
||||
There's a script included that can do the migration easy. You should have Postgres already installed and there should be a password for the user (see Postgres install guide above). Additionally, your LNbits instance should run once on postgres to implement the database schema before the migration works:
|
||||
<details>
|
||||
<summary><strong>UV (recommended)</strong></summary>
|
||||
|
||||
```sh
|
||||
cd lnbits
|
||||
git pull --rebase
|
||||
uv sync --all-extras
|
||||
# restart (dev)
|
||||
uv run lnbits
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Poetry (legacy)</strong></summary>
|
||||
|
||||
```sh
|
||||
cd lnbits
|
||||
git pull --rebase
|
||||
# Optional: ensure Python 3.12
|
||||
poetry env list
|
||||
poetry env use python3.12
|
||||
poetry install --only main
|
||||
# restart (dev)
|
||||
poetry run lnbits
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>AppImage</strong></summary>
|
||||
|
||||
Download the latest AppImage from Releases and replace your old file **in the same directory** to keep the `./data` folder (DB, extensions).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Install script (Debian/Ubuntu)</strong></summary>
|
||||
|
||||
```sh
|
||||
# If you installed via lnbits.sh:
|
||||
cd lnbits
|
||||
git pull --rebase
|
||||
# then use your chosen runner (UV recommended)
|
||||
uv sync --all-extras
|
||||
uv run lnbits
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Nix</strong></summary>
|
||||
|
||||
```sh
|
||||
cd lnbits
|
||||
git pull --rebase
|
||||
nix build
|
||||
# restart
|
||||
nix run
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Docker (official image)</strong></summary>
|
||||
|
||||
```sh
|
||||
docker pull lnbits/lnbits
|
||||
docker stop lnbits && docker rm lnbits
|
||||
docker run --detach --publish 5000:5000 --name lnbits \
|
||||
--volume ${PWD}/.env:/app/.env \
|
||||
--volume ${PWD}/data/:/app/data \
|
||||
lnbits/lnbits
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Docker (build yourself)</strong></summary>
|
||||
|
||||
```sh
|
||||
cd lnbits
|
||||
git pull --rebase
|
||||
docker build -t lnbits/lnbits .
|
||||
docker stop lnbits && docker rm lnbits
|
||||
docker run --detach --publish 5000:5000 --name lnbits \
|
||||
--volume ${PWD}/.env:/app/.env \
|
||||
--volume ${PWD}/data/:/app/data \
|
||||
lnbits/lnbits
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Fly.io</strong></summary>
|
||||
|
||||
```sh
|
||||
# If using Dockerfile in repo (recommended)
|
||||
cd lnbits
|
||||
git pull --rebase
|
||||
fly deploy
|
||||
# Logs & shell if needed
|
||||
fly logs
|
||||
fly ssh console
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## SQLite → PostgreSQL migration
|
||||
|
||||
> [!TIP]
|
||||
> If you run on SQLite and plan to scale, migrate to Postgres.
|
||||
|
||||
```sh
|
||||
# STOP LNbits
|
||||
|
||||
# add the database connection string to .env 'nano .env' LNBITS_DATABASE_URL=
|
||||
# postgres://<user>:<password>@<host>/<database> - alter line bellow with your user, password and db name
|
||||
# Edit .env with Postgres URL
|
||||
LNBITS_DATABASE_URL="postgres://postgres:postgres@localhost/lnbits"
|
||||
# save and exit
|
||||
|
||||
# START LNbits
|
||||
# STOP LNbits
|
||||
# START then STOP LNbits once to apply schema
|
||||
uv run python tools/conv.py
|
||||
# or
|
||||
make migration
|
||||
```
|
||||
|
||||
Hopefully, everything works and get migrated... Launch LNbits again and check if everything is working properly.
|
||||
- Launch LNbits again and verify.
|
||||
|
||||
## LNbits as a systemd service
|
||||
|
||||
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:
|
||||
Create `/etc/systemd/system/lnbits.service`:
|
||||
|
||||
```
|
||||
# Systemd unit for lnbits
|
||||
|
|
@ -388,17 +686,14 @@ Systemd is great for taking care of your LNbits instance. It will start it on bo
|
|||
|
||||
[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)
|
||||
# Optional: start after your backend
|
||||
#Wants=lnd.service
|
||||
#After=lnd.service
|
||||
|
||||
[Service]
|
||||
# replace with the absolute path of your lnbits installation
|
||||
WorkingDirectory=/home/lnbits/lnbits
|
||||
# same here. run `which uv` if you can't find the poetry binary
|
||||
# Find uv path via `which uv`
|
||||
ExecStart=/home/lnbits/.local/bin/uv run lnbits
|
||||
# replace with the user that you're running lnbits on
|
||||
User=lnbits
|
||||
Restart=always
|
||||
TimeoutSec=120
|
||||
|
|
@ -409,33 +704,23 @@ Environment=PYTHONUNBUFFERED=1
|
|||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Save the file and run the following commands:
|
||||
Enable & start:
|
||||
|
||||
```sh
|
||||
sudo systemctl enable lnbits.service
|
||||
sudo systemctl start lnbits.service
|
||||
```
|
||||
|
||||
## Reverse proxy with automatic HTTPS using Caddy
|
||||
## Reverse proxy with automatic HTTPS (Caddy)
|
||||
|
||||
Use Caddy to make your LNbits install accessible over clearnet with a domain and https cert.
|
||||
Point your domain A-record to your server IP. Install Caddy: [Caddy install guide](https://caddyserver.com/docs/install#debian-ubuntu-raspbian)
|
||||
|
||||
Point your domain at the IP of the server you're running LNbits on, by making an `A` record.
|
||||
|
||||
Install Caddy on the server
|
||||
https://caddyserver.com/docs/install#debian-ubuntu-raspbian
|
||||
|
||||
```
|
||||
```sh
|
||||
sudo caddy stop
|
||||
```
|
||||
|
||||
Create a Caddyfile
|
||||
|
||||
```
|
||||
sudo nano Caddyfile
|
||||
```
|
||||
|
||||
Assuming your LNbits is running on port `5000` add:
|
||||
Add:
|
||||
|
||||
```
|
||||
yourdomain.com {
|
||||
|
|
@ -445,28 +730,21 @@ yourdomain.com {
|
|||
}
|
||||
```
|
||||
|
||||
Save and exit `CTRL + x`
|
||||
Save (Ctrl+X) and start:
|
||||
|
||||
```
|
||||
```sh
|
||||
sudo caddy start
|
||||
```
|
||||
|
||||
## Running behind an Apache2 reverse proxy over HTTPS
|
||||
|
||||
Install Apache2 and enable Apache2 mods:
|
||||
## Apache2 reverse proxy over HTTPS
|
||||
|
||||
```sh
|
||||
apt-get install apache2 certbot
|
||||
a2enmod headers ssl proxy proxy_http
|
||||
```
|
||||
|
||||
Create a SSL certificate with LetsEncrypt:
|
||||
|
||||
```sh
|
||||
certbot certonly --webroot --agree-tos --non-interactive --webroot-path /var/www/html -d lnbits.org
|
||||
```
|
||||
|
||||
Create an Apache2 vhost at: `/etc/apache2/sites-enabled/lnbits.conf`:
|
||||
Create `/etc/apache2/sites-enabled/lnbits.conf`:
|
||||
|
||||
```sh
|
||||
cat <<EOF > /etc/apache2/sites-enabled/lnbits.conf
|
||||
|
|
@ -493,27 +771,20 @@ cat <<EOF > /etc/apache2/sites-enabled/lnbits.conf
|
|||
EOF
|
||||
```
|
||||
|
||||
Restart Apache2:
|
||||
Restart:
|
||||
|
||||
```sh
|
||||
service apache2 restart
|
||||
```
|
||||
|
||||
## Running behind an Nginx reverse proxy over HTTPS
|
||||
|
||||
Install nginx:
|
||||
## Nginx reverse proxy over HTTPS
|
||||
|
||||
```sh
|
||||
apt-get install nginx certbot
|
||||
```
|
||||
|
||||
Create a SSL certificate with LetsEncrypt:
|
||||
|
||||
```sh
|
||||
certbot certonly --nginx --agree-tos -d lnbits.org
|
||||
```
|
||||
|
||||
Create an nginx vhost at `/etc/nginx/sites-enabled/lnbits.org`:
|
||||
Create `/etc/nginx/sites-enabled/lnbits.org`:
|
||||
|
||||
```sh
|
||||
cat <<EOF > /etc/nginx/sites-enabled/lnbits.org
|
||||
|
|
@ -547,23 +818,22 @@ server {
|
|||
EOF
|
||||
```
|
||||
|
||||
Restart nginx:
|
||||
Restart:
|
||||
|
||||
```sh
|
||||
service nginx restart
|
||||
```
|
||||
|
||||
## Using https without reverse proxy
|
||||
---
|
||||
|
||||
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.
|
||||
## HTTPS without a reverse proxy (self-signed)
|
||||
|
||||
We have to create a self-signed certificate using `mkcert`. Note that this certificate 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.
|
||||
Create a self-signed cert (useful for local/dev). Browsers won’t trust it by default.
|
||||
|
||||
#### Install mkcert
|
||||
### Install mkcert
|
||||
|
||||
You can find the install instructions for `mkcert` [here](https://github.com/FiloSottile/mkcert).
|
||||
|
||||
Install mkcert on Ubuntu:
|
||||
- Install instructions: [mkcert README](https://github.com/FiloSottile/mkcert)
|
||||
- Ubuntu example:
|
||||
|
||||
```sh
|
||||
sudo apt install libnss3-tools
|
||||
|
|
@ -572,70 +842,47 @@ chmod +x mkcert-v*-linux-amd64
|
|||
sudo cp mkcert-v*-linux-amd64 /usr/local/bin/mkcert
|
||||
```
|
||||
|
||||
#### Create certificate
|
||||
### Create certificate
|
||||
|
||||
To create a certificate, first `cd` into your LNbits folder and execute the following command on Linux:
|
||||
**OpenSSL**
|
||||
|
||||
```sh
|
||||
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/)):
|
||||
**mkcert** (alternative)
|
||||
|
||||
```sh
|
||||
# add your local IP (192.x.x.x) as well if you want to use it in your local network
|
||||
# include your local IP (e.g., 192.x.x.x) if needed
|
||||
mkcert localhost 127.0.0.1 ::1
|
||||
```
|
||||
|
||||
You can then pass the certificate files to uvicorn when you start LNbits:
|
||||
**Run with certs**
|
||||
|
||||
```sh
|
||||
poetry run uvicorn lnbits.__main__:app --host 0.0.0.0 --port 5000 --ssl-keyfile ./key.pem --ssl-certfile ./cert.pem
|
||||
```
|
||||
|
||||
## LNbits running on Umbrel behind Tor
|
||||
## LNbits on Umbrel behind Tor
|
||||
|
||||
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/guide-lnbits-without-tor/604) on how to do it.
|
||||
See this community [guide](https://community.getumbrel.com/t/guide-lnbits-without-tor/604).
|
||||
|
||||
## Docker installation
|
||||
## FreeBSD notes
|
||||
|
||||
To install using docker you first need to build the docker image as:
|
||||
Issue with secp256k1 0.14.0 on FreeBSD (thanks @GitKalle):
|
||||
|
||||
```
|
||||
git clone https://github.com/lnbits/lnbits.git
|
||||
cd lnbits
|
||||
docker build -t lnbits/lnbits .
|
||||
```
|
||||
1. Install `py311-secp256k1` with `pkg install py311-secp256k1`.
|
||||
2. Change version in `pyproject.toml` from `0.14.0` to `0.13.2`.
|
||||
3. Rewrite `poetry.lock` with `poetry lock`.
|
||||
4. Follow install instructions with Poetry.
|
||||
|
||||
You can launch the docker in a different directory, but make sure to copy `.env.example` from lnbits there
|
||||
---
|
||||
|
||||
```
|
||||
cp <lnbits_repo>/.env.example .env
|
||||
```
|
||||
## Powered by LNbits
|
||||
|
||||
and change the configuration in `.env` as required.
|
||||
LNbits empowers everyone with modular, open-source tools for building Bitcoin-based systems — fast, free, and extendable.
|
||||
|
||||
Then create the data directory
|
||||
If you like this project [send some tip love](https://demo.lnbits.com/tipjar/DwaUiE4kBX6mUW6pj3X5Kg) or visiting our [Shop](https://shop.lnbits.com)
|
||||
|
||||
```
|
||||
mkdir data
|
||||
```
|
||||
|
||||
Then the image can be run as:
|
||||
|
||||
```
|
||||
docker run --detach --publish 5000:5000 --name lnbits -e "LNBITS_BACKEND_WALLET_CLASS='FakeWallet'" --volume ${PWD}/.env:/app/.env --volume ${PWD}/data/:/app/data lnbits
|
||||
```
|
||||
|
||||
Finally you can access your lnbits on your machine at port 5000.
|
||||
|
||||
### FreeBSD notes
|
||||
|
||||
Currently there is an issue with secp256k1 0.14.0 on FreeBSD. Thanks to @GitKalle
|
||||
|
||||
1. Install package `py311-secp256k1` with `pkg install py311-secp256k1`
|
||||
2. Change version in `pyproject.toml` from 0.14.0 to 0.13.2
|
||||
3. Rewrite `poetry.lock` file with command `poetry lock`
|
||||
4. Follow install instruction with Poetry
|
||||
[](https://shop.lnbits.com/)
|
||||
[](https://shop.lnbits.com/) [](https://my.lnbits.com/login) [](https://news.lnbits.com/) [](https://extensions.lnbits.com/)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue