|
2 | 2 |
|
3 | 3 |  |
4 | 4 |
|
5 | | - |
6 | | - |
7 | | -Lightning Terminal (LiT) is a browser-based interface for managing the off-chain liquidity |
8 | | -of your `lnd` Lightning Network node. It presents a visual representation of your channels |
9 | | -and balances, while allowing you to perform submarine swaps via the |
10 | | -[Lightning Loop](https://lightning.engineering/loop) service using a graphical interface. |
11 | | -With a bird's eye view of all of your open channels, you can instantly see which ones need |
12 | | -your immediate attention. |
13 | | - |
14 | | -You can configure the UI to classify channels according to your node's operating mode. |
15 | | - |
16 | | -- **Optimize for Receiving**: For merchants who primarily receive inbound Lightning |
17 | | - payments, the channels with high local balances will be shaded red. |
18 | | -- **Optimize for Routing**: For routing node operators, that want to keep their channels |
19 | | - balanced close to 50%, the channels with a high balance in either direction will be |
20 | | - flagged. |
21 | | -- **Optimize for Sending**: For exchanges, fiat gateways, and other operators who |
22 | | - primarily send outgoing Lightning payments, the channels with low local balances will |
23 | | - be shaded red. |
24 | | - |
25 | | -## Architecture |
26 | | - |
27 | | -LiT is packaged as a single binary which contains the |
28 | | -[`lnd`](https://github.com/lightningnetwork/lnd), |
29 | | -[`loopd`](https://github.com/lightninglabs/loop) and |
30 | | -[`faraday`](https://github.com/lightninglabs/faraday) daemons all in one. It also contains |
31 | | -an HTTP server to serve the web assets (html/js/css) and a GRPC proxy to forward web |
32 | | -requests from the browser to the appropriate GRPC server. This deployment strategy was |
33 | | -chosen as it greatly simplifies the operational overhead of installation, configuration |
34 | | -and maintenance that would be necessary to run each of these servers independently. You |
35 | | -only need to download one executable and run one command to get LiT up and running. We |
36 | | -include the CLI binaries `lncli`, `loop` and `frcli` for convenience in the downloadable |
37 | | -archives as well. |
38 | | - |
39 | | -### Daemon Versions packaged with LiT |
40 | | - |
41 | | -| LiT | LND | Loop | Faraday | |
42 | | -| ---------------- | ------------ | ----------- | ------------ | |
43 | | -| **v0.2.0-alpha** | v0.11.1-beta | v0.9.0-beta | v0.2.1-alpha | |
44 | | -| **v0.1.1-alpha** | v0.11.0-beta | v0.8.1-beta | v0.2.0-alpha | |
45 | | -| **v0.1.0-alpha** | v0.10.3-beta | v0.6.5-beta | v0.2.0-alpha | |
| 5 | +Lightning Terminal (LiT) is a browser-based interface for managing channel liquidity. |
46 | 6 |
|
47 | | -## Usage |
| 7 | + |
48 | 8 |
|
49 | | -Read the [Walkthrough](doc/WALKTHROUGH.md) document to learn more about how to use |
50 | | -Lightning Terminal. |
| 9 | +## Features |
| 10 | +- Visualize your channels and balances |
| 11 | +- Perform submarine swaps via the [Lightning Loop](https://lightning.engineering/loop) service |
| 12 | +- Classify channels according to your node's operating mode |
| 13 | +- Run a single binary that integrates both [`loopd`](https://github.com/lightninglabs/loop) and [`faraday`](https://github.com/lightninglabs/faraday) daemons all in one |
51 | 14 |
|
52 | 15 | ## Installation |
| 16 | +Download the latest binaries from the [releases](https://github.com/lightninglabs/lightning-terminal/releases) page. |
53 | 17 |
|
54 | | -There are two options for installing LiT: download the published binaries for your |
55 | | -platform, or compile from source code. |
56 | | - |
57 | | -#### Download Binaries |
58 | | - |
59 | | -LiT binaries for many platforms are made available on the GitHub |
60 | | -[Releases](https://github.com/lightninglabs/lightning-terminal/releases) page in this |
61 | | -repo. There you can download the latest version and extract the archive into a directory |
62 | | -on your computer. |
63 | | - |
64 | | -#### Compile from Source Code |
65 | | - |
66 | | -To compile from source code, you'll need to have some prerequisite developer tooling |
67 | | -installed on your machine. |
68 | | - |
69 | | -| Dependency | Description | |
70 | | -| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | |
71 | | -| [golang](https://golang.org/doc/install) | LiT's backend web server is written in Go. The minimum version supported is Go v1.13. | |
72 | | -| [protoc](https://grpc.io/docs/protoc-installation/) | Required to compile LND & Loop gRPC proto files at build time | |
73 | | -| [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. | |
74 | | -| [yarn](https://classic.yarnpkg.com/en/docs/install) | a popular package manager for NodeJS application dependencies | |
| 18 | +## Execution |
| 19 | +Run Lightning Terminal with a local `lnd` instance: |
75 | 20 |
|
76 | | -Once you have the necessary prerequisites, LiT can be compiled by running the following |
77 | | -commands: |
78 | | - |
79 | | -```shell script |
80 | | -$ git clone https://github.com/lightninglabs/lightning-terminal.git |
81 | | -$ cd lightning-terminal |
82 | | -$ make install |
| 21 | +``` |
| 22 | +./litd --uipassword=UP48lm4Vjqxy<change_this_or_you_will_get_robbed> |
83 | 23 | ``` |
84 | 24 |
|
85 | | -This will produce the `litd` executable and add it to your `GOPATH`. The CLI binaries for |
86 | | -`lncli`, `loop`, and `frcli` are not created by `make install`. You will need to download |
87 | | -those binaries from the [lnd](https://github.com/lightningnetwork/lnd/releases), |
88 | | -[loop](https://github.com/lightninglabs/loop/releases), and |
89 | | -[faraday](https://github.com/lightninglabs/faraday/releases) repos manually. |
| 25 | +Visit https://localhost:8443 to access Terminal. |
90 | 26 |
|
91 | | -#### Executing CLI Commands |
| 27 | +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. |
92 | 28 |
|
93 | | -When executing `loop` and `frcli` commands, you will need to specify the connection info |
94 | | -since the daemons are now integrated into `lnd`'s GRPC server. |
| 29 | +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). |
95 | 30 |
|
96 | | -Examples: |
| 31 | +## LND |
| 32 | +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: |
97 | 33 |
|
98 | | -```shell script |
99 | | -$ loop --rpcserver=localhost:10009 --tlscertpath=$HOME/.lnd/tls.cert --macaroonpath=$HOME/.lnd/data/chain/bitcoin/mainnet/admin.macaroon |
100 | 34 | ``` |
101 | | - |
102 | | -```shell script |
103 | | -$ frcli --rpcserver=localhost:10009 --tlscertpath=$HOME/.lnd/tls.cert --macaroonpath=$HOME/.lnd/data/chain/bitcoin/mainnet/admin.macaroon |
| 35 | +make install tags="signrpc walletrpc chainrpc invoicesrpc" |
104 | 36 | ``` |
105 | 37 |
|
106 | | -## Configuration |
107 | | - |
108 | | -LiT only has a few configuration parameters itself. |
109 | | - |
110 | | -#### Required |
111 | | - |
112 | | -You must set `httpslisten` to the host & port that the https server should listen on. Also |
113 | | -set `uipassword` to a strong password to use to login to the website in your browser. A |
114 | | -minimum of 8 characters is required. In a production environment, it's recommended that |
115 | | -you store this password as an environment variable. |
116 | | - |
117 | | -#### Optional |
118 | | - |
119 | | -You can also configure the HTTP server to automatically install a free SSL certificate |
120 | | -provided by [Let's Encrypt](https://letsencrypt.org/). This is recommended if you plan to |
121 | | -access the website from a remote computer and do not want to deal with the browser warning |
122 | | -you about the self-signed certificate. View the |
123 | | -[Let's Encrypt Configuration](./doc/letsencrypt.md) doc for instructions on how to |
124 | | -configure this. |
125 | | - |
126 | | -```text |
127 | | -Application Options: |
128 | | - --httpslisten= host:port to listen for incoming HTTP/2 connections on (default: 127.0.0.1:8443) |
129 | | - --uipassword= the password that must be entered when using the loop UI. use a strong |
130 | | - password to protect your node from unauthorized access through the web UI |
131 | | - --letsencrypt use Let's Encrypt to create a TLS certificate for the UI instead of using |
132 | | - lnd's TLS certificate. port 80 must be free to listen on and must be reachable |
133 | | - from the internet for this to work |
134 | | - --letsencrypthost= the host name to create a Let's Encrypt certificate for' |
135 | | - --letsencryptdir= the directory where the Let's Encrypt library will store its key and |
136 | | - certificate (default: /Users/<username>/Library/Application Support/Lnd/letsencrypt) |
137 | | -``` |
138 | | - |
139 | | -### Lnd mode |
140 | | - |
141 | | -Starting with LiT `v0.2.0-alpha`, you now have the choice of either running an |
142 | | -`lnd` node in the same process as the UI (which is called the "integrated" `lnd` |
143 | | -mode) or connect the UI to an already running `lnd` node (called "remote" mode). |
144 | | - |
145 | | -Because that single decision has an impact on the configuration options that |
146 | | -need to be used, the documentation has been split into two parts, each |
147 | | -explaining one mode in detail. |
| 38 | +## Interaction |
| 39 | +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 |
| 40 | +[Let's Encrypt Configuration](./doc/letsencrypt.md) doc for instructions on how to configure this. |
148 | 41 |
|
149 | | -* Lnd mode **"remote"** |
150 | | - + Connect to a remote `lnd` instance, start the rest (the UI, `loop`, |
151 | | - `faraday`) in the same process. |
152 | | - + [Please read the `lnd` **remote** mode configuration guide here.](doc/config-lnd-remote.md) |
153 | | - + This is the default mode that is used if the `--lnd-mode=` command line |
154 | | - or `lnd-mode=` configuration option is not set explicitly. |
| 42 | +## Upgrading |
| 43 | +If you used command line arguments with previous versions then you don't need to change anything when upgrading. |
155 | 44 |
|
156 | | -* Lnd mode **"integrated"** |
157 | | - + Start everything (the UI, `lnd`, `loop`, `faraday`) in one single process. |
158 | | - + [Please read the `lnd` **integrated** mode configuration guide here.](doc/config-lnd-integrated.md) |
| 45 | +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: |
| 46 | +- MacOS: `~/Library/Application Support/Lit/lit.conf` |
| 47 | +- Linux: `~/.lit/lit.conf` |
| 48 | +- Windows: `~/AppData/Roaming/Lit/lit.conf` |
159 | 49 |
|
160 | | -### Troubleshooting |
| 50 | +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`). |
161 | 51 |
|
162 | | -If you have trouble running your node, please first check the logs for warnings or errors. |
163 | | -If there are errors relating to one of the embedded servers, then you should open an issue |
164 | | -in their respective GitHub repos ([lnd](https://github.com/lightningnetwork/lnd/issues), |
165 | | -[loop](https://github.com/lightninglabs/loop/issues), |
166 | | -[faraday](https://github.com/lightninglabs/faraday/issues). If the issue is related to the |
167 | | -web app, then you should open an |
168 | | -[issue](https://github.com/lightninglabs/lightning-terminal/issues) here in this repo. |
169 | | - |
170 | | -#### Server |
| 52 | +## Usage |
| 53 | +Read the [walkthrough](doc/WALKTHROUGH.md) document to learn more about how to use LiT. |
171 | 54 |
|
172 | | -Server-side logs are stored in the directory specified by `lnd.lnddir` in your |
173 | | -configuration. Inside, there is a `logs` dir containing the log files in subdirectories. |
174 | | -Be sure to set `lnd.debuglevel=debug` in your configuration to see the most verbose |
175 | | -logging information. |
| 55 | +## Troubleshooting |
| 56 | +If you encounter any issues please see our [troubleshooting guide](./doc/troubleshooting.md). |
176 | 57 |
|
177 | | -#### Browser |
| 58 | +## Build from source |
| 59 | +If you’d prefer to compile from source code please follow [these instructions](./doc/compile.md). |
178 | 60 |
|
179 | | -Client-side logs are disabled by default in production builds. Logging can be turned on by |
180 | | -adding a couple keys to your browser's `localStorage`. Simply run these two JS statements |
181 | | -in you browser's DevTools console then refresh the page: |
| 61 | +## Compatibility |
182 | 62 |
|
183 | | -```js |
184 | | -localStorage.setItem('debug', '*'); localStorage.setItem('debug-level', 'debug'); |
185 | | -``` |
| 63 | +Lightning Terminal is backwards compatible with `lnd` back to version v0.11.0-beta |
186 | 64 |
|
187 | | -The value for `debug` is a namespace filter which determines which portions of the app to |
188 | | -display logs for. The namespaces currently used by the app are as follows: |
| 65 | +| LiT | LND | |
| 66 | +| ---------------- | ------------ | |
| 67 | +| **v0.2.0-alpha** | v0.11.0-beta | |
189 | 68 |
|
190 | | -- `main`: logs general application messages |
191 | | -- `action`: logs all actions that modify the internal application state |
192 | | -- `grpc`: logs all GRPC API requests and responses |
| 69 | +## Daemon Versions packaged with LiT |
193 | 70 |
|
194 | | -Example filters: `main,action` will only log main and action messages. `*,-action` will |
195 | | -log everything except action messages. |
| 71 | +| LiT | LND | Loop | Faraday | |
| 72 | +| ---------------- | ------------ | ----------- | ------------ | |
| 73 | +| **v0.2.0-alpha** | v0.11.1-beta | v0.9.0-beta | v0.2.0-alpha | |
| 74 | +| **v0.1.1-alpha** | v0.11.0-beta | v0.8.1-beta | v0.2.0-alpha | |
| 75 | +| **v0.1.0-alpha** | v0.10.3-beta | v0.6.5-beta | v0.2.0-alpha | |
196 | 76 |
|
197 | | -The value for `debug-level` determines the verbosity of the logs. The value can be one of |
198 | | -`debug`, `info`, `warn`, or `error`. |
0 commit comments