mirror of
https://github.com/lightninglabs/lightning-terminal.git
synced 2026-08-13 12:33:36 +02:00
Simplified readme (#129)
Update README, simplify documentation Simplified to focus on the happy path * Connect to remote instance Instructions for connecting Terminal to a remote LND instance. * Add link to remote instance Link to new instructions for connecting Terminal to a remote LND instance. * Create build from source instructions Parse out the building from source instructions into a separate doc to simplify main README file. * Change configuration section Update configuration section to acknowledge ability to upgrade an LND instance to Terminal * Add upgrading section Ensure that there is a clear upgrade path for existing users that have modified their lnd.conf files to be compatible with Terminal * Reference integrated configuration doc Change configuration section to point to the integrate mode configuration doc. * Reference remote mode instructions In case the user needs further information point them to the more comprehensive instructions * Update configuration settings Change configuration settings to be more accurate and specific * Update compatibility Changed to v0.11.0-beta * Update README Add list of features and Daemon Versions table * Combine config links Put remote and integrated modes together but separate. * Create troubleshooting doc Specific information for troubleshooting * Add troubleshooting section Link out to the troubleshooting guide * Update configuration to interaction Make it more explicit as to what problem is being solved * Add quickstart section Quickstart section for those wanting to connect LiT with a standalone process on a remote host * Combine remote configs into one Reference the single remote config doc instead of chained docs. * Update doc/config-lnd-remote.md * Remove commands for downloading Sort of overkill in terms of info * Update README Add small changes to README to address comments * Update compile Address small nits * Update uipassword Make it clearer the password needs to be changed * Update with build tags Added build tags for LND since it is most likely the case that LND was built without tags.
This commit is contained in:
Justin O'Brien
GitHub
parent
3e6a77da85
commit
0ce30d4a37
5 changed files with 276 additions and 256 deletions
240
README.md
240
README.md
|
|
@ -2,197 +2,75 @@
|
|||
|
||||
|
||||
|
||||
Lightning Terminal (LiT) is a browser-based interface for managing channel liquidity.
|
||||
|
||||
|
||||
|
||||
Lightning Terminal (LiT) is a browser-based interface for managing the off-chain liquidity
|
||||
of your `lnd` Lightning Network node. It presents a visual representation of your channels
|
||||
and balances, while allowing you to perform submarine swaps via the
|
||||
[Lightning Loop](https://lightning.engineering/loop) service using a graphical interface.
|
||||
With a bird's eye view of all of your open channels, you can instantly see which ones need
|
||||
your immediate attention.
|
||||
## Features
|
||||
- Visualize your channels and balances
|
||||
- Perform submarine swaps via the [Lightning Loop](https://lightning.engineering/loop) service
|
||||
- Classify channels according to your node's operating mode
|
||||
- Run a single binary that integrates both [`loopd`](https://github.com/lightninglabs/loop) and [`faraday`](https://github.com/lightninglabs/faraday) daemons all in one
|
||||
|
||||
You can configure the UI to classify channels according to your node's operating mode.
|
||||
## Installation
|
||||
Download the latest binaries from the [releases](https://github.com/lightninglabs/lightning-terminal/releases) page.
|
||||
|
||||
- **Optimize for Receiving**: For merchants who primarily receive inbound Lightning
|
||||
payments, the channels with high local balances will be shaded red.
|
||||
- **Optimize for Routing**: For routing node operators, that want to keep their channels
|
||||
balanced close to 50%, the channels with a high balance in either direction will be
|
||||
flagged.
|
||||
- **Optimize for Sending**: For exchanges, fiat gateways, and other operators who
|
||||
primarily send outgoing Lightning payments, the channels with low local balances will
|
||||
be shaded red.
|
||||
## Execution
|
||||
Run Lightning Terminal with a local `lnd` instance:
|
||||
|
||||
## Architecture
|
||||
```
|
||||
./litd --uipassword=UP48lm4Vjqxy<change_this_or_you_will_get_robbed>
|
||||
```
|
||||
|
||||
LiT is packaged as a single binary which contains the
|
||||
[`lnd`](https://github.com/lightningnetwork/lnd),
|
||||
[`loopd`](https://github.com/lightninglabs/loop) and
|
||||
[`faraday`](https://github.com/lightninglabs/faraday) daemons all in one. It also contains
|
||||
an HTTP server to serve the web assets (html/js/css) and a GRPC proxy to forward web
|
||||
requests from the browser to the appropriate GRPC server. This deployment strategy was
|
||||
chosen as it greatly simplifies the operational overhead of installation, configuration
|
||||
and maintenance that would be necessary to run each of these servers independently. You
|
||||
only need to download one executable and run one command to get LiT up and running. We
|
||||
include the CLI binaries `lncli`, `loop` and `frcli` for convenience in the downloadable
|
||||
archives as well.
|
||||
Visit https://localhost:8443 to access Terminal.
|
||||
|
||||
### Daemon Versions packaged with LiT
|
||||
Note that a password with a minimum of 8 characters is required to run Lightning Terminal. In a production environment, it's recommended that you store this password as an environment variable to avoid it being recorded in the command history.
|
||||
|
||||
To use LiT with a remote `lnd` instance please [follow these instructions](./doc/config-lnd-remote.md). If you would like to replace your existing LND instance with the one integrated within LiT please see [configuring Terminal](./doc/config-lnd-integrated.md).
|
||||
|
||||
## LND
|
||||
Note that LiT requires `lnd` to be built with **all of its subservers** and requires running at least v0.11.0. Download the latest [official release binary](https://github.com/lightningnetwork/lnd/releases/latest) or build `lnd` from source by following the [installation instructions](https://github.com/lightningnetwork/lnd/blob/master/docs/INSTALL.md). If you choose to build `lnd` from source, use the following command to enable all the relevant subservers:
|
||||
|
||||
```
|
||||
make install tags="signrpc walletrpc chainrpc invoicesrpc"
|
||||
```
|
||||
|
||||
## Interaction
|
||||
If you plan to run LiT on a remote machine but access the web-interface from your computer you may not want to deal with self-signed certificate browser warnings. To avoid these warnings configure the HTTP server to use a certificate from [Let's Encrypt](https://letsencrypt.org/). View the
|
||||
[Let's Encrypt Configuration](./doc/letsencrypt.md) doc for instructions on how to configure this.
|
||||
|
||||
## Upgrading
|
||||
If you used command line arguments with previous versions then you don't need to change anything when upgrading.
|
||||
|
||||
To upgrade from v0.1.1-alpha or earlier simply create a `lit.conf` file in your LiT directory. The default location LiT uses depends on your operating system:
|
||||
- MacOS: `~/Library/Application Support/Lit/lit.conf`
|
||||
- Linux: `~/.lit/lit.conf`
|
||||
- Windows: `~/AppData/Roaming/Lit/lit.conf`
|
||||
|
||||
Move all the configuration settings specific to LiT from `lnd.conf` to `lit.conf` and remove any previous LiT-specific customizations from the configuration settings in `lnd.conf`. Note that any section headers (`[ Example ]`) in `lit.conf` should be removed or changed to comments (`# Example`).
|
||||
|
||||
## Usage
|
||||
Read the [walkthrough](doc/WALKTHROUGH.md) document to learn more about how to use LiT.
|
||||
|
||||
## Troubleshooting
|
||||
If you encounter any issues please see our [troubleshooting guide](./doc/troubleshooting.md).
|
||||
|
||||
## Build from source
|
||||
If you’d prefer to compile from source code please follow [these instructions](./doc/compile.md).
|
||||
|
||||
## Compatibility
|
||||
|
||||
Lightning Terminal is backwards compatible with `lnd` back to version v0.11.0-beta
|
||||
|
||||
| LiT | LND |
|
||||
| ---------------- | ------------ |
|
||||
| **v0.2.0-alpha** | v0.11.0-beta |
|
||||
|
||||
## Daemon Versions packaged with LiT
|
||||
|
||||
| LiT | LND | Loop | Faraday |
|
||||
| ---------------- | ------------ | ----------- | ------------ |
|
||||
| **v0.2.0-alpha** | v0.11.1-beta | v0.9.0-beta | v0.2.1-alpha |
|
||||
| **v0.2.0-alpha** | v0.11.1-beta | v0.9.0-beta | v0.2.0-alpha |
|
||||
| **v0.1.1-alpha** | v0.11.0-beta | v0.8.1-beta | v0.2.0-alpha |
|
||||
| **v0.1.0-alpha** | v0.10.3-beta | v0.6.5-beta | v0.2.0-alpha |
|
||||
|
||||
## Usage
|
||||
|
||||
Read the [Walkthrough](doc/WALKTHROUGH.md) document to learn more about how to use
|
||||
Lightning Terminal.
|
||||
|
||||
## Installation
|
||||
|
||||
There are two options for installing LiT: download the published binaries for your
|
||||
platform, or compile from source code.
|
||||
|
||||
#### Download Binaries
|
||||
|
||||
LiT binaries for many platforms are made available on the GitHub
|
||||
[Releases](https://github.com/lightninglabs/lightning-terminal/releases) page in this
|
||||
repo. There you can download the latest version and extract the archive into a directory
|
||||
on your computer.
|
||||
|
||||
#### Compile from Source Code
|
||||
|
||||
To compile from source code, you'll need to have some prerequisite developer tooling
|
||||
installed on your machine.
|
||||
|
||||
| Dependency | Description |
|
||||
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| [golang](https://golang.org/doc/install) | LiT's backend web server is written in Go. The minimum version supported is Go v1.13. |
|
||||
| [protoc](https://grpc.io/docs/protoc-installation/) | Required to compile LND & Loop gRPC proto files at build time |
|
||||
| [nodejs](https://nodejs.org/en/download/) | LiT's frontend is written in TypeScript and built on top of the React JS web framework. To bundle the assets into Javascript & CSS compatible with web browsers, NodeJS is required. |
|
||||
| [yarn](https://classic.yarnpkg.com/en/docs/install) | a popular package manager for NodeJS application dependencies |
|
||||
|
||||
Once you have the necessary prerequisites, LiT can be compiled by running the following
|
||||
commands:
|
||||
|
||||
```shell script
|
||||
$ git clone https://github.com/lightninglabs/lightning-terminal.git
|
||||
$ cd lightning-terminal
|
||||
$ make install
|
||||
```
|
||||
|
||||
This will produce the `litd` executable and add it to your `GOPATH`. The CLI binaries for
|
||||
`lncli`, `loop`, and `frcli` are not created by `make install`. You will need to download
|
||||
those binaries from the [lnd](https://github.com/lightningnetwork/lnd/releases),
|
||||
[loop](https://github.com/lightninglabs/loop/releases), and
|
||||
[faraday](https://github.com/lightninglabs/faraday/releases) repos manually.
|
||||
|
||||
#### Executing CLI Commands
|
||||
|
||||
When executing `loop` and `frcli` commands, you will need to specify the connection info
|
||||
since the daemons are now integrated into `lnd`'s GRPC server.
|
||||
|
||||
Examples:
|
||||
|
||||
```shell script
|
||||
$ loop --rpcserver=localhost:10009 --tlscertpath=$HOME/.lnd/tls.cert --macaroonpath=$HOME/.lnd/data/chain/bitcoin/mainnet/admin.macaroon
|
||||
```
|
||||
|
||||
```shell script
|
||||
$ frcli --rpcserver=localhost:10009 --tlscertpath=$HOME/.lnd/tls.cert --macaroonpath=$HOME/.lnd/data/chain/bitcoin/mainnet/admin.macaroon
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
LiT only has a few configuration parameters itself.
|
||||
|
||||
#### Required
|
||||
|
||||
You must set `httpslisten` to the host & port that the https server should listen on. Also
|
||||
set `uipassword` to a strong password to use to login to the website in your browser. A
|
||||
minimum of 8 characters is required. In a production environment, it's recommended that
|
||||
you store this password as an environment variable.
|
||||
|
||||
#### Optional
|
||||
|
||||
You can also configure the HTTP server to automatically install a free SSL certificate
|
||||
provided by [Let's Encrypt](https://letsencrypt.org/). This is recommended if you plan to
|
||||
access the website from a remote computer and do not want to deal with the browser warning
|
||||
you about the self-signed certificate. View the
|
||||
[Let's Encrypt Configuration](./doc/letsencrypt.md) doc for instructions on how to
|
||||
configure this.
|
||||
|
||||
```text
|
||||
Application Options:
|
||||
--httpslisten= host:port to listen for incoming HTTP/2 connections on (default: 127.0.0.1:8443)
|
||||
--uipassword= the password that must be entered when using the loop UI. use a strong
|
||||
password to protect your node from unauthorized access through the web UI
|
||||
--letsencrypt use Let's Encrypt to create a TLS certificate for the UI instead of using
|
||||
lnd's TLS certificate. port 80 must be free to listen on and must be reachable
|
||||
from the internet for this to work
|
||||
--letsencrypthost= the host name to create a Let's Encrypt certificate for'
|
||||
--letsencryptdir= the directory where the Let's Encrypt library will store its key and
|
||||
certificate (default: /Users/<username>/Library/Application Support/Lnd/letsencrypt)
|
||||
```
|
||||
|
||||
### Lnd mode
|
||||
|
||||
Starting with LiT `v0.2.0-alpha`, you now have the choice of either running an
|
||||
`lnd` node in the same process as the UI (which is called the "integrated" `lnd`
|
||||
mode) or connect the UI to an already running `lnd` node (called "remote" mode).
|
||||
|
||||
Because that single decision has an impact on the configuration options that
|
||||
need to be used, the documentation has been split into two parts, each
|
||||
explaining one mode in detail.
|
||||
|
||||
* Lnd mode **"remote"**
|
||||
+ Connect to a remote `lnd` instance, start the rest (the UI, `loop`,
|
||||
`faraday`) in the same process.
|
||||
+ [Please read the `lnd` **remote** mode configuration guide here.](doc/config-lnd-remote.md)
|
||||
+ This is the default mode that is used if the `--lnd-mode=` command line
|
||||
or `lnd-mode=` configuration option is not set explicitly.
|
||||
|
||||
* Lnd mode **"integrated"**
|
||||
+ Start everything (the UI, `lnd`, `loop`, `faraday`) in one single process.
|
||||
+ [Please read the `lnd` **integrated** mode configuration guide here.](doc/config-lnd-integrated.md)
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
If you have trouble running your node, please first check the logs for warnings or errors.
|
||||
If there are errors relating to one of the embedded servers, then you should open an issue
|
||||
in their respective GitHub repos ([lnd](https://github.com/lightningnetwork/lnd/issues),
|
||||
[loop](https://github.com/lightninglabs/loop/issues),
|
||||
[faraday](https://github.com/lightninglabs/faraday/issues). If the issue is related to the
|
||||
web app, then you should open an
|
||||
[issue](https://github.com/lightninglabs/lightning-terminal/issues) here in this repo.
|
||||
|
||||
#### Server
|
||||
|
||||
Server-side logs are stored in the directory specified by `lnd.lnddir` in your
|
||||
configuration. Inside, there is a `logs` dir containing the log files in subdirectories.
|
||||
Be sure to set `lnd.debuglevel=debug` in your configuration to see the most verbose
|
||||
logging information.
|
||||
|
||||
#### Browser
|
||||
|
||||
Client-side logs are disabled by default in production builds. Logging can be turned on by
|
||||
adding a couple keys to your browser's `localStorage`. Simply run these two JS statements
|
||||
in you browser's DevTools console then refresh the page:
|
||||
|
||||
```js
|
||||
localStorage.setItem('debug', '*'); localStorage.setItem('debug-level', 'debug');
|
||||
```
|
||||
|
||||
The value for `debug` is a namespace filter which determines which portions of the app to
|
||||
display logs for. The namespaces currently used by the app are as follows:
|
||||
|
||||
- `main`: logs general application messages
|
||||
- `action`: logs all actions that modify the internal application state
|
||||
- `grpc`: logs all GRPC API requests and responses
|
||||
|
||||
Example filters: `main,action` will only log main and action messages. `*,-action` will
|
||||
log everything except action messages.
|
||||
|
||||
The value for `debug-level` determines the verbosity of the logs. The value can be one of
|
||||
`debug`, `info`, `warn`, or `error`.
|
||||
|
|
|
|||
26
doc/compile.md
Normal file
26
doc/compile.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
## Compile from Source Code
|
||||
|
||||
To compile from source code, you'll need to have some prerequisite developer tooling
|
||||
installed on your machine.
|
||||
|
||||
| Dependency | Description |
|
||||
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| [golang](https://golang.org/doc/install) | LiT's backend web server is written in Go. The minimum version supported is Go v1.13. |
|
||||
| [protoc](https://grpc.io/docs/protoc-installation/) | Required to compile LND & Loop gRPC proto files at build time. |
|
||||
| [nodejs](https://nodejs.org/en/download/) | LiT's frontend is written in TypeScript and built on top of the React JS web framework. To bundle the assets into Javascript & CSS compatible with web browsers, NodeJS is required. |
|
||||
| [yarn](https://classic.yarnpkg.com/en/docs/install) | A popular package manager for NodeJS application dependencies. |
|
||||
|
||||
Once you have the necessary prerequisites, LiT can be compiled by running the following
|
||||
commands:
|
||||
|
||||
```shell script
|
||||
$ git clone https://github.com/lightninglabs/lightning-terminal.git
|
||||
$ cd lightning-terminal
|
||||
$ make install
|
||||
```
|
||||
|
||||
This will produce the `litd` executable and add it to your `GOPATH`. The CLI binaries for
|
||||
`lncli`, `loop`, and `frcli` are not created by `make install`. You will need to download
|
||||
those binaries from the [lnd](https://github.com/lightningnetwork/lnd/releases),
|
||||
[loop](https://github.com/lightninglabs/loop/releases), and
|
||||
[faraday](https://github.com/lightninglabs/faraday/releases) repos manually.
|
||||
|
|
@ -1,29 +1,78 @@
|
|||
# Configuring LiT with remote lnd node
|
||||
# Connecting LiT to a standalone LND process
|
||||
|
||||
The "remote" mode means that `lnd` is started as a standalone process, possibly
|
||||
on another host, and `litd` connects to it, right after starting its UI server.
|
||||
Once the connection to the remote `lnd` node has been established, `litd` then
|
||||
goes ahead and starts `faraday` and `loop` and connects them to that `lnd` node
|
||||
as well.
|
||||
By default LiT assumes that `lnd` is running as a standalone process locally. However
|
||||
`litd` can connect to `lnd` running on a remote host.
|
||||
|
||||
Currently the UI server cannot connect to `loop` or `faraday` daemons that
|
||||
aren't running in the same process. But that feature will also be available in
|
||||
future versions.
|
||||
## Quickstart
|
||||
|
||||
To connect Lightning Terminal to a remote LND instance first make sure your `lnd.conf`
|
||||
file contains the following additional configuration settings:
|
||||
|
||||
```
|
||||
tlsextraip=<externally-reachable-ip-address>
|
||||
rpclisten=0.0.0.0:10009
|
||||
```
|
||||
|
||||
Copy the following files that are located in your `~/.lnd/data/chain/bitcoin/mainnet`
|
||||
directory on your remote machine to `/some/folder/with/lnd/data/` on your local machine
|
||||
(where you’ll be running LiT):
|
||||
|
||||
- tls.cert
|
||||
- admin.macaroon
|
||||
- chainnotifier.macaroon
|
||||
- invoices.macaroon
|
||||
- readonly.macaroon
|
||||
- router.macaroon
|
||||
- signer.macaroon
|
||||
- walletkit.macaroon
|
||||
|
||||
Create a `lit.conf` file. The default location LiT will look for the configuration file
|
||||
depends on your operating system:
|
||||
|
||||
- MacOS: `~/Library/Application Support/Lit/lit.conf`
|
||||
- Linux: `~/.lit/lit.conf`
|
||||
- Windows: `~/AppData/Roaming/Lit/lit.conf`
|
||||
|
||||
Alternatively you can specify a different location by passing `--lit-dir=~/.lit`. After
|
||||
creating `lit.conf` populate it with the following configuration settings:
|
||||
|
||||
```
|
||||
remote.lnd.rpcserver=<externally-reachable-ip-address>:10009
|
||||
remote.lnd.macaroonpath=/some/folder/with/lnd/data/admin.macaroon
|
||||
remote.lnd.tlscertpath=/some/folder/with/lnd/data/tls.cert
|
||||
```
|
||||
|
||||
Run LiT:
|
||||
|
||||
```
|
||||
./litd --uipassword=UP48lm4VjqxmOxB9X9stry6VTKBRQI
|
||||
```
|
||||
|
||||
Visit https://localhost:8443 to access LiT.
|
||||
|
||||
## Additional Configuration
|
||||
|
||||
The "remote" mode means that `lnd` is started as a standalone process, possibly on another
|
||||
host, and `litd` connects to it, right after starting its UI server. Once the connection
|
||||
to the remote `lnd` node has been established, `litd` then goes ahead and starts `faraday`
|
||||
and `loop` and connects them to that `lnd` node as well.
|
||||
|
||||
Currently the UI server cannot connect to `loop` or `faraday` daemons that aren't running
|
||||
in the same process. But that feature will also be available in future versions.
|
||||
|
||||
## Use command line parameters only
|
||||
|
||||
In addition to the LiT specific and remote `lnd` parameters, you must also
|
||||
provide configuration to the `loop` and `faraday` daemons. For the remote `lnd`
|
||||
node, all `remote.lnd` flags must be specified. Note that `loopd` and
|
||||
`faraday` will automatically connect to the same remote `lnd` node, so you do
|
||||
not need to provide them with any additional parameters unless you want to
|
||||
override them. If you do override them, be sure to add the `loop.` and `faraday.`
|
||||
prefixes.
|
||||
In addition to the LiT specific and remote `lnd` parameters, you must also provide
|
||||
configuration to the `loop` and `faraday` daemons. For the remote `lnd` node, all
|
||||
`remote.lnd` flags must be specified. Note that `loopd` and `faraday` will automatically
|
||||
connect to the same remote `lnd` node, so you do not need to provide them with any
|
||||
additional parameters unless you want to override them. If you do override them, be sure
|
||||
to add the `loop.` and `faraday.` prefixes.
|
||||
|
||||
To see all available command line options, run `litd --help`.
|
||||
|
||||
The most minimal example command to start `litd` and connect it to a local `lnd`
|
||||
node that is running with default configuration settings is:
|
||||
The most minimal example command to start `litd` and connect it to a local `lnd` node that
|
||||
is running with default configuration settings is:
|
||||
|
||||
```shell script
|
||||
$ litd --uipassword=My$trongP@ssword
|
||||
|
|
@ -31,9 +80,8 @@ $ litd --uipassword=My$trongP@ssword
|
|||
|
||||
All other command line flags are only needed to overwrite the default behavior.
|
||||
|
||||
Here is an example command to start `litd` connected to a testnet `lnd` that is
|
||||
running on another host and overwrites a few default settings in `loop` and
|
||||
`faraday` (optional):
|
||||
Here is an example command to start `litd` connected to a testnet `lnd` that is running on
|
||||
another host and overwrites a few default settings in `loop` and `faraday` (optional):
|
||||
|
||||
```shell script
|
||||
$ litd \
|
||||
|
|
@ -55,38 +103,35 @@ $ litd \
|
|||
--faraday.bitcoin.password=testnetpw
|
||||
```
|
||||
|
||||
NOTE: Even though LiT itself only needs `lnd`'s `admin.macaroon`, the `loop` and
|
||||
`faraday` daemons will require other macaroons and will look for them in the
|
||||
folder specified with `--remote.lnd.macaroondir`. It is advised to copy all
|
||||
`*.macaroon` files and the `tls.cert` file from the remote host to the host that
|
||||
is running `litd`.
|
||||
NOTE: Even though LiT itself only needs `lnd`'s `admin.macaroon`, the `loop` and `faraday`
|
||||
daemons will require other macaroons and will look for them in the folder specified with
|
||||
`--remote.lnd.macaroondir`. It is advised to copy all `*.macaroon` files and the
|
||||
`tls.cert` file from the remote host to the host that is running `litd`.
|
||||
|
||||
## Use a configuration file
|
||||
|
||||
You can also store the configuration in a persistent `~/.lit/lit.conf` file, so
|
||||
you do not need to type in the command line arguments every time you start the
|
||||
server. Just remember to use the appropriate prefixes as necessary.
|
||||
You can also store the configuration in a persistent `~/.lit/lit.conf` file, so you do not
|
||||
need to type in the command line arguments every time you start the server. Just remember
|
||||
to use the appropriate prefixes as necessary.
|
||||
|
||||
Make sure you don't add any section headers (the lines starting with `[` and
|
||||
ending with `]`, for example `[Application Options]`) as these don't work with
|
||||
the additional levels of sub configurations. You can replace them with a
|
||||
comment (starting with the `#` character) to get the same grouping effect as
|
||||
before.
|
||||
Make sure you don't add any section headers (the lines starting with `[` and ending with
|
||||
`]`, for example `[Application Options]`) as these don't work with the additional levels
|
||||
of sub configurations. You can replace them with a comment (starting with the `#`
|
||||
character) to get the same grouping effect as before.
|
||||
|
||||
The most minimal example of a `~/.lit/lit.conf` file that connects to a local
|
||||
`lnd` node that is running with default configuration settings is:
|
||||
The most minimal example of a `~/.lit/lit.conf` file that connects to a local `lnd` node
|
||||
that is running with default configuration settings is:
|
||||
|
||||
```text
|
||||
# Application Options
|
||||
uipassword=My$trongP@ssword
|
||||
```
|
||||
|
||||
All other configuration settings are only needed to overwrite the default
|
||||
behavior.
|
||||
All other configuration settings are only needed to overwrite the default behavior.
|
||||
|
||||
Here is an example `~/.lit/lit.conf` file that connects LiT to a testnet `lnd`
|
||||
node running on another host and overwrites a few default settings in `loop` and
|
||||
`faraday` (optional):
|
||||
Here is an example `~/.lit/lit.conf` file that connects LiT to a testnet `lnd` node
|
||||
running on another host and overwrites a few default settings in `loop` and `faraday`
|
||||
(optional):
|
||||
|
||||
```text
|
||||
# Application Options
|
||||
|
|
@ -118,24 +163,21 @@ faraday.bitcoin.user=testnetuser
|
|||
faraday.bitcoin.password=testnetpw
|
||||
```
|
||||
|
||||
The default location for the `lit.conf` file will depend on your operating
|
||||
system:
|
||||
The default location for the `lit.conf` file will depend on your operating system:
|
||||
|
||||
- **On MacOS**: `~/Library/Application Support/Lit/lit.conf`
|
||||
- **On Linux**: `~/.lit/lit.conf`
|
||||
- **On Windows**: `~/AppData/Roaming/Lit/lit.conf`
|
||||
|
||||
|
||||
## Example commands for interacting with the command line
|
||||
|
||||
Because not all functionality of `lnd` (or `loop`/`faraday` for that matter) is
|
||||
available through the web UI, it will still be necessary to interact with those
|
||||
daemons through the command line.
|
||||
Because not all functionality of `lnd` (or `loop`/`faraday` for that matter) is available
|
||||
through the web UI, it will still be necessary to interact with those daemons through the
|
||||
command line.
|
||||
|
||||
We are going through an example for each of the command line tools and will
|
||||
explain the reasons for the extra flags.
|
||||
The examples assume that LiT is started with the following configuration (only
|
||||
relevant parts shown here):
|
||||
We are going through an example for each of the command line tools and will explain the
|
||||
reasons for the extra flags. The examples assume that LiT is started with the following
|
||||
configuration (only relevant parts shown here):
|
||||
|
||||
```text
|
||||
httpslisten=0.0.0.0:443
|
||||
|
|
@ -147,24 +189,22 @@ remote.lnd.macaroondir=/some/folder/with/lnd/data
|
|||
remote.lnd.tlscertpath=/some/folder/with/lnd/data/tls.cert
|
||||
```
|
||||
|
||||
Because in the remote `lnd` mode all other LiT components (`loop`, `faraday` and
|
||||
the UI server) listen on the same port (`443` in this example) and use the same
|
||||
TLS certificate (`~/.lit/tls.cert` in this example), some command line calls now
|
||||
need some extra options that weren't necessary before.
|
||||
Because in the remote `lnd` mode all other LiT components (`loop`, `faraday` and the UI
|
||||
server) listen on the same port (`443` in this example) and use the same TLS certificate
|
||||
(`~/.lit/tls.cert` in this example), some command line calls now need some extra options
|
||||
that weren't necessary before.
|
||||
|
||||
**NOTE**: All mentioned command line tools have the following behavior in
|
||||
common: You either specify the `--network` flag and the `--tlscertpath` and
|
||||
`--macaroonpath` are implied by looking inside the default directories for that
|
||||
network. Or you specify the `--tlscertpath` and `--macaroonpath` flags
|
||||
explicitly, then you **must not** set the `--network` flag. Otherwise, you will
|
||||
get an error like `[lncli] could not load global options: unable to read macaroon
|
||||
path (check the network setting!): open /home/<user>/.lnd/data/chain/bitcoin/testnet/admin.macaroon:
|
||||
no such file or directory`.
|
||||
**NOTE**: All mentioned command line tools have the following behavior in common: You
|
||||
either specify the `--network` flag and the `--tlscertpath` and `--macaroonpath` are
|
||||
implied by looking inside the default directories for that network. Or you specify the
|
||||
`--tlscertpath` and `--macaroonpath` flags explicitly, then you **must not** set the
|
||||
`--network` flag. Otherwise, you will get an error like
|
||||
`[lncli] could not load global options: unable to read macaroon path (check the network setting!): open /home/<user>/.lnd/data/chain/bitcoin/testnet/admin.macaroon: no such file or directory`.
|
||||
|
||||
### Example `lncli` command
|
||||
|
||||
The `lncli` commands in the "remote" mode are the same as if `lnd` was
|
||||
running standalone on a remote host. We need to specify all flags explicitly.
|
||||
The `lncli` commands in the "remote" mode are the same as if `lnd` was running standalone
|
||||
on a remote host. We need to specify all flags explicitly.
|
||||
|
||||
```shell script
|
||||
$ lncli --rpcserver=some-other-host:10009 \
|
||||
|
|
@ -175,10 +215,10 @@ $ lncli --rpcserver=some-other-host:10009 \
|
|||
|
||||
### Example `loop` command
|
||||
|
||||
This is where things get a bit tricky. Because as mentioned above, `loopd` also
|
||||
runs on the same port as the UI server. That's why we have to both specify the
|
||||
`host:port` as well as the TLS certificate of LiT. But `loopd` verifies its
|
||||
own macaroon, so we have to specify that one from the `.loop` directory.
|
||||
This is where things get a bit tricky. Because as mentioned above, `loopd` also runs on
|
||||
the same port as the UI server. That's why we have to both specify the `host:port` as well
|
||||
as the TLS certificate of LiT. But `loopd` verifies its own macaroon, so we have to
|
||||
specify that one from the `.loop` directory.
|
||||
|
||||
```shell script
|
||||
$ loop --rpcserver=localhost:443 --tlscertpath=~/.lit/tls.cert \
|
||||
|
|
@ -186,8 +226,8 @@ $ loop --rpcserver=localhost:443 --tlscertpath=~/.lit/tls.cert \
|
|||
quote out 500000
|
||||
```
|
||||
|
||||
You can easily create an alias for this by adding the following line to your
|
||||
`~/.bashrc` file:
|
||||
You can easily create an alias for this by adding the following line to your `~/.bashrc`
|
||||
file:
|
||||
|
||||
```shell script
|
||||
alias lit-loop="loop --rpcserver=localhost:443 --tlscertpath=~/.lit/tls.cert --macaroonpath=~/.loop/testnet/loop.macaroon"
|
||||
|
|
@ -195,8 +235,8 @@ alias lit-loop="loop --rpcserver=localhost:443 --tlscertpath=~/.lit/tls.cert --m
|
|||
|
||||
### Example `frcli` command
|
||||
|
||||
Faraday's command line tool follows the same pattern as loop. We also have to
|
||||
specify the server and TLS flags for `lnd` but use `faraday`'s macaroon:
|
||||
Faraday's command line tool follows the same pattern as loop. We also have to specify the
|
||||
server and TLS flags for `lnd` but use `faraday`'s macaroon:
|
||||
|
||||
```shell script
|
||||
$ frcli --rpcserver=localhost:443 --tlscertpath=~/.lit/tls.cert \
|
||||
|
|
@ -204,8 +244,8 @@ $ frcli --rpcserver=localhost:443 --tlscertpath=~/.lit/tls.cert \
|
|||
audit
|
||||
```
|
||||
|
||||
You can easily create an alias for this by adding the following line to your
|
||||
`~/.bashrc` file:
|
||||
You can easily create an alias for this by adding the following line to your `~/.bashrc`
|
||||
file:
|
||||
|
||||
```shell script
|
||||
alias lit-frcli="frcli --rpcserver=localhost:443 --tlscertpath=~/.lit/tls.cert --macaroonpath=~/.faraday/testnet/faraday.macaroon"
|
||||
|
|
|
|||
37
doc/remote.md
Normal file
37
doc/remote.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
## Run Lightning Terminal with a remote LND instance
|
||||
To connect Lightning Terminal to a remote LND instance first make sure your `lnd.conf` file contains the following additional configuration settings:
|
||||
```
|
||||
tlsextraip=<externally-reachable-ip-address>
|
||||
rpclisten=0.0.0.0:10009
|
||||
```
|
||||
|
||||
Copy the following files that are located in your `~/.lnd/data/chain/bitcoin/mainnet` directory on your remote machine to `/some/folder/with/lnd/data/` on your local machine (where you’ll be running LiT):
|
||||
- tls.cert
|
||||
- admin.macaroon
|
||||
- chainnotifier.macaroon
|
||||
- invoices.macaroon
|
||||
- readonly.macaroon
|
||||
- router.macaroon
|
||||
- signer.macaroon
|
||||
- walletkit.macaroon
|
||||
|
||||
Create a `lit.conf` file. The default location LiT will look for the configuration file depends on your operating system:
|
||||
- MacOS: `~/Library/Application Support/Lit/lit.conf`
|
||||
- Linux: `~/.lit/lit.conf`
|
||||
- Windows: `~/AppData/Roaming/Lit/lit.conf`
|
||||
|
||||
Alternatively you can specify a different location by passing `--lit-dir=~/.lit`. After creating `lit.conf` populate it with the following configuration settings:
|
||||
```
|
||||
remote.lnd.rpcserver=<externally-reachable-ip-address>:10009
|
||||
remote.lnd.macaroonpath=/some/folder/with/lnd/data/admin.macaroon
|
||||
remote.lnd.tlscertpath=/some/folder/with/lnd/data/tls.cert
|
||||
```
|
||||
|
||||
Run LiT:
|
||||
```
|
||||
./litd --uipassword=UP48lm4VjqxmOxB9X9stry6VTKBRQI
|
||||
```
|
||||
|
||||
Visit https://localhost:8443 to access LiT.
|
||||
|
||||
For further information on configuring LiT in remote mode see [these instructions](config-lnd-remote.md).
|
||||
39
doc/troubleshooting.md
Normal file
39
doc/troubleshooting.md
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
## Troubleshooting
|
||||
|
||||
If you have trouble running your node, please first check the logs for warnings or errors.
|
||||
If there are errors relating to one of the embedded servers, then you should open an issue
|
||||
in their respective GitHub repos ([lnd](https://github.com/lightningnetwork/lnd/issues),
|
||||
[loop](https://github.com/lightninglabs/loop/issues),
|
||||
[faraday](https://github.com/lightninglabs/faraday/issues). If the issue is related to the
|
||||
web app, then you should open an
|
||||
[issue](https://github.com/lightninglabs/lightning-terminal/issues) here in this repo.
|
||||
|
||||
### Server
|
||||
|
||||
Server-side logs are stored in the directory specified by `lnd.lnddir` in your
|
||||
configuration. Inside, there is a `logs` dir containing the log files in subdirectories.
|
||||
Be sure to set `lnd.debuglevel=debug` in your configuration to see the most verbose
|
||||
logging information.
|
||||
|
||||
### Browser
|
||||
|
||||
Client-side logs are disabled by default in production builds. Logging can be turned on by
|
||||
adding a couple keys to your browser's `localStorage`. Simply run these two JS statements
|
||||
in you browser's DevTools console then refresh the page:
|
||||
|
||||
```
|
||||
localStorage.setItem('debug', '*'); localStorage.setItem('debug-level', 'debug');
|
||||
```
|
||||
|
||||
The value for `debug` is a namespace filter which determines which portions of the app to
|
||||
display logs for. The namespaces currently used by the app are as follows:
|
||||
|
||||
- `main`: logs general application messages
|
||||
- `action`: logs all actions that modify the internal application state
|
||||
- `grpc`: logs all GRPC API requests and responses
|
||||
|
||||
Example filters: `main,action` will only log main and action messages. `*,-action` will
|
||||
log everything except action messages.
|
||||
|
||||
The value for `debug-level` determines the verbosity of the logs. The value can be one of
|
||||
`debug`, `info`, `warn`, or `error`.
|
||||
Loading…
Add table
Add a link
Reference in a new issue