mirror of
https://github.com/ACINQ/eclair.git
synced 2025-03-13 11:35:47 +01:00
Documentation update (#1092)
* Fix README style warnings * Add documentation links to the wiki * Update build instructions.
This commit is contained in:
Bastien Teinturier
GitHub
parent
648415771e
commit
b9698f2230
2 changed files with 86 additions and 47 deletions
56
BUILD.md
56
BUILD.md
|
|
@ -1,39 +1,57 @@
|
|||
# Building Eclair
|
||||
|
||||
## Requirements
|
||||
- [OpenJDK 11](https://jdk.java.net/11/).
|
||||
|
||||
- [OpenJDK 11](https://adoptopenjdk.net/?variant=openjdk11&jvmVariant=hotspot).
|
||||
- [Maven](https://maven.apache.org/download.cgi) 3.6.0 or newer
|
||||
- [Docker](https://www.docker.com/) 18.03 or newer (optional) if you want to run all tests
|
||||
|
||||
:warning: You can also use [Oracle JDK 1.8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) to build and run eclair, but we recommend you use Open JDK11.
|
||||
:warning: You can also use [Oracle JDK 1.8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) to build and run eclair, but we recommend you use OpenJDK 11.
|
||||
|
||||
## Build
|
||||
To build the project, simply run:
|
||||
|
||||
To build the project and run the tests, simply run:
|
||||
|
||||
```shell
|
||||
$ mvn install
|
||||
mvn install
|
||||
```
|
||||
|
||||
#### Other build options
|
||||
### Other build options
|
||||
|
||||
To skip all tests, run:
|
||||
|
||||
```shell
|
||||
$ mvn install -DskipTests
|
||||
```
|
||||
To only build the `eclair-node` module
|
||||
```shell
|
||||
$ mvn install -pl eclair-node -am -DskipTests
|
||||
mvn install -DskipTests
|
||||
```
|
||||
|
||||
# Building the API documentation
|
||||
To only build the `eclair-node` module, run:
|
||||
|
||||
## Slate
|
||||
```shell
|
||||
mvn install -pl eclair-node -am -DskipTests
|
||||
```
|
||||
|
||||
To run the tests, run:
|
||||
|
||||
```shell
|
||||
mvn test
|
||||
```
|
||||
|
||||
To run tests for a specific class, run:
|
||||
|
||||
```shell
|
||||
mvn test -Dsuites=*<TestClassName>
|
||||
```
|
||||
|
||||
## Build the API documentation
|
||||
|
||||
### Slate
|
||||
|
||||
The API doc is generated via slate and hosted on github pages. To make a change and update the doc follow the steps:
|
||||
|
||||
1. git checkout slate-doc
|
||||
2. Install your local dependencies for slate, more info [here](https://github.com/lord/slate#getting-started-with-slate)
|
||||
3. Edit `source/index.html.md` and save your changes.
|
||||
4. Commit all the changes to git, before deploying the repo should be clean.
|
||||
5. Push your commit to remote.
|
||||
6. Run `./deploy.sh`
|
||||
7. Wait a few minutes and the doc should be updated at https://acinq.github.io/eclair
|
||||
1. `git checkout slate-doc`
|
||||
2. Install your local dependencies for slate, more info [here](https://github.com/lord/slate#getting-started-with-slate)
|
||||
3. Edit `source/index.html.md` and save your changes.
|
||||
4. Commit all the changes to git, before deploying the repo should be clean.
|
||||
5. Push your commit to remote.
|
||||
6. Run `./deploy.sh`
|
||||
7. Wait a few minutes and the doc should be updated at [https://acinq.github.io/eclair](https://acinq.github.io/eclair)
|
||||
|
|
|
|||
77
README.md
77
README.md
|
|
@ -8,18 +8,20 @@
|
|||
**Eclair** (French for Lightning) is a Scala implementation of the Lightning Network. It can run with or without a GUI, and a JSON API is also available.
|
||||
|
||||
This software follows the [Lightning Network Specifications (BOLTs)](https://github.com/lightningnetwork/lightning-rfc). Other implementations include [c-lightning](https://github.com/ElementsProject/lightning) and [lnd](https://github.com/LightningNetwork/lnd).
|
||||
|
||||
---
|
||||
|
||||
:construction: Both the BOLTs and Eclair itself are still a work in progress. Expect things to break/change!
|
||||
|
||||
:rotating_light: If you run Eclair on mainnet (which is the default setting):
|
||||
- Keep in mind that it is beta-quality software and **don't put too much money** in it
|
||||
- Eclair's JSON API should **NOT** be accessible from the outside world (similarly to Bitcoin Core API)
|
||||
|
||||
|
||||
---
|
||||
|
||||
:construction: Both the BOLTs and Eclair itself are still a work in progress. Expect things to break/change!
|
||||
|
||||
:rotating_light: If you run Eclair on mainnet (which is the default setting):
|
||||
|
||||
* Keep in mind that it is beta-quality software and **don't put too much money** in it
|
||||
* Eclair's JSON API should **NOT** be accessible from the outside world (similarly to Bitcoin Core API)
|
||||
|
||||
---
|
||||
|
||||
## Lightning Network Specification Compliance
|
||||
|
||||
Please see the latest [release note](https://github.com/ACINQ/eclair/releases) for detailed information on BOLT compliance.
|
||||
|
||||
## Overview
|
||||
|
|
@ -32,18 +34,26 @@ Eclair offers a feature rich HTTP API that enables application developers to eas
|
|||
|
||||
For more information please visit the [API documentation website](https://acinq.github.io/eclair).
|
||||
|
||||
## Documentation
|
||||
|
||||
Please visit our [wiki](https://github.com/acinq/eclair/wiki) to find detailed instructions on how to configure your
|
||||
node, connect to other nodes, open channels, send and receive payments and more advanced scenario.
|
||||
|
||||
You will find detailed guides and frequently asked questions there.
|
||||
|
||||
## Installation
|
||||
|
||||
### Configuring Bitcoin Core
|
||||
|
||||
:warning: Eclair requires Bitcoin Core 0.17.1 or higher. If you are upgrading an existing wallet, you need to create a new address and send all your funds to that address.
|
||||
|
||||
Eclair needs a _synchronized_, _segwit-ready_, **_zeromq-enabled_**, _wallet-enabled_, _non-pruning_, _tx-indexing_ [Bitcoin Core](https://github.com/bitcoin/bitcoin) node.
|
||||
Eclair needs a _synchronized_, _segwit-ready_, **_zeromq-enabled_**, _wallet-enabled_, _non-pruning_, _tx-indexing_ [Bitcoin Core](https://github.com/bitcoin/bitcoin) node.
|
||||
Eclair will use any BTC it finds in the Bitcoin Core wallet to fund any channels you choose to open. Eclair will return BTC from closed channels to this wallet.
|
||||
You can configure your Bitcoin Node to use either `p2sh-segwit` addresses or `bech32` addresses, Eclair is compatible with both modes.
|
||||
|
||||
Run bitcoind with the following minimal `bitcoin.conf`:
|
||||
```
|
||||
|
||||
```conf
|
||||
server=1
|
||||
rpcuser=foo
|
||||
rpcpassword=bar
|
||||
|
|
@ -55,17 +65,22 @@ zmqpubrawtx=tcp://127.0.0.1:29000
|
|||
### Installing Eclair
|
||||
|
||||
Eclair is developed in [Scala](https://www.scala-lang.org/), a powerful functional language that runs on the JVM, and is packaged as a JAR (Java Archive) file. We provide 2 different packages, which internally use the same core libraries:
|
||||
|
||||
* eclair-node, which is a headless application that you can run on servers and desktops, and control from the command line
|
||||
* eclair-node-gui, which also includes a JavaFX GUI
|
||||
|
||||
To run Eclair, you first need to install Java, we recommend that you use [OpenJDK 11](https://adoptopenjdk.net/?variant=openjdk11&jvmVariant=hotspot). Eclair will also run on Oracle JDK 1.8, Oracle JDK 11, and other versions of OpenJDK but we don't recommend using them.
|
||||
|
||||
Then download our latest [release](https://github.com/ACINQ/eclair/releases) and depending on whether or not you want a GUI run the following command:
|
||||
|
||||
* with GUI:
|
||||
|
||||
```shell
|
||||
java -jar eclair-node-gui-<version>-<commit_id>.jar
|
||||
```
|
||||
|
||||
* without GUI:
|
||||
|
||||
```shell
|
||||
java -jar eclair-node-<version>-<commit_id>.jar
|
||||
```
|
||||
|
|
@ -78,7 +93,7 @@ Eclair reads its configuration file, and write its logs, to `~/.eclair` by defau
|
|||
|
||||
To change your node's configuration, create a file named `eclair.conf` in `~/.eclair`. Here's an example configuration file:
|
||||
|
||||
```
|
||||
```conf
|
||||
eclair.node-alias=eclair
|
||||
eclair.node-color=49daaa
|
||||
```
|
||||
|
|
@ -111,10 +126,11 @@ Some advanced parameters can be changed with java environment variables. Most us
|
|||
name | description | default value
|
||||
----------------------|--------------------------------------------|--------------
|
||||
eclair.datadir | Path to the data directory | ~/.eclair
|
||||
eclair.headless | Run eclair without a GUI |
|
||||
eclair.headless | Run eclair without a GUI |
|
||||
eclair.printToConsole | Log to stdout (in addition to eclair.log) |
|
||||
|
||||
For example, to specify a different data directory you would run the following command:
|
||||
|
||||
```shell
|
||||
java -Declair.datadir=/tmp/node1 -jar eclair-node-gui-<version>-<commit_id>.jar
|
||||
```
|
||||
|
|
@ -130,41 +146,44 @@ java -Dlogback.configurationFile=/path/to/logback-custom.xml -jar eclair-node-gu
|
|||
#### Backup
|
||||
|
||||
The files that you need to backup are located in your data directory. You must backup:
|
||||
- your seed (`seed.dat`)
|
||||
- your channel database (`eclair.sqlite.bak` under directory `mainnet`, `testnet` or `regtest` depending on which chain you're running on)
|
||||
|
||||
* your seed (`seed.dat`)
|
||||
* your channel database (`eclair.sqlite.bak` under directory `mainnet`, `testnet` or `regtest` depending on which chain you're running on)
|
||||
|
||||
Your seed never changes once it has been created, but your channels will change whenever you receive or send payments. Eclair will
|
||||
create and maintain a snapshot of its database, named `eclair.sqlite.bak`, in your data directory, and update it when needed. This file is
|
||||
create and maintain a snapshot of its database, named `eclair.sqlite.bak`, in your data directory, and update it when needed. This file is
|
||||
always consistent and safe to use even when Eclair is running, and this is what you should backup regularly.
|
||||
|
||||
For example you could configure a `cron` task for your backup job. Or you could configure an optional notification script to be called by eclair once a new database snapshot has been created, using the following option:
|
||||
```
|
||||
|
||||
```conf
|
||||
eclair.backup-notify-script = "/absolute/path/to/script.sh"
|
||||
```
|
||||
|
||||
Make sure that your script is executable and uses an absolute path name for `eclair.sqlite.bak`.
|
||||
|
||||
Note that depending on your filesystem, in your backup process we recommend first moving `eclair.sqlite.bak` to some temporary file
|
||||
Note that depending on your filesystem, in your backup process we recommend first moving `eclair.sqlite.bak` to some temporary file
|
||||
before copying that file to your final backup location.
|
||||
|
||||
|
||||
## Docker
|
||||
|
||||
A [Dockerfile](Dockerfile) image is built on each commit on [docker hub](https://hub.docker.com/r/acinq/eclair) for running a dockerized eclair-node.
|
||||
|
||||
You can use the `JAVA_OPTS` environment variable to set arguments to `eclair-node`.
|
||||
|
||||
```
|
||||
```shell
|
||||
docker run -ti --rm -e "JAVA_OPTS=-Xmx512m -Declair.api.binding-ip=0.0.0.0 -Declair.node-alias=node-pm -Declair.printToConsole" acinq/eclair
|
||||
```
|
||||
|
||||
If you want to persist the data directory, you can make the volume to your host with the `-v` argument, as the following example:
|
||||
|
||||
```
|
||||
```shell
|
||||
docker run -ti --rm -v "/path_on_host:/data" -e "JAVA_OPTS=-Declair.printToConsole" acinq/eclair
|
||||
```
|
||||
|
||||
If you enabled the API you can check the status of eclair using the command line tool:
|
||||
```
|
||||
|
||||
```shell
|
||||
docker exec <container_name> eclair-cli -p foobar getinfo
|
||||
```
|
||||
|
||||
|
|
@ -175,6 +194,7 @@ For advanced usage, Eclair supports plugins written in Scala, Java, or any JVM-c
|
|||
A valid plugin is a jar that contains an implementation of the [Plugin](eclair-node/src/main/scala/fr/acinq/eclair/Plugin.scala) interface.
|
||||
|
||||
Here is how to run Eclair with plugins:
|
||||
|
||||
```shell
|
||||
java -jar eclair-node-<version>-<commit_id>.jar <plugin1.jar> <plugin2.jar> <...>
|
||||
```
|
||||
|
|
@ -184,15 +204,15 @@ java -jar eclair-node-<version>-<commit_id>.jar <plugin1.jar> <plugin2.jar> <...
|
|||
Eclair is configured to run on mainnet by default, but you can still run it on testnet (or regtest): start your Bitcoin Node in
|
||||
testnet mode (add `testnet=1` in `bitcoin.conf` or start with `-testnet`), and change Eclair's chain parameter and Bitcoin RPC port:
|
||||
|
||||
```
|
||||
```conf
|
||||
eclair.chain=testnet
|
||||
eclair.bitcoind.rpcport=18332
|
||||
```
|
||||
|
||||
You may also want to take advantage of the new configuration sections in `bitcoin.conf` to manage parameters that are network specific,
|
||||
You may also want to take advantage of the new configuration sections in `bitcoin.conf` to manage parameters that are network specific,
|
||||
so you can easily run your bitcoin node on both mainnet and testnet. For example you could use:
|
||||
|
||||
```
|
||||
```conf
|
||||
server=1
|
||||
txindex=1
|
||||
[main]
|
||||
|
|
@ -208,6 +228,7 @@ zmqpubrawtx=tcp://127.0.0.1:29001
|
|||
```
|
||||
|
||||
## Resources
|
||||
- [1] [The Bitcoin Lightning Network: Scalable Off-Chain Instant Payments](https://lightning.network/lightning-network-paper.pdf) by Joseph Poon and Thaddeus Dryja
|
||||
- [2] [Reaching The Ground With Lightning](https://github.com/ElementsProject/lightning/raw/master/doc/deployable-lightning.pdf) by Rusty Russell
|
||||
- [3] [Lightning Network Explorer](https://explorer.acinq.co) - Explore testnet LN nodes you can connect to
|
||||
|
||||
* [1] [The Bitcoin Lightning Network: Scalable Off-Chain Instant Payments](https://lightning.network/lightning-network-paper.pdf) by Joseph Poon and Thaddeus Dryja
|
||||
* [2] [Reaching The Ground With Lightning](https://github.com/ElementsProject/lightning/raw/master/doc/deployable-lightning.pdf) by Rusty Russell
|
||||
* [3] [Lightning Network Explorer](https://explorer.acinq.co) - Explore testnet LN nodes you can connect to
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue