From 157145df65483202f805fe6912fbff8b419dade1 Mon Sep 17 00:00:00 2001
From: Olaoluwa Osuntokun <laolu32@gmail.com>
Date: Sat, 1 Apr 2017 16:03:34 +0200
Subject: [PATCH] docs: revamp installation docs to note --externalip and auto
 RPC config

---
 docs/INSTALL.md | 118 +++++++++++++++++++++++++++++-------------------
 1 file changed, 72 insertions(+), 46 deletions(-)

diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 2b41212c..ccbaac3b 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -1,11 +1,13 @@
-# Installation for Lnd and Btcd
+# Installation for lnd and btcd
 
 ### If Glide isn't installed, install it:
+
 ```
 $ go get -u github.com/Masterminds/glide
 ```
 
 ### Install lnd:
+
 ```
 $ cd $GOPATH
 $ git clone https://github.com/lightningnetwork/lnd $GOPATH/src/github.com/lightningnetwork/lnd
@@ -14,29 +16,14 @@ $ glide install
 $ go install . ./cmd/...
 ```
 
-### Create lnd.conf:
-**On MacOS, located at:**
-/Users/[username]/Library/Application Support/Lnd/lnd.conf
-
-**On Linux, located at:**
-~/.lnd/lnd.conf
-
-**lnd.conf:**
-(Note: Replace `kek` with the username and password you prefer.)
-```
-[Application Options]
-rpcuser=kek
-rpcpass=kek
-btcdhost=127.0.0.1
-debuglevel=debug
-```
-
 ### Install btcutil: (must be from roasbeef fork, not from btcsuite)
+
 ```
 $ go get -u github.com/roasbeef/btcutil
 ```
 
 ### Install btcd: (must be from roasbeef fork, not from btcsuite)
+
 ```
 $ cd $GOPATH/src/github.com/roasbeef/btcd
 $ glide install
@@ -44,54 +31,93 @@ $ go install . ./cmd/...
 ```
 
 ### Start btcd (will create rpc.cert and default btcd.conf):
+
 ```
 $ btcd --testnet --txindex --rpcuser=kek --rpcpass=kek
 ```
-(Note: It may take several minutes to find segwit-enabled peers.)
 
-### Add a limited username and password to btcd.conf and restart
-(Note: Replace `kek` with the username and password you prefer.)
+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.
 
-**On Linux:**
+(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`
+RPC command:
 ```
-$ sed -i 's#; rpclimituser=whatever_limited_username_you_want#rpclimituser=kek#' ~/.btcd/btcd.conf
-$ sed -i 's#; rpclimitpass=#rpclimitpass=kek#' ~/.btcd/btcd.conf
+$ btcctl --testnet getinfo
+{
+  "version": 120000,
+  "protocolversion": 70002,
+  "blocks": 1114996, 
+  "timeoffset": 0,
+  "connections": 7,
+  "proxy": "",
+  "difficulty": 422570.58270815,
+  "testnet": true,
+  "relayfee": 0.00001,
+  "errors": ""
+}
 ```
 
-**On MacOS:**
-```
-$ sed -i 's#; rpclimituser=whatever_limited_username_you_want#rpclimituser=kek#' /Users/[username]/Library/Application Support/Btcd/btcd.conf
-$ sed -i 's#; rpclimitpass=#rpclimitpass=kek#' /Users/[username]/Library/Application Support/Btcd/btcd.conf
-```
+Additionally, you can monitor btcd's logs to track its syncing progress in real
+time. 
 
-If you did not have a `btcd.conf` file yet, you can simply paste the following into it:
-````
-[Application Options]
-rpclimituser=<the username you picked in lnd.conf>
-rpclimitpass=<the password you picked in lnd.conf>
-````
-
-**Then, regardless of OS:**
-```
-$ btcctl --testnet stop
-$ btcd --testnet
-```
-
-### Check to see that peers are connected:
+You can test your `btcd` node's connectivity using the `getpeerinfo` command:
 ```
 $ btcctl --testnet getpeerinfo | more
 ```
 
-### Start Lnd: (Once btcd has synced testnet)
+### Start lnd: (once btcd has synced testnet)
+
 ```
-$ lnd --testnet
+$ lnd --testnet --debuglevel=debug --externalip=X.X.X.X
 ```
 
-### Start Lnd on Simnet: (Doesn’t require testnet syncing.)
+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 `--simnet` flag instead of the `--testnet` flag.
+
+Another relevant command line flag for local testing of new `lnd` developments
+is the `--debughtlc` flag. When starting `lnd` with this flag, it'll be able to
+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.
 ```
 $ lnd --simnet --debughtlc
 ```
 
+### Create an lnd.conf (Optional)
+
+Optionally, if you'd like to have a persistent configuration between `lnd`
+launches, allowing you to simply type `lnd --testnet` at the command line. You
+can create an `lnd.conf`. 
+
+**On MacOS, located at:**
+`/Users/[username]/Library/Application Support/Lnd/lnd.conf`
+
+**On Linux, located at:**
+`~/.lnd/lnd.conf`
+
+Here's a sample `lnd.conf` to get you started:
+```
+[Application Options]
+btcdhost=localhost:18834
+debuglevel=trace
+debughtlc=true
+maxpendingchannels=10
+profile=5060
+externalip=128.111.13.23,111.32.29.29
+```
+
 #### Accurate as of:
 roasbeef/btcd commit: 54362e17a5b80643ef1e12edc08895a2e2a1202b