diff --git a/docker/README.md b/docker/README.md index b2f1d1efc72..6083987c0eb 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,18 +1,16 @@ -This document is written for people who are eager to do something with -the Lightning Network Daemon (`lnd`). This folder uses `docker-compose` to -package `lnd` and `btcd` together to make deploying the two daemons as easy as -typing a few commands. All configuration between `lnd` and `btcd` are handled -automatically by their `docker-compose` config file. +This document is intended for those looking to get started with +the Lightning Network Daemon (lnd). This folder uses docker to package lnd and +btcd together, making the deployment of both daemons as simple as running a +few commands. All configuration between lnd and btcd is handled automatically +by the docker-compose.yml file ### Prerequisites Name | Version --------|--------- -docker-compose | 1.9.0 -docker | 1.13.0 +docker | 20.10.13+ ### Table of content * [Create lightning network cluster](#create-lightning-network-cluster) - * [Connect to faucet lightning node](#connect-to-faucet-lightning-node) * [Building standalone docker images](#building-standalone-docker-images) * [Using bitcoind version](#using-bitcoind-version) * [Start Bitcoin Node with bitcoind using Docker Compose](#start-bitcoin-node-with-bitcoind-using-docker-compose) @@ -30,10 +28,6 @@ possible to spin up an arbitrary number of `lnd` instances within containers to create a mini development cluster. All state is saved between instances using a shared volume. -Current workflow is big because we recreate the whole network by ourselves, -next versions will use the started `btcd` bitcoin node in `testnet` and -`faucet` wallet from which you will get the bitcoins. - In the workflow below, we describe the steps required to recreate the following topology, and send a payment from `Alice` to `Bob`. ```text @@ -62,6 +56,11 @@ topology, and send a payment from `Alice` to `Bob`. * Close the channel between `Alice` and `Bob`. * Check that on-chain `Bob` balance was changed. +> [!IMPORTANT] +> **Prerequisites:** This guide assumes you have **LND** installed. If not, please follow the [installation guide](/docs/INSTALL.md). +> The following commands require root privileges. Please prefix +them with `sudo` if necessary. + Start `btcd`, and then create an address for `Alice` that we'll directly mine bitcoin into. ```shell @@ -73,7 +72,7 @@ $ docker volume create simnet_lnd_alice $ docker volume create simnet_lnd_bob # Run the "Alice" container and log into it: -$ docker-compose run -d --name alice --volume simnet_lnd_alice:/root/.lnd lnd +$ docker compose run -d --name alice --volume simnet_lnd_alice:/root/.lnd lnd $ docker exec -i -t alice bash # Generate a new backward compatible nested p2sh address for Alice: @@ -100,7 +99,7 @@ Connect `Bob` node to `Alice` node. ```shell # Run "Bob" node and log into it: -$ docker-compose run -d --name bob --volume simnet_lnd_bob:/root/.lnd lnd +$ docker compose run -d --name bob --volume simnet_lnd_bob:/root/.lnd lnd $ docker exec -i -t bob bash # Get the identity pubkey of "Bob" node: @@ -267,66 +266,6 @@ bob $ lncli --network=simnet walletbalance } ``` -### Connect to faucet lightning node -In order to be more confident with `lnd` commands I suggest you to try -to create a mini lightning network cluster ([Create lightning network cluster](#create-lightning-network-cluster)). - -In this section we will try to connect our node to the faucet/hub node -which we will create a channel with and send some amount of -bitcoins. The schema will be following: - -```text -+ ----- + + ------ + (1) + --- + -| Alice | <--- channel ---> | Faucet | <--- channel ---> | Bob | -+ ----- + + ------ + + --- + - | | | - | | | <--- (2) - + - - - - - - - - - - - - - + - - - - - - - - - - - - - + - | - + --------------- + - | Bitcoin network | <--- (3) - + --------------- + - - - (1) You may connect an additional node "Bob" and make the multihop - payment Alice->Faucet->Bob - - (2) "Faucet", "Alice" and "Bob" are the lightning network daemons which - create channels to interact with each other using the Bitcoin network - as source of truth. - - (3) In current scenario "Alice" and "Faucet" lightning network nodes - connect to different Bitcoin nodes. If you decide to connect "Bob" - to "Faucet" then the already created "btcd" node would be sufficient. -``` - -First you need to run `btcd` node in `testnet` and wait for it to be -synced with test network (`May the Force and Patience be with you`). -```shell -# Init bitcoin network env variable: -$ NETWORK="testnet" docker-compose up -``` - -After `btcd` synced, connect `Alice` to the `Faucet` node. - -The `Faucet` node address can be found at the [Faucet Lightning Community webpage](https://faucet.lightning.community). - -```shell -# Run "Alice" container and log into it: -$ docker-compose run -d --name alice lnd_btc; docker exec -i -t "alice" bash - -# Connect "Alice" to the "Faucet" node: -alice $ lncli --network=testnet connect @ -``` - -After a connection is achieved, the `Faucet` node should create the channel -and send some amount of bitcoins to `Alice`. - -**What you may do next?:** -- Send some amount to `Faucet` node back. -- Connect `Bob` node to the `Faucet` and make multihop payment (`Alice->Faucet->Bob`) -- Close channel with `Faucet` and check the onchain balance. - ### Building standalone docker images Instructions on how to build standalone docker images (for development or @@ -339,7 +278,7 @@ If you are using the bitcoind version of the compose file i.e. `docker-compose-b #### Start Bitcoin Node with bitcoind using Docker Compose To launch the Bitcoin node using bitcoind in the regtest network using Docker Compose, use the following command: ```shell -$ NETWORK="regtest" docker-compose -f docker-compose-bitcoind.yml up +$ NETWORK="regtest" docker compose -f docker-compose-bitcoind.yml up ``` #### Generating RPCAUTH @@ -377,5 +316,5 @@ Note: The address `2N1NQzFjCy1NnpAH3cT4h4GoByrAAkiH7zu` is just a random example * How to see `alice` | `bob` | `btcd` | `lnd` | `bitcoind` logs? ```shell -$ docker-compose logs +$ docker compose logs ``` diff --git a/docker/btcd/Dockerfile b/docker/btcd/Dockerfile index 699c3466cb2..69caebea88f 100644 --- a/docker/btcd/Dockerfile +++ b/docker/btcd/Dockerfile @@ -1,6 +1,7 @@ # If you change this please also update GO_VERSION in Makefile (then run # `make lint` to see where else it needs to be updated as well). -FROM golang:1.25.3-alpine as builder +ARG GO_VERSION=1.25.3 +FROM golang:${GO_VERSION}-alpine AS builder LABEL maintainer="Olaoluwa Osuntokun " @@ -10,7 +11,7 @@ RUN apk add --no-cache git gcc musl-dev WORKDIR $GOPATH/src/github.com/btcsuite/btcd # Pin down btcd to a version that we know works with lnd. -ARG BTCD_VERSION=v0.23.4 +ARG BTCD_VERSION=v0.24.2 # Grab and install the latest version of of btcd and all related dependencies. RUN git clone https://github.com/btcsuite/btcd.git . \ @@ -18,7 +19,7 @@ RUN git clone https://github.com/btcsuite/btcd.git . \ && go install -v . ./cmd/... # Start a new image -FROM alpine as final +FROM alpine:3.22 AS final # Expose mainnet ports (server, rpc) EXPOSE 8333 8334 @@ -29,7 +30,7 @@ EXPOSE 18333 18334 # Expose simnet ports (server, rpc) EXPOSE 18555 18556 -# Expose segnet ports (server, rpc) +# Expose signet ports (server, rpc) EXPOSE 28901 28902 # Copy the compiled binaries from the builder image. @@ -45,13 +46,13 @@ COPY "start-btcd.sh" . RUN apk add --no-cache \ bash \ ca-certificates \ -&& mkdir "/rpc" "/root/.btcd" "/root/.btcctl" \ -&& touch "/root/.btcd/btcd.conf" \ -&& chmod +x start-btcctl.sh \ -&& chmod +x start-btcd.sh \ -# Manually generate certificate and add all domains, it is needed to connect -# "btcctl" and "lnd" to "btcd" over docker links. -&& "/bin/gencerts" --host="*" --directory="/rpc" --force + && mkdir "/rpc" "/root/.btcd" "/root/.btcctl" \ + && touch "/root/.btcd/btcd.conf" \ + && chmod +x start-btcctl.sh \ + && chmod +x start-btcd.sh \ + # Manually generate certificate and add all domains, it is needed to connect + # "btcctl" and "lnd" to "btcd" over docker links. + && "/bin/gencerts" --host="*" --host="blockchain" --directory="/rpc" --force # Create a volume to house pregenerated RPC credentials. This will be # shared with any lnd, btcctl containers so they can securely query btcd's RPC @@ -60,3 +61,7 @@ RUN apk add --no-cache \ # Otherwise manually generated certificate will be overridden with shared # mounted volume! For more info read dockerfile "VOLUME" documentation. VOLUME ["/rpc"] + +# Health check to ensure btcd is running +HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \ + CMD pgrep btcd || exit 1 diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index ade93e07261..7e97ceff391 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -1,4 +1,3 @@ -version: '2' services: # btc is an image of bitcoin node which used as base image for btcd and # btccli. The environment variables default values determined on stage of @@ -8,6 +7,7 @@ services: container_name: btcd build: context: btcd/ + dockerfile: Dockerfile volumes: - shared:/rpc - bitcoin:/data diff --git a/docker/lnd/start-lnd.sh b/docker/lnd/start-lnd.sh index 7b83c231173..24fd240060b 100755 --- a/docker/lnd/start-lnd.sh +++ b/docker/lnd/start-lnd.sh @@ -60,6 +60,7 @@ HOSTNAME=$(hostname) # Also, setting --rpclisten to $HOSTNAME will cause it to listen on an IP # address that is reachable on the internal network. If you do this outside of # docker, this might be a security concern! +# [:18556] is the default btcd RPC port in SIMNET network. if [ "$BACKEND" == "bitcoind" ]; then exec lnd \ @@ -79,14 +80,12 @@ if [ "$BACKEND" == "bitcoind" ]; then elif [ "$BACKEND" == "btcd" ]; then exec lnd \ --noseedbackup \ - "--$CHAIN.active" \ "--$CHAIN.$NETWORK" \ "--$CHAIN.node"="$BACKEND" \ "--$BACKEND.rpccert"="$RPCCRTPATH" \ "--$BACKEND.rpchost"="$RPCHOST" \ "--$BACKEND.rpcuser"="$RPCUSER" \ "--$BACKEND.rpcpass"="$RPCPASS" \ - "--rpclisten=$HOSTNAME:10009" \ "--rpclisten=localhost:10009" \ --debuglevel="$DEBUG" \ "$@"