From 5b8a3eb72ff80660061319fdca51173e6e9dd3c4 Mon Sep 17 00:00:00 2001 From: Oliver Gugger Date: Mon, 11 Jan 2021 10:21:03 +0100 Subject: [PATCH] doc: update INSTALL.md, recommend installing releases To prevent novice users from running non-release versions, we update the installation instructions to point them towards our release binaries. We also document the new Docker build helper that allows you to compile lnd without needing to install golang. --- docs/INSTALL.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 70 insertions(+), 4 deletions(-) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index d565a5e0..3ac5c9e0 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -1,7 +1,10 @@ # Table of Contents * [Installation](#installation) - * [Preliminaries](#preliminaries) - * [Installing lnd](#installing-lnd) + * [Installing a binary release](#installing-a-binary-release) + * [Building a tagged version with Docker](#building-a-tagged-version-with-docker) + * [Building a development version from source](#building-a-development-version-from-source) + * [Preliminaries](#preliminaries-for-installing-from-source) + * [Installing lnd](#installing-lnd-from-source) * [Available Backend Operating Modes](#available-backend-operating-modes) * [btcd Options](#btcd-options) * [Neutrino Options](#neutrino-options) @@ -20,7 +23,70 @@ # Installation -### Preliminaries +There are multiple ways to install `lnd`. For most users the easiest way is to +[download and install an official release binary](#installing-a-binary-release). +Those release binaries are always built with production in mind and have all +RPC subservers enabled. + +More advanced users that want to build `lnd` from source also have multiple +options. To build a tagged version, there is a docker build helper script that +allows users to +[build `lnd` from source without needing to install `golang`](#building-a-tagged-version-with-docker). +That is also the preferred way to build and verify the reproducible builds that +are released by the team. See +[release.md for more information about reproducible builds](release.md). + +Finally, there is the option to build `lnd` fully manually. This requires more +tooling to be set up first but allows to produce non-production (debug, +development) builds. + +## Installing a binary release + +Downloading and installing an official release binary is recommended for use on +mainnet. +[Visit the release page on GitHub](https://github.com/lightningnetwork/lnd/releases) +and select the latest version that does not have the "Pre-release" label set +(unless you explicitly want to help test a Release Candidate, RC). + +Choose the package that best fits your operating system and system architecture. +It is recommended to choose 64bit versions over 32bit ones, if your operating +system supports both. + +Extract the package and place the two binaries (`lnd` and `lncli` or `lnd.exe` +and `lncli.exe` on Windows) somewhere where the operating system can find them. + +## Building a tagged version with Docker + +To use the Docker build helper, you need to have the following software +installed and set up on your machine: + - Docker + - `make` + - `bash` + +To build a specific git tag of `lnd`, simply run the following steps (assuming +`v0.x.y-beta` is the tagged version to build): + +```shell +git clone https://github.com/lightningnetwork/lnd +cd lnd +git checkout v0.x.y-beta +make docker-release tag=v0.x.y-beta +``` + +This will create a directory called `lnd-v0.x.y-beta` that contains the release +binaries for all operating system and architecture pairs. A single pair can also +be selected by specifying the `sys=linux-amd64` flag for example. See +[release.md for more information on reproducible builds](release.md). + +## Building a development version from source + +Building and installing `lnd` from source is only recommended for advanced users +and/or developers. Running the latest commit from the `master` branch is not +recommended for mainnet. The `master` branch can at times be unstable and +running your node off of it can prevent it to go back to a previous, stable +version if there are database migrations present. + +### Preliminaries for installing from source In order to work with [`lnd`](https://github.com/lightningnetwork/lnd), the following build dependencies are required: @@ -99,7 +165,7 @@ `lnd` into your `$GOPATH` for development purposes. Instead, your `lnd` repo can now live anywhere! -### Installing lnd +### Installing lnd from source With the preliminary steps completed, to install `lnd`, `lncli`, and all related dependencies run the following commands: