Feat/isolate nodes per container

[IsaacTai13]

Summary by CodeRabbit

Release Notes

• New Features

  • Added cluster management commands (cluster-up, cluster-down, cluster-logs, cluster-clean, cluster-restart) for simplified local BSC cluster operations
  • Implemented Docker-based container orchestration for validator network setup

• Documentation

  • Redesigned setup documentation with architecture workflow diagrams
  • Updated node access guidance with new port mapping tables and logging examples
  • Enhanced cluster initialization and configuration instructions

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This pull request introduces a complete Docker-based orchestration system for managing a local BSC validator cluster. It adds a Makefile with lifecycle management targets (cluster-up, cluster-down, cluster-logs, cluster-clean, cluster-restart), a comprehensive docker_cluster.sh orchestration script that handles initialization (validator key setup, geth compilation, genesis generation, geth initialization, config patching, docker-compose generation, and validator registration), a node_entrypoint.sh container startup script that configures and launches geth nodes with appropriate flags per node type, updates to bsc_cluster.sh with minor clarifications and cache configuration, and revised README documentation replacing manual toolbox workflows with make-based cluster management.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Make as Makefile<br/>(make cluster-up)
    participant Toolbox as Toolbox Container<br/>(docker_cluster.sh)
    participant Genesis as Genesis Module<br/>(prep & build)
    participant Geth as Geth Binary<br/>(compile/copy)
    participant Compose as Docker Compose<br/>(generate & start)
    participant Nodes as Node Services<br/>(validators/sentries)

    User->>Make: make cluster-up
    Make->>Toolbox: run docker_cluster.sh prepare
    
    Toolbox->>Geth: clone/build BSC geth (if needed)
    Geth-->>Toolbox: geth binary
    
    Toolbox->>Genesis: reset to compatible commit
    Genesis->>Genesis: install dependencies (poetry/npm)
    Genesis-->>Toolbox: prepared genesis module
    
    Toolbox->>Toolbox: extract validator addresses from keystores
    Toolbox->>Toolbox: generate validators.conf & genesis.json
    Toolbox->>Toolbox: initialize geth datadirs (geth init)
    Toolbox->>Toolbox: patch config.toml files
    
    Toolbox->>Compose: generate docker-compose.cluster.yml
    Compose-->>Toolbox: compose file ready
    
    Toolbox-->>Make: prepare phase complete
    Make->>Compose: docker compose up -d
    Compose->>Nodes: start validator/sentry/fullnode services
    Nodes-->>Compose: services running
    
    Compose-->>User: cluster operational

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

The changes introduce substantial new infrastructure (~500 lines across five files) with heterogeneous components: orchestration logic (docker_cluster.sh, node_entrypoint.sh), build system integration (Makefile), and documentation. The docker_cluster.sh script presents significant logic density including keystore parsing, geth binary handling, genesis module reset with artifact preservation, config patching via sed, docker-compose YAML generation with dynamic service definitions, and StakeHub validator registration. The node_entrypoint.sh script handles environment variable validation, consensus address derivation, and complex geth flag construction. The integration across multiple layers—build system, container orchestration, node initialization—requires careful verification of correctness and concurrency safety.

Possibly related PRs

• Add Dockerfile and environment setup for BSC cluster #1 — Adds Docker-based cluster tooling touching the same core files (README.md, bsc_cluster.sh, container entrypoint), indicating overlapping cluster infrastructure changes.
• Feat/storage optimized and metrics access #2 — Modifies cluster orchestration surfaces, README monitoring/metrics documentation, and bsc_cluster.sh/docker-compose logic for unified state/database scheme and metrics/pprof exposure.

🚥 Pre-merge checks | ✅ 5 | ❌ 3

❌ Failed checks (3 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title does not follow the required format: it lacks the parentheses around domain/pkg and uses a slash instead of proper structure.	Reformat the title to match the required pattern: 'feat(docker): isolate nodes per container' or similar, ensuring it starts with type(domain): and stays under 72 characters.
Concurrency Safety	⚠️ Warning	PR contains critical concurrency issues: time.Ticker instances created without Stop() calls cause goroutine leaks in txblob/main.go and txbot/main.go; context.Background() used for RPC operations without timeouts violates best practices.	Call defer t.Stop() after ticker creation; add context.WithTimeout() for all RPC calls with 30s timeout; implement graceful shutdown with context cancellation for infinite loops.
Security Considerations	⚠️ Warning	Pull request contains multiple critical security vulnerabilities including command injection risks, unvalidated input handling, sed pattern injection, path traversal risks, and insecure network exposure.	Quote variables in Makefile, add set -o pipefail and variable validation in shell scripts, escape sed patterns safely, validate sourced environment variables, and restrict network bindings to 127.0.0.1 with specific CORS domains.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 85.71% which is sufficient. The required threshold is 80.00%.
Go Build And Test Rationale	✅ Passed	The PR modifies only shell scripts and documentation, not Go source code. No Go package logic changes require test coverage verification.
Public Api Changes	✅ Passed	PR introduces only new Makefile targets and scripts without modifying existing exported APIs or functions.
Rust Best Practices	✅ Passed	The custom check for Rust best practices is not applicable to this pull request. The PR consists entirely of modifications to Bash shell scripts (bsc_cluster.sh, docker_cluster.sh, node_entrypoint.sh), a Makefile, and README documentation. The repository contains a Go program in create-validator/main.go, but that file is not modified by this PR. Since no Rust code (.rs files) is present in the modified files, the Rust-specific guidelines are not applicable.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/isolate-nodes-per-container

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}