From 3d841d5b8a0cb3e996138dbce59f830b4ed40cbd Mon Sep 17 00:00:00 2001 From: ShahanaFarooqui Date: Tue, 11 Jun 2024 22:50:46 -0700 Subject: [PATCH] doc: Added Miscellaneous section for Docker users Added CLN image execution and testing hints for Docker users. Changelog-None. --- .../docker-images.md | 90 +++++++++++++++++-- 1 file changed, 85 insertions(+), 5 deletions(-) diff --git a/doc/contribute-to-core-lightning/docker-images.md b/doc/contribute-to-core-lightning/docker-images.md index b758b4e66..35cd98b03 100644 --- a/doc/contribute-to-core-lightning/docker-images.md +++ b/doc/contribute-to-core-lightning/docker-images.md @@ -13,7 +13,7 @@ Docker Buildx is an extension of Docker's build command, that provides a more ef 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.): -``` +```shell export DOCKER_CLI_EXPERIMENTAL=enabled ``` @@ -22,7 +22,7 @@ After adding it, source your shell profile file or restart your shell to apply t 2. 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: -``` +```shell docker buildx create --use ``` @@ -33,7 +33,7 @@ The --use flag sets the newly created builder as the current one. 1. 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: -``` +```shell Name: my_builder Driver: docker-container Last Activity: 2023-06-13 04:37:30 +0000 UTC @@ -55,7 +55,7 @@ sudo systemctl restart docker 3. Setup QEMU to run binaries from multiple architectures -``` +```shell docker run --rm --privileged multiarch/qemu-user-static --reset -p yes ``` @@ -63,7 +63,7 @@ docker run --rm --privileged multiarch/qemu-user-static --reset -p yes Again run `docker buildx inspect --bootstrap` command to verify that `linux/arm64` is in the list of platforms. -``` +```shell Name: my_builder Driver: docker-container Last Activity: 2023-06-13 04:37:30 +0000 UTC @@ -81,3 +81,83 @@ Platforms: linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/amd64/v4, linux/38 2. Run script `tools/build-release.sh --push docker` to build `amd64`, `arm64v8`, `latest` and `multiarch` images and publish them on Dockerhub. 3. 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. + + +# Miscellaneous +## Testing Docker image + +> 📘 QEMU Multiarch Setup +> +> 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](https://docs.corelightning.org/docs/docker-images#setting-up-multiarchqemu-user-static). + + +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: + +```shell +docker run -it --rm --platform=linux/amd64 --network=host -v '/root/.lightning:/root/.lightning' -v '/root/.bitcoin:/root/.bitcoin' elementsproject/lightningd:latest --network=regtest +``` + +## Test repro Dockerfiles and repro-build.sh: +1. Once the `cl-repro-` builder image is created, you can run it with: + +```shell +docker run -it -v $(pwd):/repo cl-repro-noble /bin/bash +``` + +2. Get the Docker container ID of the above container using: + +```shell +docker container ps +``` + +3. Start a shell in the container with: + +```shell +docker exec -it bash +``` + +4. You can now run `. tools/repro-build.sh` with `--force-version` and `--force-mtime` arguments as needed. + +## Execute other scripts for testing: + +1. Create a directory named `lightning-poststart.d` in the `LIGHTNINGD_DATA` (`/root/.lightning`) directory. + +2. Save executable scripts in this directory. + +3. Run the container ensuring that: + - The lightning data directory is mounted. + - The lightning data directory path is defined with the environment variable `LIGHTNINGD_DATA`. + +```shell +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 + +``` + +## Using CLI for CLN Node Running in the Docker Container + +### From Host (Local CLI) + +Use your local lightning-cli (if installed), ensuring that `lightning-dir` is configured with the local directory that is mounted to the container's `root/.lightning`. + +```shell +sudo lightning-cli --regtest --lightning-dir=/root/.lightning getinfo +``` + +### Inside Docker Container +1. Get the container ID for the image `elementsproject/lightningd:latest`: + +```shell +docker container ps +``` + +2. Run a new command in the running `lightningd` container: + +```shell +docker exec -it bash +``` + +3. Use the container's `lightning-cli`: + +```shell +lightning-cli --regtest getinfo +```