Add instructions

stack-orchestrator/compose/docker-compose-bsc-node.yml

@@ -9,16 +9,16 @@ services:
       CERC_GETH_GCMODE: ${CERC_GETH_GCMODE:-full}
       CERC_GETH_VERBOSITY: ${CERC_GETH_VERBOSITY:-3}
     volumes:
-      - ../config/docker-entrypoint.sh:/bsc/docker-entrypoint.sh
+      - ../config/bsc-node/docker-entrypoint.sh:/bsc/docker-entrypoint.sh
       - data:/data
       - bsc:/bsc
       - snapshot:/var/tmp/snapshot
     ports:
-      - 30303:30303
+      - "30303"
-      - 30311:30311
+      - "30311"
-      - 6060:6060
+      - "6060"
-      - 8545:8545
+      - "8545"
-      - 8546:8546
+      - "8546"
     healthcheck:
       test: ["CMD", "nc", "-vz", "localhost", "8545"]
       interval: 5s

stack-orchestrator/config/bsc-node/docker-entrypoint.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+
 set -e
 
 echo "Setting up BSC $CERC_BSC_NETWORK"
@@ -15,13 +16,14 @@ else
   echo "Config file not found at $BSC_CONFIG, downloading config for $CERC_BSC_NETWORK..."
 
   # Download and unzip the config files
-  wget -O config.zip $(curl -s https://api.github.com/repos/bnb-chain/bsc/releases/latest |grep browser_ |grep $CERC_BSC_NETWORK |cut -d\" -f4)
+  wget -O config.zip $(curl -s https://api.github.com/repos/bnb-chain/bsc/releases/latest | grep browser_ | grep $CERC_BSC_NETWORK | cut -d\" -f4)
   unzip config.zip -d config
 fi
 
 # Use snapshot if provided
-geth_dir=${DATA_DIR}/geth
+# Take first file with extension .tar.lz4 from the snapshot dir
 snapshot_file=$((ls /var/dev/snapshot/*.tar.lz4) 2>/dev/null | head -1)
+geth_dir=${DATA_DIR}/geth
 ADDITIONAL_FLAGS=""
 if [ ! -d "$geth_dir" ] && [ "${CERC_USE_SNAPSHOT}" = "true" ] && [ -n "$snapshot_file" ]; then
   echo "Using snapshot $snapshot_file"
@@ -37,7 +39,7 @@ if [ ! -d "$geth_dir" ] && [ "${CERC_USE_SNAPSHOT}" = "true" ] && [ -n "$snapsho
     echo "Pruning trie data and turning snapshot verification off"
 
     # Prune all trie data from the snapshot
-    geth snapshot insecure-prune-all --datadir ${DATA_DIR}  ${BSC_GENESIS}
+    geth snapshot insecure-prune-all --datadir ${DATA_DIR} ${BSC_GENESIS}
 
     # Turn off snapshot verification
     ADDITIONAL_FLAGS="--tries-verify-mode none"

stack-orchestrator/stacks/bsc-node/README.md

@@ -2,8 +2,130 @@
 
 Instructions for running a BSC node
 
-## Prerequisite
+## Setup
 
-Downloaded chain snapshot
+* (Optional) Download the snapshot for BSC network (mainetn | testnet) by following instructions from <https://github.com/bnb-chain/bsc-snapshots>
 
-<!-- TODO -->
+* Clone the stack repo:
+
+  ```bash
+  laconic-so fetch-stack git.vdb.to/cerc-io/bsc-stack
+  ```
+
+* Build the container images:
+
+  ```bash
+  laconic-so --stack ~/cerc/bsc-stack/stack-orchestrator/stacks/bsc-node build-containers
+  ```
+
+## Create a deployment
+
+* Create a spec file for the deployment:
+
+  ```bash
+  laconic-so --stack ~/cerc/bsc-stack/stack-orchestrator/stacks/bsc-node deploy init --map-ports-to-host any-same --output bsc-node-spec.yml
+  ```
+
+* Edit `network` in the spec file to map container ports to host ports as required
+
+* Create a deployment directory from the spec file:
+
+  ```bash
+  laconic-so --stack ~/cerc/bsc-stack/stack-orchestrator/stacks/bsc-node deploy create --spec-file bsc-node-spec.yml --deployment-dir bsc-node-deployment
+  ```
+
+* (Optional) Copy over the snapshot file (`*.tar.lz4`) in snapshot data directory in the deployment (`bsc-node-deployment/data/snapshot`):
+
+  ```bash
+  # Example
+  cp geth-pbss-pebble-20240514.tar.lz4 bsc-node-deployment/data/snapshot/
+  ```
+
+## Configuration
+
+* Environment variables for Lotus node can be configured by setting them in `config.env` inside deployment directory:
+
+  ```bash
+  # All optional
+  # Runs a full node syncing from genesis if none are set
+
+  # BSC network to run (mainnet | testnet) (default: mainnet)
+  CERC_BSC_NETWORK=
+
+  # Whether to sync from a snapshot (true | false) (default: false)
+  # Requires snapshot file with extension .tar.lz4 to be placed in the snapshot directory
+  CERC_USE_SNAPSHOT=
+
+  # Whether to run as a fast node (true | false) (default: false)
+  # Fast node does not generate trie data when syncing
+  CERC_FAST_NODE=
+
+  # Garbage collection mode (full | archive) (default: archive)
+  # Set to archive for archive node
+  CERC_GETH_GCMODE=
+
+  # Logging verbosity (default: 3)
+  # 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail
+  CERC_GETH_VERBOSITY=
+  ```
+
+## Start the deployment
+
+```bash
+laconic-so deployment --dir bsc-node-deployment up
+```
+
+## Check status
+
+* To list down and monitor the running containers:
+
+  ```bash
+  # With status
+  docker ps -a
+
+  # Check logs for a container
+  docker logs -f <CONTAINER_ID>
+  ```
+
+* Log in with bash into the bsc container:
+
+  ```bash
+  docker exec -it <BSC_CONTAINER_ID> bash
+  ```
+
+* Check Synchronization:
+
+  ```bash
+  # Inside the bsc container
+
+  # Start geth console
+  geth attach ipc:node/geth.ipc
+
+  >eth.syncing
+  ```
+
+* Check geth logs:
+
+  ```bash
+  # Inside the bsc container
+  tail -f /data/bsc.log
+  ```
+
+## Clean up
+
+* Stop all services running in the background:
+
+  ```bash
+  # Stop the docker containers
+  laconic-so deployment --dir bsc-node-deployment down
+  ```
+
+* To stop all services and also delete data:
+
+  ```bash
+  # Stop the docker containers
+  laconic-so deployment --dir bsc-node-deployment down --delete-volumes
+
+  # Remove deployment directory (deployment will have to be recreated for a re-run)
+  rm -r bsc-node-deployment
+  ```