Docker Images

Docker Buildx is an extension of Docker's build command, that provides a more efficient way to create images. It is part of Docker 19.03 and can also be manually installed as a CLI plugin for older versions.

Enable Docker CLI experimental features
Docker CLI experimental features are required to use Buildx. Enable them by setting the DOCKER_CLI_EXPERIMENTAL environment variable to enabled.
You can do this by adding the following line to your shell profile file (.bashrc, .zshrc, etc.):

export DOCKER_CLI_EXPERIMENTAL=enabled

After adding it, source your shell profile file or restart your shell to apply the changes.

Create a new builder instance
By default, Docker uses the "legacy" builder. You need to create a new builder instance that uses BuildKit. To create a new builder instance, use the following command:

docker buildx create --use

The --use flag sets the newly created builder as the current one.

Check Buildx is working
Use the docker buildx inspect --bootstrap command to verify that Buildx is working correctly. The --bootstrap option ensures the builder instance is running before inspecting it. The output should look something like this:

Name:          my_builder
Driver:        docker-container
Last Activity: 2023-06-13 04:37:30 +0000 UTC
Nodes:
Name:      my_builder0
Endpoint:  unix:///var/run/docker.sock
Status:    running
Buildkit:  v0.11.6
Platforms: linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/amd64/v4, linux/386

Install binfmt-support and qemu-user-static if not installed already.

sudo apt-get update
sudo apt-get install docker.io binfmt-support qemu-user-static
sudo systemctl restart docker

Setup QEMU to run binaries from multiple architectures

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

Confirm QEMU is working

Again run docker buildx inspect --bootstrap command to verify that linux/arm64 is in the list of platforms.

Name:          my_builder
Driver:        docker-container
Last Activity: 2023-06-13 04:37:30 +0000 UTC
Nodes:
Name:      my_builder0
Endpoint:  unix:///var/run/docker.sock
Status:    running
Buildkit:  v0.11.6
Platforms: linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/amd64/v4, linux/386, linux/arm64, linux/riscv64, linux/ppc64, linux/ppc64le, linux/s390x, linux/mips64le, linux/mips64

Ensure that your multiarch setup is working
Run script tools/build-release.sh --push docker to build amd64, arm64v8, latest and multiarch images and publish them on Dockerhub.
If you do not want to push the images directly on Dockerhub then run tools/build-release.sh docker. It will only create images locally but not push them to Dockerhub.

📘
Before running a Docker image on a different platform than your local architecture, ensure that the multiarch/qemu-user-static setup is functioning correctly. Instructions for setting this up can be found here.

The Core Lightning (CLN) Docker image (platforms: linux/amd64, linux/arm64, linux/arm/v7) can be tested with a local Bitcoin regtest setup using the following command:

docker run -it --rm --platform=linux/amd64 --network=host -v '/root/.lightning:/root/.lightning' -v '/root/.bitcoin:/root/.bitcoin' elementsproject/lightningd:latest --network=regtest

Once the cl-repro-<distro> builder image is created, you can run it with:

docker run -it -v $(pwd):/repo cl-repro-noble /bin/bash

Get the Docker container ID of the above container using:

Start a shell in the container with:

docker exec -it <container-id-from-step2> bash

You can now run . tools/repro-build.sh with --force-version and --force-mtime arguments as needed.

Create a directory named lightning-poststart.d in the LIGHTNINGD_DATA (/root/.lightning) directory.
Save executable scripts in this directory.
Run the container ensuring that:
- The lightning data directory is mounted.
- The lightning data directory path is defined with the environment variable LIGHTNINGD_DATA.

docker run -it --rm --platform=linux/amd64 --network=host -v '/root/.lightning:/root/.lightning' -v '/root/.bitcoin:/root/.bitcoin' -e LIGHTNINGD_DATA=/root/.lightning elementsproject/lightningd:latest --network=regtest

This setup assumes that both bitcoind and vlsd will be running on your host system.
Start your bitcoind node on the local machine.
Start vlsd locally with your prefered configuration. For example:

export LIGHTNING_VLS_DIR=/root/.lightning
export GREENLIGHT_VERSION="v25.12"
export VLS_CLN_VERSION="v25.12"
export VLS_NETWORK="regtest"
export BITCOIND_RPC_URL="http://user:[email protected]:18443"
export RUST_LOG=info
export RUST_BACKTRACE=1

/home/validating-lightning-signer/target/release/vlsd \
  --datadir "$LIGHTNING_VLS_DIR"/.lightning-signer \
  --network regtest \
  --connect http://127.0.0.1:7701 \
  --rpc-server-address 127.0.0.1 \
  --rpc-server-port 8000 \
  --rpc-user vlsuser \
  --rpc-pass vlspassword \
  --log-level info

Finally, run the Core Lightning node:

4.1 Either by utilizing our docker image flavor elementsproject/lightningd:v25.12-vls which comes with pre-built remote_hsmd_socket binaries.

docker run -it --rm -d \
  --platform=linux/amd64 \
  --network=host \
  -v '/root/.lightning:/root/.lightning' \
  -v '/root/.bitcoin:/root/.bitcoin' \
  -e GREENLIGHT_VERSION="v25.12" \
  -e VLS_CLN_VERSION="v25.12" \
  -e VLS_NETWORK="regtest" \
  -e BITCOIND_RPC_URL="http://user:[email protected]:18443" \
  -e LIGHTNINGD_NETWORK=regtest \
  elementsproject/lightningd:v25.12-vls \
  --bitcoin-rpcconnect=0.0.0.0 \
  --bitcoin-rpcuser=user \
  --bitcoin-rpcpassword=password \
  --network=regtest \
  --database-upgrade=true \
  --bitcoin-datadir=/root/.bitcoin \
  --log-level=debug \
  --announce-addr=127.0.0.1:19750 \
  --bind-addr=localhost:8989 \
  --bind-addr=ws:127.0.0.1:5020 \
  --bind-addr=0.0.0.0:19750 \
  --bitcoin-rpcport=18443 \
  --clnrest-port=3020 \
  --grpc-port=9740 \
  --subdaemon=hsmd:/var/lib/vls/bin/remote_hsmd_socket

4.2 Or, by replacing subdaemon hsmd with your mounted remote_hsmd_socket:

docker run -it --rm -d \
  --platform=linux/amd64 \
  --network=host \
  -v '/root/.lightning:/root/.lightning' \
  -v '/root/.bitcoin:/root/.bitcoin' \
  -v '/root/vls/target/release/remote_hsmd_socket:/var/lib/vls/bin/remote_hsmd_socket'
  -e GREENLIGHT_VERSION="v25.12" \
  -e VLS_CLN_VERSION="v25.12" \
  -e VLS_NETWORK="regtest" \
  -e BITCOIND_RPC_URL="http://user:[email protected]:18443" \
  -e LIGHTNINGD_NETWORK=regtest \
  elementsproject/lightningd:v25.12 \
  --bitcoin-rpcconnect=0.0.0.0 \
  --bitcoin-rpcuser=user \
  --bitcoin-rpcpassword=password \
  --network=regtest \
  --database-upgrade=true \
  --bitcoin-datadir=/root/.bitcoin \
  --log-level=debug \
  --announce-addr=127.0.0.1:19750 \
  --bind-addr=localhost:8989 \
  --bind-addr=ws:127.0.0.1:5020 \
  --bind-addr=0.0.0.0:19750 \
  --bitcoin-rpcport=18443 \
  --clnrest-port=3020 \
  --grpc-port=9740 \
  --subdaemon=hsmd:/var/lib/vls/bin/remote_hsmd_socket