docs(docker): update README for improved clarity and accuracy

Author: Euler-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 **Docker** installed. If not, please follow the [official Docker installation guide](https://docs.docker.com/get-docker/). 
+>
+>All commands should be executed from the `lnd/docker/` directory. Depending on your system's configuration, you may need to prefix **docker** commands with **sudo**. For `Linux` users, we highly recommend following the official [Docker documentation to manage Docker as a non-root](https://docs.docker.com/engine/install/linux-postinstall/) user, which allows you to run commands without sudo safely
+
 Start `btcd`, and then create an address for `Alice` that we'll directly mine
 bitcoin into.
 ```shell
@@ -73,11 +72,11 @@ $  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 exec -i -t alice bash
+$  docker compose run -d --name alice --volume simnet_lnd_alice:/root/.lnd lnd
+$  docker exec -it alice bash
 
-# Generate a new backward compatible nested p2sh address for Alice:
-alice $  lncli --network=simnet newaddress np2wkh 
+# Generate a new native SegWit (Bech32) address for Alice:
+alice $  lncli --network=simnet newaddress p2wkh
 
 # Recreate "btcd" node and set Alice's address as mining address:
 $  export MINING_ADDRESS=<alice_address>
@@ -86,9 +85,6 @@ $  docker-compose up -d btcd
 # Generate 400 blocks (we need at least "100 >=" blocks because of coinbase 
 # block maturity and "300 ~=" in order to activate segwit):
 $  docker exec -it btcd /start-btcctl.sh generate 400
-
-# Check that segwit is active:
-$  docker exec -it btcd /start-btcctl.sh getblockchaininfo | grep -A 1 segwit
 ```
 
 Check `Alice` balance:
@@ -100,8 +96,8 @@ 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 exec -i -t bob bash
+$  docker compose run -d --name bob --volume simnet_lnd_bob:/root/.lnd lnd
+$  docker exec -it bob bash
 
 # Get the identity pubkey of "Bob" node:
 bob $  lncli --network=simnet getinfo
@@ -267,66 +263,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 <faucet_identity_address>@<faucet_host>
-```
-
-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 +275,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 +313,5 @@ Note: The address `2N1NQzFjCy1NnpAH3cT4h4GoByrAAkiH7zu` is just a random example
 
 * How to see `alice` | `bob` | `btcd` | `lnd` | `bitcoind` logs?
 ```shell
-$  docker-compose logs <alice|bob|btcd|lnd|bitcoind>
+$  docker compose logs <alice|bob|btcd|lnd|bitcoind>
 ```

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 <laolu@lightning.engineering>"
 
@@ -10,15 +11,15 @@ 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.25.0 
 
 # Grab and install the latest version of of btcd and all related dependencies.
 RUN git clone https://github.com/btcsuite/btcd.git . \
     && git checkout $BTCD_VERSION \
     && 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

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

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" \
         "$@"