From 9f8378f4cffc542e146d7a24b602843da119a2e9 Mon Sep 17 00:00:00 2001 From: Max Fang Date: Wed, 2 Aug 2017 18:52:37 -0700 Subject: [PATCH] readme+docs: Consolidate installation docs --- README.md | 48 +-------------- docs/INSTALL.md | 160 ++++++++++++++++++++++++++++++++---------------- 2 files changed, 108 insertions(+), 100 deletions(-) diff --git a/README.md b/README.md index a9752dde..5b02473b 100644 --- a/README.md +++ b/README.md @@ -51,53 +51,9 @@ said, `lnd` the current status of `lnd`'s BOLT compliance is: - [X] BOLT 8: Encrypted and Authenticated Transport ## Installation - In order to build from source, the following build dependencies are - required: + In order to build from source, please see [the installation + instructions](docs/INSTALL.md). - * **Go:** Installation instructions can be found [here](http://golang.org/doc/install). - - It is recommended to add `$GOPATH/bin` to your `PATH` at this point. - **Note:** If you are building with `Go 1.5`, then you'll need to - enable the vendor experiment by setting the `GO15VENDOREXPERIMENT` - environment variable to `1`. If you're using `Go 1.6` or later, then - it is safe to skip this step. - - * **Glide:** This project uses `Glide` to manage dependencies as well - as to provide *reproducible builds*. To install `Glide`, execute the - following command (assumes you already have Go properly installed): - ``` - $ go get -u github.com/Masterminds/glide - ``` - * **btcd:** This project currently requires `btcd` with segwit support, - which is not yet merged into the master branch. Instead, - [roasbeef](https://github.com/roasbeef/btcd) maintains a fork with his - segwit implementation applied. To install, please see - [the installation instructions](docs/INSTALL.md). - -With the preliminary steps completed, to install `lnd`, `lncli`, and all -related dependencies run the following commands: -``` -$ git clone https://github.com/lightningnetwork/lnd $GOPATH/src/github.com/lightningnetwork/lnd -$ cd $GOPATH/src/github.com/lightningnetwork/lnd -$ glide install -$ go install . ./cmd/... -``` - -### Updating -To update your version of `lnd` to the latest version run the following -commands: -``` -$ cd $GOPATH/src/github.com/lightningnetwork/lnd -$ git pull && glide install -$ go install . ./cmd/... -``` - -### Tests -To check that `lnd` was installed properly run the following command: -``` -go install; go test -v -p 1 $(go list ./... | grep -v '/vendor/') -``` - ## IRC * irc.freenode.net * channel #lnd diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 61e3e185..8f970e65 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -1,50 +1,106 @@ -# Installation for lnd and btcd +# Installation -### If Glide isn't installed, install it: +### Preliminaries + In order to work with [`lnd`](https://github.com/lightningnetwork/lnd), the following build dependencies are required: + + * **Go:** `lnd` is written in Go. To install, run one of the following commands: + + ``` + # On Linux: + sudo apt-get install golang-go + # On Mac OS X + brew install go + ``` + More detailed installation instructions can be found + [here](http://golang.org/doc/install). + + At this point, you should set your `$GOPATH` environment variable, which + represents the path to your workspace. By default, `$GOPATH` is set to + `~/go`. Be sure to set your `$GOPATH` every time you open a new terminal + window. + ``` + export GOPATH=~/projects/lightning + ``` + It is recommended to add `$GOPATH/bin` to your `PATH` at this point, like + so: + ```bash + export PATH=$PATH:$GOPATH/bin + ``` + This will ensure that your shell will be able to detect the binaries that + were just installed. + + * **Glide:** This project uses `Glide` to manage dependencies as well + as to provide *reproducible builds*. To install `Glide`, execute the + following command (assumes you already have Go properly installed): + ``` + go get -u github.com/Masterminds/glide + ``` + +### Installing LND + +With the preliminary steps completed, to install `lnd`, `lncli`, and all +related dependencies run the following commands: ``` -$ go get -u github.com/Masterminds/glide +git clone https://github.com/lightningnetwork/lnd $GOPATH/src/github.com/lightningnetwork/lnd +cd $GOPATH/src/github.com/lightningnetwork/lnd +glide install +go install . ./cmd/... ``` -### Install lnd: +**Updating** +To update your version of `lnd` to the latest version run the following +commands: ``` -$ cd $GOPATH -$ git clone https://github.com/lightningnetwork/lnd $GOPATH/src/github.com/lightningnetwork/lnd -$ cd $GOPATH/src/github.com/lightningnetwork/lnd -$ glide install -$ go install . ./cmd/... +cd $GOPATH/src/github.com/lightningnetwork/lnd +git pull && glide install +go install . ./cmd/... ``` -### Install btcutil: (must be from roasbeef fork, not from btcsuite) +**Tests** +To check that `lnd` was installed properly run the following command: ``` -$ go get -u github.com/roasbeef/btcutil +go install; go test -v -p 1 $(go list ./... | grep -v '/vendor/') ``` -### Install btcd: (must be from roasbeef fork, not from btcsuite) +### Installing BTCD +`lnd` currently requires `btcd` with segwit support, which is not yet merged +into the master branch. Instead, [roasbeef](https://github.com/roasbeef/btcd) +maintains a fork with his segwit implementation applied. To install, run the +following commands: + +Install **btcutil**: (must be from roasbeef fork, not from btcsuite) ``` -$ cd $GOPATH/src/github.com/roasbeef/btcd -$ glide install -$ go install . ./cmd/... +go get -u github.com/roasbeef/btcutil ``` -### Start btcd (will create rpc.cert and default btcd.conf): - +Install **btcd**: (must be from roasbeef fork, not from btcsuite) ``` -$ btcd --testnet --txindex --rpcuser=kek --rpcpass=kek +cd $GOPATH/src/github.com/roasbeef/btcd +glide install +go install . ./cmd/... ``` -Before you'll be able to use `lnd` on testnet, `btcd` needs to first fully sync -the blockchain. Depending on your hardware, this may take up to a few hours. +### Starting btcd + +Running the following command will create `rpc.cert` and default `btcd.conf`. + +``` +btcd --testnet --txindex --rpcuser=kek --rpcpass=kek +``` +If you want to use `lnd` on testnet, `btcd` needs to first fully sync the +testnet blockchain. Depending on your hardware, this may take up to a few +hours. (NOTE: It may take several minutes to find segwit-enabled peers.) -While `btcd` is syncing you can check on it's progress using btcd's `getinfo` +While `btcd` is syncing you can check on its progress using btcd's `getinfo` RPC command: ``` -$ btcctl --testnet getinfo +btcctl --testnet --rpcuser=kek --rpcpass=kek getinfo { "version": 120000, "protocolversion": 70002, @@ -64,26 +120,18 @@ time. You can test your `btcd` node's connectivity using the `getpeerinfo` command: ``` -$ btcctl --testnet getpeerinfo | more +btcctl --testnet --rpcuser=kek --rpcpass=kek getpeerinfo | more ``` -### Start lnd: (once btcd has synced testnet) +### LND -``` -$ lnd --bitcoin.active --bitcoin.testnet --debuglevel=debug --externalip=X.X.X.X -``` +#### Simnet vs. Testnet Development -If you'd like to signal to other nodes on the network that you'll accept -incoming channels (as peers need to connect inbound to initiate a channel -funding workflow), then the `--externalip` flag should be set to your publicly -reachable IP address. - -#### Simnet Development - -If doing local development, you'll want to start both `btcd` and `lnd` in the -`simnet` mode. Simnet is similar to regtest in that you'll be able to instantly -mine blocks as needed to test `lnd` locally. In order to start either daemon in -the `simnet` mode add the `--bitcoin.simnet` flag instead of the +If you are doing local development, such as for the tutorial, you'll want to +start both `btcd` and `lnd` in the `simnet` mode. Simnet is similar to regtest +in that you'll be able to instantly mine blocks as needed to test `lnd` +locally. In order to start either daemon in the `simnet` mode use `simnet` +instead of `testnet`, such as adding the `--bitcoin.simnet` flag instead of the `--bitcoin.testnet` flag. Another relevant command line flag for local testing of new `lnd` developments @@ -92,15 +140,25 @@ automatically settle a special type of HTLC sent to it. This means that you won't need to manually insert invoices in order to test payment connectivity. To send this "special" HTLC type, include the `--debugsend` command at the end of your `sendpayment` commands. + +### Running LND + +If you are on testnet, run this command after `btcd` has finished syncing. +Otherwise, replace `--bitcoin.testnet` with `--bitcoin.simnet` ``` -$ lnd --bitcoin.active --bitcoin.simnet --debughtlc +lnd --bitcoin.active --bitcoin.testnet --debuglevel=debug --bitcoin.rpcuser=kek --bitcoin.rpcpass=kek --externalip=X.X.X.X ``` -### Create an lnd.conf (Optional) +If you'd like to signal to other nodes on the network that you'll accept +incoming channels (as peers need to connect inbound to initiate a channel +funding workflow), then the `--externalip` flag should be set to your publicly +reachable IP address. + +# Creating an lnd.conf (Optional) Optionally, if you'd like to have a persistent configuration between `lnd` launches, allowing you to simply type `lnd --bitcoin.testnet --bitcoin.active` -at the command line. You can create an `lnd.conf`. +at the command line, you can create an `lnd.conf`. **On MacOS, located at:** `/Users/[username]/Library/Application Support/Lnd/lnd.conf` @@ -114,23 +172,17 @@ Here's a sample `lnd.conf` to get you started: debuglevel=trace debughtlc=true maxpendingchannels=10 -profile=5060 -externalip=128.111.13.23 -externalip=111.32.29.29 [Bitcoin] bitcoin.active=1 -bitcoin.rpchost=localhost:18334 ``` Notice the `[Bitcoin]` section. This section houses the parameters for the -Bitcoin chain. Also `lnd` also supports Litecoin, one is able to also specified -(but not concurrently with Bitcoin!) the proper parameters, so `lnd` knows to -be active on Litecoin's testnet4. +Bitcoin chain. `lnd` also supports Litecoin testnet4 (but not both BTC and LTC +at the same time), so when working with Litecoin be sure to set to parameters +for Litecoin accordingly. -#### Accurate as of: -roasbeef/btcd commit: f8c02aff4e7a807ba0c1349e2db03695d8e790e8 - -roasbeef/btcutil commit: a259eaf2ec1b54653cdd67848a41867f280797ee - -lightningnetwork/lnd commit: d7b36c6 +# Accurate as of: +- _roasbeef/btcd commit:_ `f8c02aff4e7a807ba0c1349e2db03695d8e790e8` +- _roasbeef/btcutil commit:_ `a259eaf2ec1b54653cdd67848a41867f280797ee` +- _lightningnetwork/lnd commit:_ `d7b36c6`