From 3de4e116c960dd6994fa123f5fb1625ae01caced Mon Sep 17 00:00:00 2001 From: Lakshya Singh Date: Sun, 12 Nov 2023 21:59:32 +0530 Subject: [PATCH] readme: vls and compose setup - for running standalone vls - fix heading size and grammar - improve description - add command highlighting Signed-off-by: Lakshya Singh --- README.md | 114 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 94 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 5e778de..350cc91 100644 --- a/README.md +++ b/README.md @@ -23,71 +23,135 @@ sudo dnf install docker docker-compose containerd runc sudo systemctl enable --now docker ``` -### Docker Compose Compatibility +### Docker v1/v2 Compatibility -- Currently available `docker-compose` package 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`. +- 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 Images in this repository work with version 2 and are also __backward compatible__ with version 1. +- 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. -## VLSD Image +## VLS standalone Setup -``` +Below are the steps required to run `vlsd2` as a standalone container. + +### Docker Image + +```bash +# Pull the latest release image for vlsd +docker pull registry.gitlab.com/lightning-signer/vls-container/vlsd:latest +docker tag registry.gitlab.com/lightning-signer/vls-container/vlsd:latest vlsd:latest +# Build the latest docker image cd vlsd docker build -t vlsd . ``` -## Volume Creation +### Volume Creation +```bash +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](https://gitlab.com/lightning-signer/validating-lightning-signer/-/blob/main/vls-proxy/src/config.rs?ref_type=heads). + +### 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. + +```bash +cd vlsd +docker compose up +``` + +**_Note_**: Make sure to set `BITCOIND_RPC_URL` and `CLN_RMEOTE_HSMD_URL` as either environment variables or in the `docker-compose.yml` file before running the above command. + +If you wish to run it as a standalone container without using `docker-compose` you can use the following command: + +```bash +docker run \ + -d \ + --rm \ + --name vlsd \ + --network host \ + -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 + +```bash docker volume create bitcoin_data docker volume create lightning_data docker volume create txoo_data docker volume create vls_data ``` -## Docker Compose Run +### Docker Compose Run -``` +```bash docker compose up --build ``` -## Using Bitcoin Chains +### Selecting Bitcoin Chains -We have three possible overrides over the default `testnet` configuration in `docker-compose.yml`: +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 COMPOSE_PROJECT_NAME= -docker compose -f docker-compose.yml -f up --build +```bash +export DOCKER_COMPOSE_OVERRIDE=docker-compose.testnet.yml +export COMPOSE_PROJECT_NAME=testnet +docker compose -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. -## Additional Regtest Commands +### Additional Regtest Commands We have to run these commands after bitcoind is up and running. Create Wallet: -``` +```bash docker container exec bitcoind-regtest bitcoin-cli createwallet default ``` Generate Address for node: -``` +```bash docker container exec bitcoind-regtest bitcoin-cli getnewaddress ``` Generate Blocks -``` +```bash docker container exec bitcoind-regtest bitcoin-cli generatetoaddress 50 $NODE_ADDRESS ``` -## Testnet CLN + CLBOSS Commands +### Testnet CLN + CLBOSS Commands -``` +```bash # 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 @@ -105,7 +169,17 @@ docker container exec lightningd-test lightning-cli --testnet clboss-status | le docker container exec lightningd-test lightning-cli --testnet summary ``` -### References +## Future Work + +- [x] standalone dockerfile for vlsd +- [x] docker compose for vls +- [ ] standalone docker image for `lightning-storage-server` +- [ ] standalone docker image for `txood` +- [ ] standalone docker image for `lightningd` +- [ ] standalone docker image for `bitcoind` +- [ ] supporting signet + +## References - [bitcoind](https://github.com/ruimarinho/docker-bitcoin-core/blob/master/23/alpine/Dockerfile) by @ruimarinho - [lightningd with clboss](https://github.com/tsjk/docker-core-lightning/blob/main/Dockerfile) by @tsjk