readme: vls and compose setup

- for running standalone vls
- fix heading size and grammar
- improve description
- add command highlighting

Signed-off-by: Lakshya Singh <lakshay.singh1108@gmail.com>
This commit is contained in:
Lakshya Singh 2023-11-12 21:59:32 +05:30
parent bac309d758
commit 3de4e116c9
No known key found for this signature in database
GPG Key ID: D3239BA6109A2CE7

114
README.md
View File

@ -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=<bitcoin_chain>
docker compose -f docker-compose.yml -f <override_file> 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