Core Lightning Application

Run a Core Lightning application for your node. An official app by Blockstream. Powered by Core Lightning.

Prerequisites

Functioning and synced Bitcoin & Core lightning node.
Node.js, which can be downloaded here
Recommended Browsers: Chrome, Firefox, MS Edge

Getting started

Standalone

Get latest release

wget https://github.com/ElementsProject/cln-application/archive/refs/tags/v0.0.1.tar.gz
tar -xzf v0.0.1.tar.gz

Dependency Installation

cd cln-application-0.0.1
npm install --omit=dev

Environment Variables

This application accepts & depends upon these variables to be passed through environment:

- APP_CORE_LIGHTNING_IP: IP address of this application (cln-application) container (required)
- APP_CORE_LIGHTNING_PORT: Port on which this application should be served (required)
- APP_CORE_LIGHTNING_DAEMON_IP: IP address of Core lightning node container (required)
- APP_CORE_LIGHTNING_WEBSOCKET_PORT: Core lightning's websocket port (required; from cln's config.json; starting with `bind-addr=ws:`)
- APP_CONFIG_DIR: Path for cln-application's configuration file (required; config.json)
- COMMANDO_CONFIG: Full Path including file name for commando auth with PUBKEY & RUNE (required)
- APP_BITCOIN_NODE_IP: IP address of bitcoin node container (required)
- APP_CORE_LIGHTNING_BITCOIN_NETWORK: Bitcoin network type (optional; for entrypoint.sh; valid values: bitcoin/signet/testnet/regtest)
- APP_CORE_LIGHTNING_REST_PORT: c-lightning-REST server port (optional; for connect wallet screen)
- APP_CORE_LIGHTNING_REST_CERT_DIR: Path for c-lightning-REST certificates (optional; for connect wallet screen)
- APP_CORE_LIGHTNING_DAEMON_GRPC_PORT: Core lightning's GRPC port (optional; future proofing for connect wallet screen)
- APP_CORE_LIGHTNING_REST_HIDDEN_SERVICE: REST hidden service url (optional; for connect wallet screen; Used for Tor Domain also)
- DEVICE_DOMAIN_NAME: Device name/IP for lnmessage connect url feature (optional; for connect wallet screen)
- LOCAL_HOST: Device url for connect url links (optional; for connect wallet screen)
- APP_MODE: Mode for logging and other settings (valid values: production/development/testing, default: production)
- SINGLE_SIGN_ON: Flag to bypass application level authentication (valid values: true/false, default: false)
- APP_PROTOCOL: Protocol on which the application will be served (valid values: http/https, default: http)
- CORE_LIGHTNING_PATH: Path for core lightning (optional; required for entrypoint.sh)

Set these variables either via terminal OR by env.sh script OR by explicitly loading variables from .env files. Important Note: Environment variables take precedence over config.json variables. Like SINGLE_SIGN_ON will take higher precedence over singleSignOn from config.json.

Application Configuration

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:
```
{
  "unit": "SATS",
  "fiatUnit": "USD",
  "appMode": "DARK",
  "isLoading": false,
  "error": null,
  "singleSignOn": false,
  "password": ""
}
```
Commando Authentication
- This application utilizes lnmessage and 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.
- The backend server reads LIGHTNING_PUBKEY & LIGHTNING_RUNE from the COMMANDO_CONFIG file for this communication.
- Values can either be set manually or script entrypoint.sh can be used to call getinfo and createrune methods and save values in COMMANDO_CONFIG.
- entrypoint.sh can only run for the locally installed lightning. If cln-application is running remotely then pubkey and rune can be set manually.
- Sample commando config should look like:
```
  LIGHTNING_PUBKEY="03d2d3b2...0f8303bfe"
  LIGHTNING_RUNE="iv...4j"
```
Start The Application
- Setup environment variables either via terminal OR by env.sh script OR by explicitly loading variables from .env files.
- Run start script for starting your application's server at port APP_CORE_LIGHTNING_PORT
```
npm run start
```

Stores/Marketplaces
- This application is also available on Umbrel App Store and Start9 OS with one click install.

Contributing

We welcome and appreciate new contributions!
If you're a developer looking to help but not sure where to begin, look for these issues that have specifically been marked as being friendly to new contributors.
If you're looking for a bigger challenge, before opening a pull request please create an issue to get feedback, discuss the best way to tackle the challenge, and to ensure that there's no duplication of work.
Click here for instructions on how to run it in development mode.

Acknowledgements

This app is inspired by the work done by Umbrel lightning app.
The backend api connects with core lightning via lnmessage.

ElementsProject / cln-application

readme