Skip to content

Update step-by-step send payment guide with docker #10461

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Euler-B wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Update step-by-step send payment guide with docker #10461

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f335f37
docs(docker): update README for improved clarity and accuracy
Euler-B Dec 22, 2025
0ffe145
Merge branch 'master' into doc/updatePaytoPaywithDocker
Euler-B Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 20 additions & 84 deletions docker/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Comment on lines +1 to +5
Copy link

@gemini-code-assist gemini-code-assist bot Jan 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The updated introduction removes backticks from terms like lnd, btcd, and docker-compose.yml. For consistency with the rest of the document, where such terms are enclosed in backticks for code formatting, it would be better to add them.

Suggested change
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
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)
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -73,22 +72,19 @@ $ 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>
$ docker-compose up -d btcd
$ 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:
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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>
```
27 changes: 16 additions & 11 deletions docker/btcd/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.5-alpine as builder
ARG GO_VERSION=1.25.5
FROM golang:${GO_VERSION}-alpine AS builder

LABEL maintainer="Olaoluwa Osuntokun <laolu@lightning.engineering>"

Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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
2 changes: 1 addition & 1 deletion docker/docker-compose.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -8,6 +7,7 @@ services:
container_name: btcd
build:
context: btcd/
dockerfile: Dockerfile
volumes:
- shared:/rpc
- bitcoin:/data
Expand Down
6 changes: 1 addition & 5 deletions docker/lnd/start-lnd.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ RPCUSER=$(set_default "$RPCUSER" "devuser")
RPCPASS=$(set_default "$RPCPASS" "devpass")
DEBUG=$(set_default "$LND_DEBUG" "debug")
CHAIN=$(set_default "$CHAIN" "bitcoin")
HOSTNAME=$(hostname)
HOSTNAME=$(set_default "$HOSTNAME" "localhost")

# CAUTION: DO NOT use the --noseedback for production/mainnet setups, ever!
# Also, setting --rpclisten to $HOSTNAME will cause it to listen on an IP
Expand All @@ -64,7 +64,6 @@ HOSTNAME=$(hostname)
if [ "$BACKEND" == "bitcoind" ]; then
exec lnd \
--noseedbackup \
"--$CHAIN.active" \
"--$CHAIN.$NETWORK" \
"--$CHAIN.node"="$BACKEND" \
"--$BACKEND.rpchost"="$RPCHOST" \
Expand All @@ -73,21 +72,18 @@ if [ "$BACKEND" == "bitcoind" ]; then
"--$BACKEND.zmqpubrawblock"="tcp://$RPCHOST:28332" \
"--$BACKEND.zmqpubrawtx"="tcp://$RPCHOST:28333" \
"--rpclisten=$HOSTNAME:10009" \
"--rpclisten=localhost:10009" \
--debuglevel="$DEBUG" \
"$@"
elif [ "$BACKEND" == "btcd" ]; then
exec lnd \
--noseedbackup \
"--$CHAIN.active" \
"--$CHAIN.$NETWORK" \
Comment on lines 79 to 80
Copy link

@gemini-code-assist gemini-code-assist bot Jan 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The --$CHAIN.active flag was removed for the btcd backend, but it's still present for the bitcoind backend. While lnd might default to activating the bitcoin chain, it's better to be explicit for clarity and consistency between the two backend configurations in this script.

Suggested change
--noseedbackup \
"--$CHAIN.active" \
"--$CHAIN.$NETWORK" \
--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" \
Comment on lines 79 to 90
Copy link

@gemini-code-assist gemini-code-assist bot Jan 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The removal of --$CHAIN.active and --rpclisten=$HOSTNAME:10009 are great improvements. The former is deprecated and the latter improves security by only listening on localhost within the container. However, the lnd command for the btcd backend is missing the --$CHAIN.active flag that is still present for the bitcoind backend. While this flag is deprecated, for consistency it might be better to remove it from the bitcoind block as well.

--debuglevel="$DEBUG" \
"$@"
else
Expand Down
Loading