Skip to content

Commit e70373f

Browse files
ShahanaFarooquiShahanaFarooqui
committed
Documentation updates
1 parent 1437723 commit e70373f

17 files changed

Lines changed: 179 additions & 104 deletions

File tree

‎.github/docs/Contributing.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Development
22
-----------
3-
* Clone the project: git clone https://github.com/ElementsProject/umbrel-core-lightning.git
4-
* Change directory: cd umbrel-core-lightning
3+
* Clone the project: git clone https://github.com/ElementsProject/cln-application.git
4+
* Change directory: cd cln-application
55
* Install dependencies: Assuming that nodejs (v14 & above) and npm are already installed, run `npm install`.
66
* Setup environment variables: Assuming that bitcoind and core-lightning are already running, adjust environment variables listed in `./env.sh` file and execute the script with `'. env.sh'` to setup required environment variables to connect to the node.
77
* Setup Commando auth: Update `LIGHTNING_PUBKEY` and `LIGHTNING_RUNE` variables in `.commando-env` for successful backend authentication and connection via commando.

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@ data/bitcoin/*
66
data/lightningd/*
77
data/c-lightning-rest/*
88
data/app/application-cln.log
9+
application-cln.log
910
.commando-env
1011
env.sh

‎Dockerfile‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Build Stage
2-
FROM node:18-buster AS umbrel-lightning-app-builder
2+
FROM node:18-buster AS cln-app-builder
33

44
# Create app directory
55
WORKDIR /app
@@ -20,23 +20,23 @@ RUN npm run build
2020
RUN npm prune --omit=dev
2121

2222
# Final image
23-
FROM node:18-buster-slim AS umbrel-lightning
23+
FROM node:18-buster-slim AS cln-app-final
2424

2525
# Install jq for JSON parsing in entrypoint.sh
2626
RUN apt-get update && apt-get install -y jq socat
2727

2828
# Copy built code from build stages to '/app/frontend' directory
29-
COPY --from=umbrel-lightning-app-builder /app/apps/frontend/build /app/apps/frontend/build
30-
COPY --from=umbrel-lightning-app-builder /app/apps/frontend/public /app/apps/frontend/public
31-
COPY --from=umbrel-lightning-app-builder /app/apps/frontend/package.json /app/apps/frontend/package.json
29+
COPY --from=cln-app-builder /app/apps/frontend/build /app/apps/frontend/build
30+
COPY --from=cln-app-builder /app/apps/frontend/public /app/apps/frontend/public
31+
COPY --from=cln-app-builder /app/apps/frontend/package.json /app/apps/frontend/package.json
3232

3333
# Copy built code from build stages to '/app/backend' directory
34-
COPY --from=umbrel-lightning-app-builder /app/apps/backend/dist /app/apps/backend/dist
35-
COPY --from=umbrel-lightning-app-builder /app/apps/backend/package.json /app/apps/backend/package.json
34+
COPY --from=cln-app-builder /app/apps/backend/dist /app/apps/backend/dist
35+
COPY --from=cln-app-builder /app/apps/backend/package.json /app/apps/backend/package.json
3636

3737
# Copy built code from build stages to '/app' directory
38-
COPY --from=umbrel-lightning-app-builder /app/package.json /app/package.json
39-
COPY --from=umbrel-lightning-app-builder /app/node_modules /app/node_modules
38+
COPY --from=cln-app-builder /app/package.json /app/package.json
39+
COPY --from=cln-app-builder /app/node_modules /app/node_modules
4040

4141
# Change directory to '/app'
4242
WORKDIR /app

‎README.md‎

Lines changed: 102 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,120 @@
11
<p align="center">
2-
<a href="https://umbrel.com">
2+
<a href="https://github.com/ElementsProject/cln-application">
33
<img src="./.github/images/Dashboard.png" alt="Core Lightning Dashboard">
44
</a>
5-
<h1 align="center">Core Lightning Node for Umbrel</h1>
6-
<p align="center">
7-
Run a Core Lightning node on your Umbrel personal server. An official app by Blockstream. Powered by Core Lightning.
5+
<h1 align="center">Core Lightning Application</h1>
6+
<h3 align="center">
7+
Run a Core Lightning application for your node. An official app by Blockstream. Powered by Core Lightning.
88
<br />
9-
<a href="https://umbrel.com"><strong>umbrel.com »</strong></a>
109
<br />
11-
<br />
12-
<a href="https://twitter.com/umbrel">
13-
<img src="https://img.shields.io/twitter/follow/umbrel?style=social" />
14-
</a>
15-
<a href="https://t.me/getumbrel">
16-
<img src="https://img.shields.io/badge/community-chat-%235351FB">
17-
</a>
18-
<a href="https://reddit.com/r/getumbrel">
19-
<img src="https://img.shields.io/reddit/subreddit-subscribers/getumbrel?style=social">
20-
</a>
21-
<a href="https://community.getumbrel.com">
22-
<img src="https://img.shields.io/badge/community-forum-%235351FB">
10+
<a href="https://twitter.com/Blockstream">
11+
<img src="https://img.shields.io/twitter/follow/blockstream?style=social" />
2312
</a>
24-
</p>
13+
</h3>
2514
</p>
2615

27-
## Getting started
16+
---
2817

29-
This app can be installed in one click via the Umbrel App Store.
18+
# Prerequisites
19+
* Functioning and synced Bitcoin & Core lightning node.
20+
* Node.js, which can be downloaded [here](https://nodejs.org/en/download/)
21+
* Recommended Browsers: Chrome, Firefox, MS Edge
3022

3123
---
3224

33-
## Contributing
25+
# Getting started
26+
27+
- ## Standalone
28+
- ### Get latest release
29+
```
30+
wget https://github.com/ElementsProject/cln-application/archive/refs/tags/v0.0.1.tar.gz
31+
tar -xzf v0.0.1.tar.gz
32+
```
33+
34+
- ### Dependency Installation
35+
```
36+
cd cln-application-0.0.1
37+
npm install --omit=dev
38+
```
39+
40+
- ### Environment Variables
41+
This application accepts & depeneds upon these variables to be passed through environment:
42+
43+
```
44+
- APP_CORE_LIGHTNING_IP: IP address of the core lightning container (required)
45+
- APP_CORE_LIGHTNING_PORT: Port on which this application should be served (required)
46+
- APP_CORE_LIGHTNING_DAEMON_IP: Core lightning deamon bind address (cln config bind-addr; required)
47+
- APP_CORE_LIGHTNING_WEBSOCKET_PORT: Core lightning's websocket port (cln config experimental-websocket-port; required)
48+
- APP_CONFIG_DIR: Path for application's configuration file (config.json; required)
49+
- COMMANDO_CONFIG: Full Path including file name for commando auth with PUBKEY & RUNE (required)
50+
- APP_CORE_LIGHTNING_REST_PORT: c-lightning-REST server port (optional; for connect wallet screen)
51+
- APP_CORE_LIGHTNING_REST_CERT_DIR: Path for c-lightning-REST certificates (optional; for connect wallet screen)
52+
- APP_CORE_LIGHTNING_BITCOIN_NETWORK: Bitcoin network type (optional; required for entrypoint.sh; valid values: bitcoin/signet/testnet/regtest)
53+
- APP_CORE_LIGHTNING_DAEMON_GRPC_PORT: Core lightning's GRPC port (optional; future proofing for connect wallet screen)
54+
- APP_CORE_LIGHTNING_REST_HIDDEN_SERVICE: REST hidden service url (optional; for connect wallet screen)
55+
- LOCAL_HOST: Docker setup variable (optional; for connect wallet screen)
56+
- APP_MODE: Mode for logging and other settings (optional; valid values: production/development/testing)
57+
- CORE_LIGHTNING_PATH: Path for core lightning (optional; required for entrypoint.sh)
58+
```
59+
60+
Set these variables either via terminal OR by env.sh script OR by explicity loading varibles from .env files.
61+
62+
- ### Application Configuration
63+
This is the config.json file which is required by application's frontend. If the file named `config.json` is missing at `APP_CONFIG_DIR` location, one like below will be auto created:
64+
65+
```
66+
{
67+
"unit": "SATS",
68+
"fiatUnit": "USD",
69+
"appMode": "DARK",
70+
"isLoading": false,
71+
"error": null
72+
}
73+
```
74+
75+
- ### Commando Authentication
76+
- This application utilizes [lnmessage](https://github.com/aaronbarnardsound/lnmessage) and [commando](https://docs.corelightning.org/reference/lightning-commando) for connecting with core lightning node. The connection is trustless and end-to-end encrypted. Commando manages authentication and authorization through runes, which can grant either full or fine-grained permissions.
77+
- The backend server reads `LIGHTNING_PUBKEY` & `LIGHTNING_RUNE` from the `COMMANDO_CONFIG` file for this communication.
78+
- Values can either be set manually or script `entrypoint.sh` can be used to call `getinfo` and `commando-rune` methods and save values in `COMMANDO_CONFIG`.
79+
- Sample commando config should look like:
3480
35-
We welcome and appreciate new contributions!
81+
```
82+
LIGHTNING_PUBKEY="03d2d3b2...0f8303bfe"
83+
LIGHTNING_RUNE="iv...4j"
84+
```
3685
37-
If you're a developer looking to help but not sure where to begin, look for [these issues](https://github.com/ElementsProject/umbrel-core-lightning/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) that have specifically been marked as being friendly to new contributors.
86+
- ### Start The Application
87+
Run `build` script to build the aplication's backend and frontend
3888
39-
If you're looking for a bigger challenge, before opening a pull request please [create an issue](https://github.com/ElementsProject/umbrel-core-lightning/issues/new/choose) or [join umbrel community chat](https://t.me/getumbrel) to get feedback, discuss the best way to tackle the challenge, and to ensure that there's no duplication of work.
89+
```
90+
npm run build
91+
```
92+
93+
Run `start` script for starting your application's server at port `APP_CORE_LIGHTNING_PORT`
94+
95+
```
96+
npm run start
97+
```
98+
99+
- ## Umbrel Store
100+
### This application is also available on Umbrel App Store with one click install.
101+
102+
---
103+
104+
# Contributing
105+
106+
- We welcome and appreciate new contributions!
107+
108+
- If you're a developer looking to help but not sure where to begin, look for [these issues](https://github.com/ElementsProject/cln-application/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) that have specifically been marked as being friendly to new contributors.
109+
110+
- If you're looking for a bigger challenge, before opening a pull request please [create an issue](https://github.com/ElementsProject/cln-application/issues/new/choose) to get feedback, discuss the best way to tackle the challenge, and to ensure that there's no duplication of work.
111+
112+
- Click [here](./docs/Contributing.md) for instructions on how to run it in development mode.
113+
114+
---
40115
41-
Click [here](./docs/Contributing.md) for instructions on how to run it in development mode.
116+
# Acknowledgements
42117
43-
## Acknowledgements
118+
- This app is inpired by the work done by [Umbrel lightning app](https://github.com/getumbrel/umbrel-lightning).
44119
45-
This app is inpired by the work done by [Umbrel lightning app](https://github.com/getumbrel/umbrel-lightning).
46-
The backend api connects with core lightning via [lnmessage](https://github.com/aaronbarnardsound/lnmessage).
120+
- The backend api connects with core lightning via [lnmessage](https://github.com/aaronbarnardsound/lnmessage).

‎apps/backend/package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
2-
"name": "umbrel-cln-backend",
2+
"name": "cln-application-backend",
33
"version": "0.0.3",
4-
"description": "Core lightning application backend on Umbrel",
4+
"description": "Core lightning application backend",
55
"private": true,
66
"license": "MIT",
77
"type": "module",

‎apps/backend/source/server.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,10 @@ let routes: Array<CommonRoutesConfig> = [];
2222
const app: express.Application = express();
2323
const server: http.Server = http.createServer(app);
2424

25-
const LIGHTNING_PORT = normalizePort(process.env.APP_CORE_LIGHTNING_PORT || '2103');
25+
const LIGHTNING_PORT =
26+
APP_CONSTANTS.APP_MODE === Environment.PRODUCTION
27+
? normalizePort(process.env.APP_CORE_LIGHTNING_PORT || '2103')
28+
: 4300;
2629
const APP_CORE_LIGHTNING_DAEMON_IP = process.env.APP_CORE_LIGHTNING_IP || 'localhost';
2730

2831
function normalizePort(val: string) {
@@ -51,10 +54,7 @@ app.use((req, res, next) => {
5154
});
5255
const corsOptions = {
5356
methods: 'GET, POST, PATCH, PUT, DELETE, OPTIONS',
54-
origin:
55-
APP_CONSTANTS.APP_MODE === Environment.PRODUCTION
56-
? 'http://' + APP_CORE_LIGHTNING_DAEMON_IP + ':' + LIGHTNING_PORT
57-
: 'http://' + APP_CORE_LIGHTNING_DAEMON_IP + ':4300',
57+
origin: 'http://' + APP_CORE_LIGHTNING_DAEMON_IP + ':' + LIGHTNING_PORT,
5858
credentials: true,
5959
allowedHeaders: 'Content-Type, X-XSRF-TOKEN, XSRF-TOKEN',
6060
};

‎apps/backend/source/service/lightning.service.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1-
import Lnmessage from 'lnmessage';
21
import * as fs from 'fs';
2+
import * as crypto from 'crypto';
3+
import Lnmessage from 'lnmessage';
34
import { LightningError } from '../models/errors.js';
45
import { HttpStatusCode, APP_CONSTANTS, LN_MESSAGE_CONFIG } from '../shared/consts.js';
56
import { logger } from '../shared/logger.js';
@@ -34,6 +35,8 @@ export class LightningService {
3435
method: method,
3536
params: methodParams,
3637
rune: APP_CONSTANTS.COMMANDO_RUNE,
38+
reqId: crypto.randomBytes(8).toString('hex'),
39+
reqIdPrefix: 'clnapp',
3740
})
3841
.then((commandRes: any) => {
3942
logger.info('Command Res for ' + method + ': ' + JSON.stringify(commandRes));

‎apps/backend/source/shared/consts.ts‎

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -28,21 +28,18 @@ export const APP_CONSTANTS = {
2828
APP_CORE_LIGHTNING_DAEMON_IP: process.env.APP_CORE_LIGHTNING_DAEMON_IP || 'localhost',
2929
LIGHTNING_WS_PORT: +(process.env.APP_CORE_LIGHTNING_WEBSOCKET_PORT || 5001),
3030
APP_MODE: process.env.APP_MODE || Environment.PRODUCTION,
31-
COMMANDO_ENV_LOCATION: join(
32-
process.env.APP_CORE_LIGHTNING_COMMANDO_ENV_DIR || '.',
33-
'.commando-env',
34-
),
31+
COMMANDO_ENV_LOCATION: process.env.COMMANDO_CONFIG || './.commando-env',
3532
MACAROON_PATH: join(process.env.APP_CORE_LIGHTNING_REST_CERT_DIR || '.', 'access.macaroon'),
3633
LOG_FILE_LOCATION: join(process.env.APP_CONFIG_DIR || '.', 'application-cln.log'),
3734
CONFIG_LOCATION: join(process.env.APP_CONFIG_DIR || '.', 'config.json'),
3835
};
3936

4037
export const DEFAULT_CONFIG = {
41-
"unit": "SATS",
42-
"fiatUnit": "USD",
43-
"appMode": "DARK",
44-
"isLoading": false,
45-
"error": null
38+
unit: 'SATS',
39+
fiatUnit: 'USD',
40+
appMode: 'DARK',
41+
isLoading: false,
42+
error: null,
4643
};
4744

4845
export const LN_MESSAGE_CONFIG = {

‎apps/frontend/package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
2-
"name": "umbrel-cln-frontend",
2+
"name": "cln-application-frontend",
33
"version": "0.0.3",
4-
"description": "Core lightning application frontend on Umbrel",
4+
"description": "Core lightning application frontend",
55
"private": true,
66
"license": "MIT",
77
"scripts": {

‎apps/frontend/public/index.html‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,7 @@
55
<link rel="icon" href="./images/cln-favicon.ico" />
66
<meta name="viewport" content="width=device-width, initial-scale=1" />
77
<meta name="color-scheme" content="light dark">
8-
<meta
9-
name="description"
10-
content="Core lightning application frontend on Umbrel"
11-
/>
8+
<meta name="description" content="Core lightning application" />
129
<link rel="apple-touch-icon" href="./images/cln-logo-dark.png" />
1310
<title>Core Lightning</title>
1411
</head>

0 commit comments

Comments
 (0)