Skip to content

Commit a41b931

Browse files
Dominion5254Dominion5254
committed
README and more
1 parent af857e9 commit a41b931

File tree

10 files changed

+222
-130
lines changed

10 files changed

+222
-130
lines changed

‎.github/workflows/releaseService.yml‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,11 @@ jobs:
99
release:
1010
uses: start9labs/shared-workflows/.github/workflows/releaseService.yml@master
1111
with:
12-
REGISTRY: ${{ vars.REGISTRY }} # Optional. Defaults to https://alpha-registry-x.start9.com
12+
REGISTRY: ${{ vars.REGISTRY }}
13+
S3_S9PKS_BASE_URL: ${{ vars.S3_S9PKS_BASE_URL }}
1314
secrets:
14-
DEV_KEY: ${{ secrets.DEV_KEY }} # Required
15+
DEV_KEY: ${{ secrets.DEV_KEY }}
16+
S3_ACCESS_KEY: ${{ secrets.S3_ACCESS_KEY }}
17+
S3_SECRET_KEY: ${{ secrets.S3_SECRET_KEY }}
1518
permissions:
1619
contents: write

‎CONTRIBUTING.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Contributing
2+
3+
## Building and Development
4+
5+
See the [StartOS Packaging Guide](https://docs.start9.com/packaging-guide/) for complete environment setup and build instructions.
6+
7+
### Quick Start
8+
9+
```bash
10+
# Install dependencies
11+
npm ci
12+
13+
# Build universal package
14+
make
15+
```

‎Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
ARCHES ?= x86 arm
1+
ARCHES := x86 arm
22
# overrides to s9pk.mk must precede the include statement
33
include s9pk.mk

‎README.md‎

Lines changed: 176 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,180 @@
11
<p align="center">
2-
<img src="icon_readme.png" alt="Project Logo" width="21%">
2+
<img src="icon_readme.png" alt="LNbits Logo" width="21%">
33
</p>
44

5-
# LNbits for StartOS
5+
# LNbits on StartOS
66

7-
This repo packages [LNbits](https://github.com/lnbits/lnbits) for StartOS.
7+
> **Upstream docs:** <https://docs.lnbits.org/>
8+
>
9+
> Everything not listed in this document should behave the same as upstream
10+
> LNbits v1.4.2. If a feature, setting, or behavior is not mentioned
11+
> here, the upstream documentation is accurate and fully applicable.
12+
13+
A free and open-source lightning-network wallet/accounts system. See the [upstream repo](https://github.com/lnbits/lnbits) for general LNbits documentation.
14+
15+
---
16+
17+
## Table of Contents
18+
19+
- [Image and Container Runtime](#image-and-container-runtime)
20+
- [Volume and Data Layout](#volume-and-data-layout)
21+
- [Installation and First-Run Flow](#installation-and-first-run-flow)
22+
- [Configuration Management](#configuration-management)
23+
- [Network Access and Interfaces](#network-access-and-interfaces)
24+
- [Actions](#actions-startos-ui)
25+
- [Backups and Restore](#backups-and-restore)
26+
- [Health Checks](#health-checks)
27+
- [Dependencies](#dependencies)
28+
- [Limitations and Differences](#limitations-and-differences)
29+
- [What Is Unchanged from Upstream](#what-is-unchanged-from-upstream)
30+
- [Contributing](#contributing)
31+
- [Quick Reference for AI Consumers](#quick-reference-for-ai-consumers)
32+
33+
---
34+
35+
## Image and Container Runtime
36+
37+
| Property | Value |
38+
|----------|-------|
39+
| Image | Custom Dockerfile based on `lnbits/lnbits:v1.4.2` |
40+
| Architectures | x86_64, aarch64 |
41+
| Entrypoint | `uv run lnbits` |
42+
43+
The custom Dockerfile adds `sqlite3`, `tini`, `yq`, `xxd`, `curl`, `jq`, and `bcrypt` (Python) on top of the upstream image. These are used for the reset password action and other utilities.
44+
45+
## Volume and Data Layout
46+
47+
| Volume | Mount Point | Purpose |
48+
|--------|-------------|---------|
49+
| `main` | `/app/data` | All LNbits data (database, configuration) |
50+
51+
StartOS-specific files on the `main` volume:
52+
53+
| File | Purpose |
54+
|------|---------|
55+
| `.env` | LNbits environment configuration (managed by StartOS) |
56+
| `store.json` | Not used (no store.json in this package) |
57+
58+
The Lightning node volume is mounted read-only depending on the configured backend:
59+
60+
| Backend | Mount Point | Files Used |
61+
|---------|-------------|------------|
62+
| LND | `/mnt/lnd` | `tls.cert`, `data/chain/bitcoin/mainnet/admin.macaroon` |
63+
| CLN | `/mnt/cln` | `bitcoin/lightning-rpc` (Unix socket) |
64+
65+
## Installation and First-Run Flow
66+
67+
1. On install, StartOS creates a **critical task** prompting the user to select a Lightning implementation (LND or Core Lightning)
68+
2. The `.env` file is written with the selected backend configuration
69+
3. On first start, LNbits creates its SQLite database and presents a web UI for account creation
70+
4. The first user to register becomes the **super user** (admin)
71+
72+
## Configuration Management
73+
74+
LNbits is configured via environment variables in the `.env` file, managed by StartOS.
75+
76+
| StartOS-Managed | Details |
77+
|-----------------|---------|
78+
| Lightning backend | LND (REST) or Core Lightning (Unix socket) |
79+
80+
Most LNbits settings are configurable through the **Admin UI** within LNbits itself (`LNBITS_ADMIN_UI=true`). StartOS manages the backend connection; everything else is configured through the LNbits web interface.
81+
82+
Settings **not** managed by StartOS (hardcoded):
83+
84+
| Setting | Value | Reason |
85+
|---------|-------|--------|
86+
| `HOST` | `lnbits.startos` | StartOS service networking |
87+
| `PORT` | `5000` | Fixed internal port |
88+
| `FORWARDED_ALLOW_IPS` | `*` | Required for HTTPS behind StartOS proxy |
89+
| `LNBITS_DATA_FOLDER` | `./data` | Maps to the mounted volume |
90+
| `LND_REST_ENDPOINT` | `https://lnd.startos:8080/` | StartOS service networking |
91+
| `LND_REST_CERT` / `LND_REST_MACAROON` | Paths in `/mnt/lnd` | Mounted dependency volume |
92+
| `CLIGHTNING_RPC` | `/mnt/cln/bitcoin/lightning-rpc` | Mounted dependency volume |
93+
| `AUTH_ALLOWED_METHODS` | `username-password` | Only username/password auth |
94+
| `LNBITS_ALLOWED_FUNDING_SOURCES` | Matches selected backend | Restricted to configured implementation |
95+
96+
## Network Access and Interfaces
97+
98+
| Interface | Port | Protocol | Purpose |
99+
|-----------|------|----------|---------|
100+
| Web UI | 5000 | HTTP | LNbits web interface and API |
101+
102+
## Actions (StartOS UI)
103+
104+
| Action | Purpose | Availability | Inputs |
105+
|--------|---------|-------------|--------|
106+
| **Lightning Implementation** | Select LND or Core Lightning as the backend | Any | Select: LND or CLN |
107+
| **Reset Password** | Reset the super user password to a random value | Running only | None |
108+
109+
**Warning:** Changing the Lightning implementation after initial use **deletes the LNbits database** (all accounts and wallets). Funds remain on the underlying Lightning node.
110+
111+
## Backups and Restore
112+
113+
**Backed up:** The entire `main` volume (database, `.env` configuration).
114+
115+
**Restore behavior:** Standard restore — the database and configuration are restored as-is. The configured Lightning backend must be available.
116+
117+
## Health Checks
118+
119+
| Check | Method | Messages |
120+
|-------|--------|----------|
121+
| **Web Interface** | Port listening (5000), 75s grace period | Ready: "The web interface is ready" |
122+
123+
## Dependencies
124+
125+
| Dependency | Required | Version | Purpose |
126+
|------------|----------|---------|---------|
127+
| Core Lightning | Optional | `>=25.12:1-beta.1` | Lightning backend (if selected) |
128+
| LND | Optional | `>=0.20.0-beta:1-beta.2` | Lightning backend (if selected) |
129+
130+
One of the two Lightning implementations must be selected and running. The dependency is determined at runtime based on the configured `LNBITS_BACKEND_WALLET_CLASS`.
131+
132+
## Limitations and Differences
133+
134+
1. **Only LND and Core Lightning backends supported** — upstream supports many funding sources (LNPayWallet, OpenNodeWallet, EclairWallet, etc.); StartOS restricts to `LndRestWallet` and `CoreLightningWallet`
135+
2. **SQLite only** — upstream supports PostgreSQL and CockroachDB; StartOS uses the embedded SQLite database
136+
3. **Username/password auth only** — `AUTH_ALLOWED_METHODS` is set to `username-password`; other methods (e.g., Google OAuth) are not available
137+
4. **Switching backends deletes the database** — changing from LND to CLN (or vice versa) removes the existing LNbits database
138+
5. **Custom Docker image** — adds sqlite3 CLI, bcrypt, and other tools not in the upstream image
139+
140+
## What Is Unchanged from Upstream
141+
142+
- All LNbits extensions and the extension marketplace
143+
- Wallet and account management
144+
- Admin UI functionality
145+
- API endpoints
146+
- Invoice and payment handling
147+
- LNURL support
148+
- Theme customization (via Admin UI)
149+
150+
## Contributing
151+
152+
See [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions and development workflow.
153+
154+
---
155+
156+
## Quick Reference for AI Consumers
157+
158+
```yaml
159+
package_id: lnbits
160+
upstream_version: 1.4.2
161+
image: custom Dockerfile (based on lnbits/lnbits:v1.4.2)
162+
architectures: [x86_64, aarch64]
163+
volumes:
164+
main: /app/data
165+
ports:
166+
ui: 5000
167+
dependencies:
168+
- c-lightning (optional, >=25.12:1-beta.1)
169+
- lnd (optional, >=0.20.0-beta:1-beta.2)
170+
startos_managed_env_vars:
171+
- LNBITS_BACKEND_WALLET_CLASS
172+
- LNBITS_ALLOWED_FUNDING_SOURCES
173+
actions:
174+
- set-lightning-implementation
175+
- reset-password
176+
health_checks:
177+
- port_listening: 5000
178+
backup_volumes:
179+
- main
180+
```

‎docs/instructions.md‎

Lines changed: 0 additions & 44 deletions
This file was deleted.

‎docs/wallet-integrations/alby-extension.md‎

Lines changed: 0 additions & 27 deletions
This file was deleted.

‎docs/wallet-integrations/bluewallet.md‎

Lines changed: 0 additions & 25 deletions
This file was deleted.

‎docs/wallet-integrations/zeus.md‎

Lines changed: 0 additions & 27 deletions
This file was deleted.

‎s9pk.mk‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,30 @@ install: | check-deps check-init
7777
printf "\n🚀 Installing %s to %s ...\n" "$$S9PK" "$$HOST"; \
7878
start-cli package install -s "$$S9PK"
7979

80+
publish: | all
81+
@REGISTRY=$$(awk -F'/' '/^registry:/ {print $$3}' ~/.startos/config.yaml); \
82+
if [ -z "$$REGISTRY" ]; then \
83+
echo "Error: You must define \"registry: https://my-registry.tld\" in ~/.startos/config.yaml"; \
84+
exit 1; \
85+
fi; \
86+
S3BASE=$$(awk -F'/' '/^s9pk-s3base:/ {print $$3}' ~/.startos/config.yaml); \
87+
if [ -z "$$S3BASE" ]; then \
88+
echo "Error: You must define \"s3base: https://s9pks.my-s3-bucket.tld\" in ~/.startos/config.yaml"; \
89+
exit 1; \
90+
fi; \
91+
command -v s3cmd >/dev/null || \
92+
(echo "Error: s3cmd not found. It must be installed to publish using s3." && exit 1); \
93+
printf "\n🚀 Publishing to %s; indexing on %s ...\n" "$$S3BASE" "$$REGISTRY"; \
94+
for s9pk in *.s9pk; do \
95+
age=$$(( $$(date +%s) - $$(stat -c %Y "$$s9pk") )); \
96+
if [ "$$age" -gt 3600 ]; then \
97+
printf "\033[1;33m⚠️ %s is %d minutes old. Publish anyway? [y/N] \033[0m" "$$s9pk" "$$((age / 60))"; \
98+
read -r ans; \
99+
case "$$ans" in [yY]*) ;; *) echo "Skipping $$s9pk"; continue ;; esac; \
100+
fi; \
101+
start-cli s9pk publish "$$s9pk"; \
102+
done
103+
80104
check-deps:
81105
@command -v start-cli >/dev/null || \
82106
(echo "Error: start-cli not found. Please see https://docs.start9.com/latest/developer-guide/sdk/installing-the-sdk" && exit 1)

‎startos/manifest/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ export const manifest = setupManifest({
1111
marketingSite: 'https://lnbits.com/',
1212
donationUrl: 'https://demo.lnbits.com/tipjar/DwaUiE4kBX6mUW6pj3X5Kg',
1313
docsUrl:
14-
'https://github.com/Start9Labs/lnbits-startos/blob/master/instructions.md',
14+
'https://docs.lnbits.org/',
1515
description: { short, long },
1616
volumes: ['main'],
1717
images: {

0 commit comments

Comments
 (0)