VLS Containers

Installing Docker

Docker Documentation

Docker Engine is available on a variety of Linux distros, macOS, and Windows 10 through Docker Desktop, and as a static binary installation. Refer to the official docker documentation

• Ubuntu
• Fedora

Distro Packages

Debian/Ubuntu:

sudo apt install docker.io docker-doc docker-compose containerd runc
sudo systemctl enable --now docker

Fedora/RHEL:

sudo dnf install docker docker-compose containerd runc
sudo systemctl enable --now docker

Docker v1/v2 Compatibility

• Currently available docker-compose packages in different linux distributions (debian, ubuntu, fedora, etc) are not up to date, they are still at version 1 which has been deprecated by docker with release of version 2.
• docker-compose version 2 is available through official docker repositories not the distribution ones.
• Docker Compose files in this repository work with version 2 and are also backward compatible with version 1.
• If you are using the distribution installation the docker compose command used below has to be changed to docker-compose instead.

VLS standalone Setup

Below are the steps required to run vlsd2 as a standalone container.

Docker Image

# Build the latest docker image
cd vlsd
docker build -t vlsd .

Volume Creation

docker volume create vls_data

Environment Variables

VLS container needs the follwing environment variables set:

• BITCOIND_RPC_URL: URL of bitcoind's RPC port.
• VLS_NETWORK: testnet or regtest.

Frequently used optional environment variables are:

• VLS_PERMISSIVE
• RUST_LOG

vlsd2 Command Arguments

Required command arguments:

• connect: URL of remote_hsmd_socket running in the lightning node.

For information on all possible arguments to vlsd see documentation.

Running container

There is a docker-compose.yml in the vlsd folder which can be used to run a standalone vlsd service with network_mode set to host.

cd vlsd
export VLS_GIT_HASH=$VLS_GIT_HASH
docker compose up

Note: Make sure to set BITCOIND_RPC_URL, VLS_GIT_HASH and CLN_RMEOTE_HSMD_URL as either environment variables or in the docker-compose.yml file before running the above command. You can take VLS_GIT_HASH from .env or from the main repo

If you wish to run it as a standalone container without using docker-compose you can use the following command:

docker run \
  -d \
  --rm \
  --name vlsd \
  --network host \
  --build_arg VLS_GIT_HASH=$VLS_GIT_HASH
  -e VLS_NETWORK=testnet \
  -e BITCOIND_RPC_URL=$BITCOIND_RPC_URL \
  --mount 'type=volume,src=vls_data,dst=/home/vls/.lightning-signer' \
  vlsd \
  --connect=$CLN_REMOTE_HSMD_URL

Single Node Setup

You can run bitcoind, lightningd, txood and vlsd on a single node using available docker compose file in the main directory.

Note: Use this only for experimentation and testing purposes as running vlsd on the same machine as CLN is not as secure as running it on dedicated hardware.

Volume Creation

Testnet:

docker volume create bitcoin_data
docker volume create lightning_data
docker volume create txoo_data
docker volume create vls_data

The regtest docker compose configuration doesn't use external volumes. The automatically created volumes can be destroyed via the down --volumes docker compose command.

Docker Compose Run

docker compose --profile vls up --build

Selecting Bitcoin Chains

We have two possible overrides over the default testnet configuration in docker-compose.yml:

• docker-compose.testnet.yml
• docker-compose.regtest.yml

To use override we have to pass it down both the config using -f flag:

export DOCKER_COMPOSE_OVERRIDE=docker-compose.testnet.yml
export COMPOSE_PROJECT_NAME=testnet
docker compose --profile vls -f docker-compose.yml -f $DOCKER_COMPOSE_OVERRIDE up --build

Note: Even while using testnet running using the override is recommended as that will expose the P2P port for bitcoind and P2P port for lightningd on the host.

Single Node without VLS

To run a single node without vls service we can use the same docker-compose.yml file in the main directory by just removing the profile flag vls from all commands.

docker compose -f docker-compose.yml -f $DOCKER_COMPOSE_OVERRIDE up --build

Above command will run bitcoind, lightningd and txood services on a single node.

Interacting with Containers

We can use the docker container exec <CONTAINER_NAME> <COMMAND> command to interact with containers and interact with setup using command line tools like bitcoin-cli, lightning-cli, vls-cli, etc.

Regtest Commands

Generate Address for node:

docker container exec bitcoind-regtest bitcoin-cli getnewaddress

Generate Blocks

docker container exec bitcoind-regtest bitcoin-cli generatetoaddress 50 $NODE_ADDRESS

Testnet CLN + CLBOSS Commands

# Create a connection to a random node (maybe from 1ML.com)
docker container exec lightningd-test lightning-cli --testnet connect \
  02ae1e6091d2a9c4db5096558668d2456b1c0e9067cb72273eab1199bcfb208888 67.227.190.47:9735

# Allocate an onchain address to fund the node
docker container exec lightningd-test lightning-cli --testnet newaddr

# List onchain and channel funds
docker container exec lightningd-test lightning-cli --testnet listfunds

# Show CLBOSS status
docker container exec lightningd-test lightning-cli --testnet clboss-status | less

# Show node summary status
docker container exec lightningd-test lightning-cli --testnet summary

Debugging Containers

Checking running status and health of containers

docker ps

Getting logs from container

# CONTAINER_NAME=lightningd-test
docker container logs $CONTAINER_NAME > $CONTAINER_NAME.log

Restarting containers

cd vls-container
docker compose --profile vls stop
# to start testnet
docker compose --profile vls up

Generating Backtrace from CLN core dump

# attach to the lightningd container
docker container exec -u root -it lightningd-test sh

# install gdb
apk add gdb
gdb /usr/libexec/c-lightning/plugins/pay /home/lightning/.lightning/testnet/core

# get backtrace
bt

Delete containers

cd vls-container
docker compose --profile vls down

NOTE: If you want to start fresh make sure to delete the created docker volumes as well.

Choosing Versions

The currently set default versions for services is as follows in the .env file:

• Bitcoin Core: v26.0
• Core Lightning: v24.02.2
• TXOO: v0.6.4
• VLS: v0.11.0

You just can switch to a particular version/commit for a service by updating the git hash and then rebuilding the service:

cd vls-container
# update bitcoin core version
sed -i 's/23.0/23.2/g' .env
# build images again
docker compose --profile vls build

Note: For bitcoind its also important to update the BITCOIN_SHA256SUMS_HASH. It is the SHA256 HASH of SHA256SUMS file.

Future Work

• standalone dockerfile for vlsd
• docker compose for vls
• standalone docker image for txood
• standalone docker image for lightningd
• standalone docker image for bitcoind
• supporting signet
• Profile configuration to run vls
• Healthcheck for txoo
• Healthcheck for vls
• Lightning Storage Server Dockerfile and Compose Service
• Postgres Service for Lightning Storage Server

References

• bitcoind by @ruimarinho
• lightningd with clboss by @tsjk
• elements lightning by @ElementsProject
• docker compose by @LukasBahrenberg