GlcoinCore/lightning-terminal
1
0
Fork 0
mirror of https://github.com/lightninglabs/lightning-terminal.git synced 2026-08-13 12:33:36 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: reformat readme markdown

Browse source
This commit is contained in:
jamaljsr 2020-06-13 00:39:59 -04:00
parent e007ea0242
commit cb2c084cc2
2 changed files with 134 additions and 41 deletions
Download patch file Download diff file Expand all files Collapse all files

3
app/.prettierrc → .prettierrc
View file

@ -8,6 +8,7 @@
} }
], ],
"printWidth": 90, "printWidth": 90,
"proseWrap": "always",
"singleQuote": true, "singleQuote": true,
"useTabs": false, "useTabs": false,
"semi": true, "semi": true,
@ -16,4 +17,4 @@
"bracketSpacing": true, "bracketSpacing": true,
"jsxBracketSameLine": false, "jsxBracketSameLine": false,
"arrowParens": "avoid" "arrowParens": "avoid"
} }

172
README.md
View file

@ -4,35 +4,69 @@
![screenshot](./app/src/assets/images/screenshot.png) ![screenshot](./app/src/assets/images/screenshot.png)
Shushtar 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. Shushtar 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.
You can configure the UI to classify channels according to your node's operating mode. You can configure the UI to classify channels according to your node's operating mode.
- **Optimize for Receiving**: For merchants who primarily receive inbound Lightning payments, the channels with high local balances will be shaded red. - **Optimize for Receiving**: For merchants who primarily receive inbound Lightning
- **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. payments, the channels with high local balances will be shaded red.
- **Optimize for Sending**: For exchanges, fiat gateways, and other operators who primarily send outgoing 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 high local balances will
be shaded red.
## Architecture ## Architecture
Shushtar 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 Shushtar up and running. We include the CLI binaries `lncli`, `loop` and `frcli` for convenience in the downloadable archives as well. Shushtar 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 Shushtar up and running.
We include the CLI binaries `lncli`, `loop` and `frcli` for convenience in the
downloadable archives as well.
## Installation ## Installation
There are two options for installing Shushtar: download the published binaries for your platform, or compile from source code. There are two options for installing Shushtar: download the published binaries for your
platform, or compile from source code.
#### Download Binaries #### Download Binaries
Shushtar binaries for many platforms are made available on the GitHub [Releases](https://github.com/lightninglabs/shushtar/releases) page in this repo. There you can download the latest version and extract the archive into a directory on your computer. Shushtar binaries for many platforms are made available on the GitHub
[Releases](https://github.com/lightninglabs/shushtar/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 #### Compile from Source Code
To compile from source code, you'll need to have some prerequisite developer tooling installed on your machine. To compile from source code, you'll need to have some prerequisite developer tooling
installed on your machine.
- **Go**: Shushtar's backend web server is written in Go. Instructions for installing Go for your operating system can be found on the [golang install](https://golang.org/doc/install) page. The minimum version supported is Go v1.13. - **Go**: Shushtar's backend web server is written in Go. Instructions for installing Go
- **NodeJS**: Shushtar'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. It can be downloaded and installed by following the instructions on the [NodeJS download](https://nodejs.org/en/download/) page. for your operating system can be found on the
- **Yarn**: a popular package manager for NodeJS application dependencies. Installation information can be found on the [Yarn Installation](https://classic.yarnpkg.com/en/docs/install) page. [golang install](https://golang.org/doc/install) page. The minimum version supported is
Go v1.13.
- **NodeJS**: Shushtar'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. It can be downloaded and installed by following the
instructions on the [NodeJS download](https://nodejs.org/en/download/) page.
- **Yarn**: a popular package manager for NodeJS application dependencies. Installation
information can be found on the
[Yarn Installation](https://classic.yarnpkg.com/en/docs/install) page.
Once you have the necessary prerequisites, Shushtar can be compiled by running the following commands: Once you have the necessary prerequisites, Shushtar can be compiled by running the
following commands:
``` ```
git clone https://github.com/lightninglabs/shushtar.git git clone https://github.com/lightninglabs/shushtar.git
@ -48,13 +82,26 @@ Shushtar only has a few configuration parameters itself.
#### Required #### 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. 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 #### Optional
You can also configure the HTTP server to automatically install a free SSL certificate provided by [LetsEncrypt](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. You just need to specify the domain name you wish to use, and make sure port 80 is open in your in your firewall. LetsEncrypt requires this to verify that you own the domain name. Shushtar will listen on port 80 to handle the verification requests. On some linux-based platforms, you may need to run Shushtar with superuser privileges since port 80 is a system port. You can also configure the HTTP server to automatically install a free SSL certificate
provided by [LetsEncrypt](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. You just need to specify the domain name you wish
to use, and make sure port 80 is open in your in your firewall. LetsEncrypt requires this
to verify that you own the domain name. Shushtar will listen on port 80 to handle the
verification requests. On some linux-based platforms, you may need to run Shushtar with
superuser privileges since port 80 is a system port.
> Note: Shushtar only serves content over **HTTPS**. If you do not use `letsencrypt`, Shushtar will use the self-signed certificate that is auto-generated by `lnd` to encrypt the browser-to-server communication. Web browsers will display a warning when using the self-signed certificate. > Note: Shushtar only serves content over **HTTPS**. If you do not use `letsencrypt`,
> Shushtar will use the self-signed certificate that is auto-generated by `lnd` to encrypt
> the browser-to-server communication. Web browsers will display a warning when using the
> self-signed certificate.
``` ```
Application Options: Application Options:
@ -69,7 +116,14 @@ Application Options:
certificate (default: /Users/jamal/Library/Application Support/Lnd/letsencrypt) certificate (default: /Users/jamal/Library/Application Support/Lnd/letsencrypt)
``` ```
In addition to the Shushtar specific parameters, you must also provide configuration to the `lnd`, `loop` and `faraday` daemons. For `lnd`, each flag must be prefixed with `lnd.` (ex: `lnd.lnddir=~/.lnd`). Please see the [sample-lnd.conf](https://github.com/lightningnetwork/lnd/blob/master/sample-lnd.conf) file for more details on the available parameters. Note that `loopd` and `faraday` will automatically connect to the in-process `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 Shushtar specific parameters, you must also provide configuration to
the `lnd`, `loop` and `faraday` daemons. For `lnd`, each flag must be prefixed with `lnd.`
(ex: `lnd.lnddir=~/.lnd`). Please see the
[sample-lnd.conf](https://github.com/lightningnetwork/lnd/blob/master/sample-lnd.conf)
file for more details on the available parameters. Note that `loopd` and `faraday` will
automatically connect to the in-process `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.
Here is an example command to start `shushtar` on testnet with a local `bitcoind` node: Here is an example command to start `shushtar` on testnet with a local `bitcoind` node:
@ -97,14 +151,13 @@ $ ./shushtar \
--faraday.min_monitored=48h --faraday.min_monitored=48h
``` ```
You can also store the configuration in a persistent `lnd.conf` file so you do You can also store the configuration in a persistent `lnd.conf` file so you do not need to
not need to type in the command line arguments every time you start the server. type in the command line arguments every time you start the server. Just remember to use
Just remember to use the appropriate prefixes as necessary. the appropriate prefixes as necessary.
Also make sure to include the `lnd` general options in the `[Application Options]` Also make sure to include the `lnd` general options in the `[Application Options]` section
section because the section name `[Lnd]` is not unique anymore because of how we because the section name `[Lnd]` is not unique anymore because of how we combine the
combine the configurations of all daemons. This will hopefully be fixed in a configurations of all daemons. This will hopefully be fixed in a future release.
future release.
Example `lnd.conf`: Example `lnd.conf`:
@ -149,36 +202,48 @@ The default location for the `lnd.conf` file will depend on your operating syste
### Upgrade Existing Nodes ### Upgrade Existing Nodes
If you already have existing `lnd`, `loop`, or `faraday` nodes, you can easily upgrade them to the Shushtar single executable while keeping all of your past data. If you already have existing `lnd`, `loop`, or `faraday` nodes, you can easily upgrade
them to the Shushtar single executable while keeping all of your past data.
For `lnd`: For `lnd`:
- if you use an `lnd.conf` file for configurations, add the `lnd.` prefix to each of the configuration parameters. - if you use an `lnd.conf` file for configurations, add the `lnd.` prefix to each of the
configuration parameters.
Before: Before:
``` ```
[Application Options] [Application Options]
alias=merchant alias=merchant
``` ```
After: After:
``` ```
[Application Options] [Application Options]
lnd.alias=merchant lnd.alias=merchant
``` ```
- if you use command line arguments for configuration, add the `lnd.` prefix to each argument to `shushtar`
- if you use command line arguments for configuration, add the `lnd.` prefix to each
argument to `shushtar`
Before: Before:
``` ```
$ lnd --lnddir=~/.lnd --alias=merchant ... $ lnd --lnddir=~/.lnd --alias=merchant ...
``` ```
After: After:
``` ```
$ shushtar lnd.lnddir=~/.lnd --lnd.alias=merchant ... $ shushtar lnd.lnddir=~/.lnd --lnd.alias=merchant ...
``` ```
For `loop`: For `loop`:
- if you use an `loop.conf` file for configurations, copy the parameters into the `lnd.conf` file that `shushtar` uses, and add the `loop.` prefix to each of the configuration parameters. - if you use an `loop.conf` file for configurations, copy the parameters into the
`lnd.conf` file that `shushtar` uses, and add the `loop.` prefix to each of the
configuration parameters.
Before: (in `loop.conf`) Before: (in `loop.conf`)
@ -194,64 +259,91 @@ For `loop`:
loop.loopoutmaxparts=5 loop.loopoutmaxparts=5
``` ```
- if you use command line arguments for configuration, add the `loop.` prefix to each argument to `shushtar` - if you use command line arguments for configuration, add the `loop.` prefix to each
argument to `shushtar`
Before: Before:
``` ```
$ loop --loopoutmaxparts=5 --debuglevel=debug ... $ loop --loopoutmaxparts=5 --debuglevel=debug ...
``` ```
After: After:
``` ```
$ shushtar --loop.loopoutmaxparts=5 --loop.debuglevel=debug ... $ shushtar --loop.loopoutmaxparts=5 --loop.debuglevel=debug ...
``` ```
For `faraday`: For `faraday`:
- the standalone `faraday` daemon does not load configuration from a file, but you can now store the parameters into the `lnd.conf` file that `shushtar` uses. Just add the `faraday.` prefix to each of the configuration parameters. - the standalone `faraday` daemon does not load configuration from a file, but you can now
store the parameters into the `lnd.conf` file that `shushtar` uses. Just add the
`faraday.` prefix to each of the configuration parameters.
Before: (from command line) Before: (from command line)
``` ```
$ faraday --min_monitored=48h $ faraday --min_monitored=48h
``` ```
After: (in `lnd.conf`) After: (in `lnd.conf`)
``` ```
[Faraday] [Faraday]
faraday.min_monitored=48h faraday.min_monitored=48h
``` ```
- if you use command line arguments for configuration, add the `faraday.` prefix to each argument to `shushtar` - if you use command line arguments for configuration, add the `faraday.` prefix to each
argument to `shushtar`
Before: Before:
``` ```
$ faraday --min_monitored=48h --debuglevel=debug ... $ faraday --min_monitored=48h --debuglevel=debug ...
``` ```
After: After:
``` ```
$ shushtar --faraday.min_monitored=48h --faraday.debuglevel=debug... $ shushtar --faraday.min_monitored=48h --faraday.debuglevel=debug...
``` ```
### Troubleshooting ### 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/shushtar/issues) here in this repo. 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/shushtar/issues)
here in this repo.
#### Server #### 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. 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 #### 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: 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'); 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: 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 - `main`: logs general application messages
- `action`: logs all actions that modify the internal application state - `action`: logs all actions that modify the internal application state
- `grpc`: logs all GRPC API requests and responses - `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. 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`. The value for `debug-level` determines the verbosity of the logs. The value can be one of
`debug`, `info`, `warn`, or `error`.