Advanced Solo Setup

• 1: Using Environment Variables
• 2: Network Deployments
• 2.1: One-shot Falcon Deployment
• 2.2: Falcon Values File Reference
• 2.3: Step-by-Step Manual Deployment
• 2.4: Custom Application Properties
• 2.5: Dynamically add, update, and remove Consensus Nodes
• 3: Attach JVM Debugger and Retrieve Logs
• 4: One-Shot Deploy with Custom Component Versions
• 5: Customizing Solo with Tasks
• 6: Solo CI Workflow
• 7: One-Shot Deploy on a GitHub-hosted Runner
• 8: Run Performance Tests Locally
• 9: CLI Reference
• 9.1: Solo CLI Reference
• 9.2: CLI Migration Reference
• 10: Solo Image Cache

1 - Using Environment Variables

Overview

Solo supports a set of environment variables that let you customize its behaviour without modifying command-line flags on every run. Variables set in your shell environment take effect automatically for all subsequent Solo commands.

Setting environment variables

How you set a variable depends on your shell. Use the tab for your platform:

• Bash / Zsh
• PowerShell

# For a single command only
CONSENSUS_NODE_VERSION=v0.73.0 solo one-shot single deploy

# For the current session
export CONSENSUS_NODE_VERSION=v0.73.0

# Persist across sessions (add to ~/.bashrc or ~/.zshrc)
echo 'export CONSENSUS_NODE_VERSION=v0.73.0' >> ~/.zshrc

# For the current session
$env:CONSENSUS_NODE_VERSION = 'v0.73.0'

# Persist for your user (all future sessions)
[System.Environment]::SetEnvironmentVariable('CONSENSUS_NODE_VERSION', 'v0.73.0', 'User')

# Or add it to your PowerShell profile
Add-Content $PROFILE '$env:CONSENSUS_NODE_VERSION = "v0.73.0"'

Tip: Variables set in your shell environment (or persisted as shown above) take effect automatically for all subsequent Solo commands.

General

Network and Node Identity

Operator and Key Configuration

Note: Full key values are omitted above for readability. Refer to the source defaults for complete key strings.

Node Client Behaviour

Pod and Network Readiness

Block Node

Relay Node

Mirror Node

Load Balancer

Lease Management

Component Versions

Tip: To pin component versions for a solo one-shot single deploy, prefix the command with these variables. See the One-Shot Deployment section below for an example.

Edge Component Versions

These variables only take effect when solo one-shot single deploy or solo one-shot multi deploy is invoked with the --edge flag (solo one-shot falcon deploy does not accept --edge in v0.72.0). They let you point a one-shot deploy at arbitrary component tags — release candidates, pre-releases, or any other tag the component’s registry exposes — without rebuilding Solo.

Set only the variables for components you want to override; the rest use their compiled-in edge defaults. Without --edge, every *_EDGE_VERSION variable is ignored.

For full usage, examples, version-format rules, and troubleshooting, see One-Shot Deploy with Custom Component Versions.

Helm Chart URLs

Network Load Generator

One-Shot Deployment

Pinning Component Versions

solo one-shot single deploy does not yet expose CLI flags for pinning individual component versions. To run a one-shot deployment against specific releases, prefix the command with the Component Versions environment variables:

CONSENSUS_NODE_VERSION=v0.73.0 MIRROR_NODE_VERSION=v0.153.1 solo one-shot single deploy

Any of the *_VERSION variables listed in Component Versions can be combined in the same command to pin multiple components at once.

Note:

• This is the current recommended approach for version pinning in one-shot deployments.
• CLI flags for version overrides on one-shot are planned for Q2 — tracked in hiero-ledger/solo#4242.
• Environment variables will remain valid for one-off overrides after the CLI flags land, so the form above will continue to work.

Image Cache

Solo caches the container images it deploys as local archives to speed up repeat deployments. The cache is enabled by default; these variables disable it per context. See Solo Image Cache for the full feature and the solo cache image commands.

Note: The cached component versions follow the same environment-variable mechanism as Pinning Component Versions above - the *_VERSION environment variables affect the images the cache pulls, but the --*-version CLI flags do not.

2 - Network Deployments

2.1 - One-shot Falcon Deployment

Overview

One-shot Falcon deployment is Solo’s YAML-driven one-shot workflow. It uses the same core deployment pipeline as solo one-shot single deploy, but lets you inject component-specific flags through a single values file.

Use One-shot Falcon deployment when you need a repeatable advanced setup, want to check a complete deployment into source control, or need to customise component flags without running every Solo command manually.

Falcon is especially useful for:

• CI/CD pipelines and automated test environments.
• Reproducible local developer setups.
• Advanced deployments that need custom chart paths, image versions, ingress, storage, TLS, or node startup options.

Important: Falcon is an orchestration layer over Solo’s standard commands. It does not introduce a separate deployment model. Solo still creates a deployment, attaches clusters, deploys the network, configures nodes, and then adds optional components such as mirror node, explorer, and relay.

Prerequisites

Before proceeding, ensure you have completed the following:

• System Readiness - your local environment meets the hardware and software requirements for Solo, Kubernetes, Docker, Kind, kubectl, and Helm.
• Quickstart -you are already familiar with the standard one-shot deployment workflow.

How Falcon Works

When you run Falcon deployment, Solo executes the same end-to-end deployment sequence used by its one-shot workflows:

1. Connect to the Kubernetes cluster.
2. Create a deployment and attach the cluster reference.
3. Set up shared cluster components.
4. Generate gossip and TLS keys.
5. Deploy the consensus network and, if enabled, the block node (in parallel).
6. Set up and start consensus nodes.
7. Optionally, deploy mirror node, explorer, and relay in parallel for faster startup.
8. Create predefined test accounts.
9. Write deployment notes, versions, port-forward details, and account data to a local output directory.

The difference is that Falcon reads a YAML file and maps its top-level sections to the underlying Solo subcommands.

For the full list of supported CLI flags per section, see the Falcon Values File Reference. If you set network.--application-properties, see Custom Application Properties for the difference between Solo’s default merge mode and full overwrite mode.

Prepare a Falcon values file

Instead of authoring a values file by hand, you can use the interactive prepare wizard to generate one:

solo one-shot falcon prepare

The wizard prompts for component toggles (mirror node, explorer, relay), consensus node count, component versions, ingress, storage type, developer options, and port forwarding. All prompts have sensible defaults, so you can press Enter to accept them.

To generate a values file with all defaults (no prompts):

solo one-shot falcon prepare --quiet-mode

To specify a custom output path:

solo one-shot falcon prepare --output-values-file ./my-values.yaml

Output file location

By default, the generated file is written to ~/.solo/cache/falcon-values.yaml — a deterministic absolute path regardless of how or where Solo is invoked. You can override this with --output-values-file. The success message always prints the fully resolved path so there is no ambiguity.

• Default: ~/.solo/cache/falcon-values.yaml — always the same location.
• Relative path: --output-values-file ./configs/my-values.yaml — resolved against the current working directory (so /tmp/configs/my-values.yaml if invoked from /tmp).
• Absolute path: --output-values-file /tmp/falcon-values.yaml — written to that exact location regardless of the current working directory.

The generated file is ready to use with solo one-shot falcon deploy --values-file. For the full list of flags the wizard sets, see the Falcon Values File Reference.

Create a Falcon Values File

Create a YAML file to control every component of your Solo deployment. The file can have any name -falcon-values.yaml is used throughout this guide as a convention.

Note: Keys within each section must be the full CLI flag name including the -- prefix - for example, --release-tag, not release-tag or -r. Any section you omit from the file is skipped, and Solo uses the built-in defaults for that component.

Example: Single-Node Falcon Deployment

The following falcon-values.yaml example deploys a standard single-node network with mirror node, explorer, and relay enabled:

network:
  --release-tag: "v0.71.0"
  --pvcs: false

setup:
  --release-tag: "v0.71.0"

consensusNode:
  --force-port-forward: true

mirrorNode:
  --enable-ingress: true
  --pinger: true
  --force-port-forward: true

explorerNode:
  --enable-ingress: true
  --force-port-forward: true

relayNode:
  --node-aliases: "node1"
  --force-port-forward: true

Deploy with Falcon one-shot

Run Falcon deployment by pointing Solo at the values file:

solo one-shot falcon deploy --values-file falcon-values.yaml

Solo creates a one-shot deployment, applies the values from the YAML file to the appropriate subcommands, and then deploys the full environment.

Command-Line Flags (Not in YAML File)

The following flags are passed on the command line and cannot be set in the YAML file:

• --deployment, --namespace, --cluster-ref, --num-consensus-nodes

Note: --values-file specifies which YAML file to load.

• --values-file selects the YAML file to load.
• --deployment, --namespace, --cluster-ref, and --num-consensus-nodes are top-level one-shot inputs.

Important: Do not rely on --deployment inside falcon-values.yaml. Solo intentionally ignores --deployment values from section content during Falcon argument expansion. Set the deployment name on the command line if you need a specific name.

Tip: When not specified, Falcon uses these defaults: --deployment one-shot, --namespace one-shot, --cluster-ref one-shot, and --num-consensus-nodes 1. Pass any of these explicitly on the command line to override them.

Example:

solo one-shot falcon deploy \
  --deployment falcon-demo \
  --cluster-ref one-shot \
  --values-file falcon-values.yaml

Multi-Node Falcon Deployment

For multiple consensus nodes, set the node count on the Falcon command and then provide matching per-node settings where required.

• Example:

  solo one-shot falcon deploy \
    --deployment falcon-multi \
    --num-consensus-nodes 3 \
    --values-file falcon-values.yaml
  

• Example multi-node values file:

  network:
    --release-tag: "v0.71.0"
    --pvcs: true
  
  setup:
    --release-tag: "v0.71.0"
  
  consensusNode:
    --force-port-forward: true
    --stake-amounts: "100,100,100"
  
  mirrorNode:
    --enable-ingress: true
    --pinger: true
  
  explorerNode:
    --enable-ingress: true
  
  relayNode:
    --node-aliases: "node1,node2,node3"
  

• The --node-aliases value in the relayNode section must match the node aliases generated by --num-consensus-nodes. Nodes are auto-named node1, node2, node3, and so on. Setting this to only node1 is valid if you want the relay to serve a single node, but specifying all aliases is typical for full coverage.

• Use this pattern when you need a repeatable multi-node deployment but do not want to manage each step manually.

Note: Multi-node deployments require more host resources than single-node deployments. Follow the resource guidance in System Readiness, and increase Docker memory and CPU allocation before deploying.

Common Falcon Customisations

Because each YAML section maps directly to the corresponding Solo subcommand, you can use Falcon to centralise advanced options such as:

• Custom release tags for the consensus node platform.
• Local chart directories for mirror node, relay, explorer, or block node.
• Local consensus node build paths for development workflows.
• Ingress and domain settings.
• Mirror node external database settings.
• Node startup settings such as state files, port forwarding, and stake amounts.
• Storage backends and credentials for stream file handling.

Example: Local Development with Local Chart Directories

setup:
  --local-build-path: "/path/to/hiero-consensus-node/hedera-node/data"

mirrorNode:
  --mirror-node-chart-dir: "/path/to/hiero-mirror-node/charts"

relayNode:
  --relay-chart-dir: "/path/to/hiero-json-rpc-relay/charts"

explorerNode:
  --explorer-chart-dir: "/path/to/hiero-mirror-node-explorer/charts"

This pattern is useful for local integration testing against unpublished component builds. For a step-by-step walkthrough of the local build workflow, see Deploying a Local Consensus Node Build.

Falcon with Block Node

Falcon can also include block node configuration.

Note: Block node workflows are advanced and require higher resource allocation and version compatibility across consensus node, block node, and related components. Docker memory must be set to at least 16 GB before deploying with block node enabled.

Block node support also requires the ONE_SHOT_WITH_BLOCK_NODE=true environment variable to be set before running falcon deploy. Without it, Solo skips the block node add step even if a blockNode section is present in the values file.

Block node deployment is subject to version compatibility requirements. Minimum versions are consensus node ≥ v0.72.0 and block node ≥ 0.29.0. Mixing incompatible versions will cause the deployment to fail. Check the Version Compatibility Reference before enabling block node.

Example:

network:
  --release-tag: "v0.72.0"

setup:
  --release-tag: "v0.72.0"

consensusNode:
  --force-port-forward: true

blockNode:
  --release-tag: "v0.29.0"
  --enable-ingress: false

mirrorNode:
  --enable-ingress: true
  --pinger: true

explorerNode:
  --enable-ingress: true

relayNode:
  --node-aliases: "node1"
  --force-port-forward: true

Use block node settings only when your target Solo and component versions are known to be compatible.

Deployment Output

After a successful Falcon deployment, Solo writes deployment metadata to ~/.solo/one-shot-<deployment>/ where <deployment> is the value of the --deployment flag (default: one-shot).

This directory typically contains:

• notes - human-readable deployment summary
• versions - component versions recorded at deploy time
• forwards - port-forward configuration
• accounts.json - predefined test account keys and IDs. All accounts are ECDSA Alias accounts (EVM-compatible) and include a publicAddress field. The file also includes the system operator account.

This makes Falcon especially useful for automation, because the deployment artifacts are written to a predictable path after each run.

To inspect deployment output, check the ~/.solo/one-shot-<deployment>/ directory directly.

If port-forwards are interrupted after deployment, restore them by rerunning the component commands (such as solo consensus node start, solo mirror node add, etc.)

Destroy a Falcon Deployment

• Destroy the Falcon deployment with:

  solo one-shot falcon destroy
  

• Solo removes deployed extensions first, then destroys the mirror node, network, cluster references, and local deployment metadata.

• If multiple deployments exist locally, Solo prompts you to choose which one to destroy unless you pass --deployment explicitly.

  solo one-shot falcon destroy --deployment falcon-demo
  

When to Use Falcon vs. Manual Deployment

Use Falcon deployment when you want a single, repeatable command backed by a versioned YAML file.

Use Step-by-Step Manual Deployment when you need to pause between steps, inspect intermediate state, or debug a specific deployment phase in isolation.

In practice:

• Falcon is better for automation and repeatability.
• Manual deployment is better for debugging and low-level control.

Reference

• Falcon Values File Reference - full list of supported CLI flags, types, and defaults for every section.
• Upstream example values file - working reference from the Solo repository.

Tip: If you are creating a values file for the first time, start from the annotated template in the Solo repository rather than writing one from scratch:

examples/one-shot-falcon/falcon-values.yaml

This file includes all supported sections and flags with inline comments explaining each option. Copy it, remove what you do not need, and adjust the values for your environment.

2.2 - Falcon Values File Reference

Overview

This page catalogs the Solo CLI flags accepted under each top-level section of a Falcon values file. Each entry corresponds to the command-line flag that the underlying Solo subcommand accepts.

Sections map to subcommands as follows:

All flag names must be written in long form with double dashes (for example, --release-tag). Flags left empty ("") or matching their default value are ignored by Solo at argument expansion time.

Note: Not every flag listed here is relevant to every deployment. Use this page as a lookup when writing or debugging a values file. For a working example file, see the upstream reference at https://github.com/hiero-ledger/solo/tree/main/examples/one-shot-falcon.

Consensus Network Deploy — network

Flags passed to solo consensus network deploy.

Consensus Node Setup — setup

Flags passed to solo consensus node setup.

Consensus Node Start — consensusNode

Flags passed to solo consensus node start.

Mirror Node Add — mirrorNode

Flags passed to solo mirror node add.

Explorer Add — explorerNode

Flags passed to solo explorer node add.

JSON-RPC Relay Add — relayNode

Flags passed to solo relay node add.

Block Node Add — blockNode

Flags passed to solo block node add.

Important: The blockNode section is only read when ONE_SHOT_WITH_BLOCK_NODE=true is set in the environment. Otherwise Solo skips the block node add step regardless of whether a blockNode section is present. Version requirements: Consensus node ≥ v0.72.0 and block node ≥ 0.29.0. Use --force to bypass version gating during testing.

Top-Level Falcon Command Flags

The following flags are passed directly on the solo one-shot falcon deploy command line. They are not read from the values file sections.

Falcon Prepare — prepare

Flags accepted by solo one-shot falcon prepare, the interactive wizard that generates a Falcon values file. The wizard prompts for nearly every values-file field, but the following CLI flags control its output behavior directly.

All other prepare-time flags correspond directly to the per-section values shown in the tables above and are documented under their respective network, setup, consensusNode, mirrorNode, explorerNode, relayNode, and blockNode sections.

2.3 - Step-by-Step Manual Deployment

Overview

Manual deployment lets you deploy each Solo network component individually, giving you full control over configuration, sequencing, and troubleshooting. Use this approach when you need to customise specific steps, debug a component in isolation, or integrate Solo into a bespoke automation pipeline.

Prerequisites

Before proceeding, ensure you have completed the following:

• System Readiness — your local environment meets all hardware and software requirements (Docker, kind, kubectl, helm, Solo).
• Quickstart — you have a running Kind cluster.
• Set your environment variables if you have not already done so:

• Bash
• PowerShell

export SOLO_CLUSTER_NAME=solo
export SOLO_NAMESPACE=solo-deployment
export SOLO_CLUSTER_SETUP_NAMESPACE=solo-cluster
export SOLO_DEPLOYMENT=solo-deployment

$env:SOLO_CLUSTER_NAME = 'solo'
$env:SOLO_NAMESPACE = 'solo-deployment'
$env:SOLO_CLUSTER_SETUP_NAMESPACE = 'solo-cluster'
$env:SOLO_DEPLOYMENT = 'solo-deployment'

Deployment Steps

Note: The expected output blocks below are fetched from the latest published Solo release at build time and will always reflect the current version.

1. Connect Cluster and Create Deployment

• Connect Solo to the Kind cluster and create a new deployment configuration:

  # Connect to the Kind cluster
  solo cluster-ref config connect \
    --cluster-ref kind-${SOLO_CLUSTER_NAME} \
    --context kind-${SOLO_CLUSTER_NAME}
  
  # Create a new deployment
  solo deployment config create \
    -n "${SOLO_NAMESPACE}" \
    --deployment "${SOLO_DEPLOYMENT}"
  

• Expected Output:

  ******************************* Solo *********************************************
    Version			: 0.80.0
    Kubernetes Context	: kind-solo
    Kubernetes Cluster	: kind-solo
    Current Command		: cluster-ref config connect --cluster-ref kind-solo --context kind-solo
    **********************************************************************************
    ❯ Initialize
    ✔ Initialize 
    ❯ Validating cluster ref: 
    ✔ Validating cluster ref: kind-solo 
    ❯ Test connection to cluster: 
    ✔ Test connection to cluster: kind-solo 
    ❯ Associate a context with a cluster reference: 
    ✔ Associate a context with a cluster reference: kind-solo 

• ******************************* Solo *********************************************
  Version			: 0.80.0
  Kubernetes Context	: kind-solo
  Kubernetes Cluster	: kind-solo
  Current Command		: deployment config create --namespace solo --deployment solo-deployment --realm 0 --shard 0
  Kubernetes Namespace	: solo
  **********************************************************************************
  ❯ Initialize
  ✔ Initialize 
  ❯ Add deployment to local config
  ✔ Adding deployment: solo-deployment with namespace: solo to local config 

2. Add Cluster to Deployment

• Attach the cluster to your deployment and specify the number of consensus nodes:

  1. Single node:

  solo deployment cluster attach \
    --deployment "${SOLO_DEPLOYMENT}" \
    --cluster-ref kind-${SOLO_CLUSTER_NAME} \
    --num-consensus-nodes 1
  

  2. Multiple nodes (e.g., –num-consensus-nodes 3):

  solo deployment cluster attach \
    --deployment "${SOLO_DEPLOYMENT}" \
    --cluster-ref kind-${SOLO_CLUSTER_NAME} \
    --num-consensus-nodes 3
  

• Expected Output:

  ******************************* Solo *********************************************
    Version			: 0.80.0
    Kubernetes Context	: kind-solo
    Kubernetes Cluster	: kind-solo
    Current Command		: deployment cluster attach --deployment solo-deployment --cluster-ref kind-solo --num-consensus-nodes 1
    **********************************************************************************
    ❯ Pre-flight: check Docker Desktop containerd setting
    ✔ Pre-flight: check Docker Desktop containerd setting 
    ❯ Check dependencies
    ❯ Check dependency: helm [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ❯ Check dependency: kind [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ❯ Check dependency: kubectl [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ✔ Check dependency: kind [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependency: helm [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependency: kubectl [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependencies 
    ❯ Setup chart manager
    ✔ Setup chart manager [0.7s]
    ❯ Initialize
    ✔ Initialize 
    ❯ Verify args
    ✔ Verify args 
    ❯ check ledger phase
    ✔ check ledger phase 
    ❯ Test cluster reference connection
    ✔ Test cluster reference connection: kind-solo, context: kind-solo 
    ❯ Verify prerequisites
    ✔ Verify prerequisites 
    ❯ Check for other deployments
    ✔ Check for other deployments 
    ❯ add cluster-ref in local config deployments
    Adding cluster-ref: kind-solo for deployment: solo-deployment in local config
    ✔ add cluster-ref: kind-solo for deployment: solo-deployment in local config 
    ❯ create remote config for deployment
    ✔ create remote config for deployment: solo-deployment in cluster reference: kind-solo 

3. Generate Keys

• Generate the gossip and TLS keys for your consensus nodes:

  solo keys consensus generate \
    --gossip-keys \
    --tls-keys \
    --deployment "${SOLO_DEPLOYMENT}"
  

  PEM key files are written to ~/.solo/cache/keys/.

• Expected output:

  ******************************* Solo *********************************************
    Version			: 0.80.0
    Kubernetes Context	: kind-solo
    Kubernetes Cluster	: kind-solo
    Current Command		: keys consensus generate --gossip-keys --tls-keys --deployment solo-deployment
    **********************************************************************************
    ❯ Initialize
    ✔ Initialize 
    ❯ Generate gossip keys
    ❯ Backup old files
    ✔ Backup old files 
    ❯ Gossip key for node: node1
    ✔ Gossip key for node: node1 [0.2s]
    ✔ Generate gossip keys [0.2s]
    ❯ Generate gRPC TLS Keys
    ❯ Backup old files
    ❯ TLS key for node: node1
    ✔ Backup old files 
    ✔ TLS key for node: node1 [0.2s]
    ✔ Generate gRPC TLS Keys [0.2s]
    ❯ Finalize
    ✔ Finalize 

4. Set Up Cluster with Shared Components

• Install shared cluster-level components (MinIO Operator, Prometheus CRDs, etc.) into the cluster setup namespace:

  solo cluster-ref config setup --cluster-setup-namespace "${SOLO_CLUSTER_SETUP_NAMESPACE}"
  

• Expected output:

  ******************************* Solo *********************************************
    Version			: 0.80.0
    Kubernetes Context	: kind-solo
    Kubernetes Cluster	: kind-solo
    Current Command		: cluster-ref config setup --cluster-setup-namespace solo-cluster
    **********************************************************************************
    ❯ Pre-flight: check Docker Desktop containerd setting
    ✔ Pre-flight: check Docker Desktop containerd setting 
    ❯ Check dependencies
    ❯ Check dependency: helm [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ❯ Check dependency: kind [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ❯ Check dependency: kubectl [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ✔ Check dependency: kind [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependency: helm [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependency: kubectl [OS: linux, Release: 6.8.0-117-generic, Arch: x64] [0.1s]
    ✔ Check dependencies [0.1s]
    ❯ Setup chart manager
    ✔ Setup chart manager [0.7s]
    ❯ Initialize
    ✔ Initialize 
    ❯ Install cluster charts
    ❯ Install pod-monitor-role ClusterRole
    ✅ ClusterRole pod-monitor-role installed successfully in context kind-solo
    ✔ Install pod-monitor-role ClusterRole 
    ❯ Install MinIO Operator chart
    ✅ MinIO Operator chart installed successfully on context kind-solo
    ✔ Install MinIO Operator chart [0.7s]
    ✔ Install cluster charts [0.7s]

5. Deploy the Network

• Deploy the Solo network Helm chart, which provisions the consensus node pods, HAProxy, Envoy, and MinIO:

  solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}"
  

  To provide a custom consensus node application.properties file, pass --application-properties <path>. Solo merges custom files with its generated defaults unless the file includes the overwrite marker. See Custom Application Properties for merge and overwrite examples.

• Expected output:

  ******************************* Solo *********************************************
    Version			: 0.80.0
    Kubernetes Context	: kind-solo
    Kubernetes Cluster	: kind-solo
    Current Command		: consensus network deploy --deployment solo-deployment --consensus-node-version v0.74.0
    **********************************************************************************
    ❯ Pre-flight: check Docker Desktop containerd setting
    ✔ Pre-flight: check Docker Desktop containerd setting 
    ❯ Check dependencies
    ❯ Check dependency: helm [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ❯ Check dependency: kind [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ❯ Check dependency: kubectl [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ✔ Check dependency: kind [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependency: helm [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependency: kubectl [OS: linux, Release: 6.8.0-117-generic, Arch: x64] [0.1s]
    ✔ Check dependencies [0.1s]
    ❯ Setup chart manager
    ✔ Setup chart manager [0.6s]
    ❯ Initialize
    ❯ Acquire lock
    ✔ Acquire lock - lock acquired successfully, attempt: 1/10 
    ✔ Initialize [0.2s]
    ❯ Copy gRPC TLS Certificates
    ↓ Copy gRPC TLS Certificates [SKIPPED: Copy gRPC TLS Certificates]
    ❯ Prepare staging directory
    ❯ Copy Gossip keys to staging
    ✔ Copy Gossip keys to staging 
    ❯ Copy gRPC TLS keys to staging
    ✔ Copy gRPC TLS keys to staging 
    ✔ Prepare staging directory 
    ❯ Copy node keys to secrets
    ❯ Copy TLS keys
    ❯ Node: node1, cluster: kind-solo
    ❯ Copy Gossip keys
    ✔ Copy TLS keys 
    ✔ Copy Gossip keys 
    ✔ Node: node1, cluster: kind-solo 
    ✔ Copy node keys to secrets 
    ❯ Install monitoring CRDs
    ❯ Pod Logs CRDs
    ❯ Prometheus Operator CRDs
    ✔ Pod Logs CRDs 
     - Installed prometheus-operator-crds chart, version: 24.0.2
    ✔ Prometheus Operator CRDs [4s]
    ✔ Install monitoring CRDs [4s]
    ❯ Install chart 'solo-deployment'
     - Installed solo-deployment chart, version: 0.64.0
    ✔ Install chart 'solo-deployment' [2s]
    ❯ Patch ServiceMonitor for Prometheus discovery
    ✔ Patch ServiceMonitor for Prometheus discovery 
    ❯ Check for load balancer
    ↓ Check for load balancer [SKIPPED: Check for load balancer]
    ❯ Redeploy chart with external IP address config
    ↓ Redeploy chart with external IP address config [SKIPPED: Redeploy chart with external IP address config]
    ❯ Check node pods are running
    ❯ Check Node: node1, Cluster: kind-solo
    ✔ Check Node: node1, Cluster: kind-solo [22s]
    ✔ Check node pods are running [22s]
    ❯ Check proxy pods are running
    ❯ Check HAProxy for: node1, cluster: kind-solo
    ❯ Check Envoy Proxy for: node1, cluster: kind-solo
    ✔ Check HAProxy for: node1, cluster: kind-solo 
    ✔ Check Envoy Proxy for: node1, cluster: kind-solo 
    ✔ Check proxy pods are running 
    ❯ Check auxiliary pods are ready
    ❯ Check MinIO
    ↓ Check MinIO [SKIPPED: Check MinIO]
    ✔ Check auxiliary pods are ready 
    ❯ Add node and proxies to remote config
    ✔ Add node and proxies to remote config 
    ❯ Copy wraps lib into consensus node
    ↓ Copy wraps lib into consensus node [SKIPPED: Copy wraps lib into consensus node]
    ❯ Copy block-nodes.json
    ✔ Copy block-nodes.json [0.7s]
    ❯ Copy JFR config file to nodes
    ↓ Copy JFR config file to nodes [SKIPPED: Copy JFR config file to nodes]

6. Set Up Consensus Nodes

• Download the consensus node platform software and configure each node:

  export CONSENSUS_NODE_VERSION=v0.66.0
  
  solo consensus node setup \
    --deployment "${SOLO_DEPLOYMENT}" \
    --release-tag "${CONSENSUS_NODE_VERSION}"
  

  On native Windows (PowerShell), set the version with $env:CONSENSUS_NODE_VERSION = 'v0.66.0' and reference variables as $env:SOLO_DEPLOYMENT / $env:CONSENSUS_NODE_VERSION.

• Example output:

  ******************************* Solo *********************************************
    Version			: 0.80.0
    Kubernetes Context	: kind-solo
    Kubernetes Cluster	: kind-solo
    Current Command		: consensus node setup --deployment solo-deployment --consensus-node-version v0.74.0
    **********************************************************************************
    ❯ Load configuration
    ✔ Load configuration [0.2s]
    ❯ Initialize
    ✔ Initialize [0.2s]
    ❯ Validate nodes states
    ❯ Validating state for node node1
    ✔ Validating state for node node1 - valid state: requested 
    ✔ Validate nodes states 
    ❯ Identify network pods
    ❯ Check network pod: node1
    ✔ Check network pod: node1 
    ✔ Identify network pods 
    ❯ Fetch platform software into network nodes
    ❯ Update node: node1 [ platformVersion = v0.74.0, context = kind-solo ]
    ✔ Update node: node1 [ platformVersion = v0.74.0, context = kind-solo ] [2s]
    ✔ Fetch platform software into network nodes [4s]
    ❯ Setup network nodes
    ❯ Node: node1
    ❯ Copy configuration files
    ✔ Copy configuration files [0.5s]
    ❯ Set file permissions
    ✔ Set file permissions [0.4s]
    ✔ Node: node1 [1s]
    ✔ Setup network nodes [1s]
    ❯ Update block-nodes.json
    ✔ Update block-nodes.json [0.7s]
    ❯ setup network node folders
    ✔ setup network node folders [0.1s]
    ❯ Change node state to configured in remote config
    ✔ Change node state to configured in remote config 

7. Start Consensus Nodes

• Start all configured nodes and wait for them to reach ACTIVE status:

  solo consensus node start --deployment "${SOLO_DEPLOYMENT}"
  

• Expected output:

  ******************************* Solo *********************************************
    Version			: 0.80.0
    Kubernetes Context	: kind-solo
    Kubernetes Cluster	: kind-solo
    Current Command		: consensus node start --deployment solo-deployment
    **********************************************************************************
    ❯ Pre-flight: check Docker Desktop containerd setting
    ✔ Pre-flight: check Docker Desktop containerd setting 
    ❯ Check dependencies
    ❯ Check dependency: helm [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ❯ Check dependency: kind [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ❯ Check dependency: kubectl [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ✔ Check dependency: kind [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependency: helm [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependency: kubectl [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependencies 
    ❯ Setup chart manager
    ✔ Setup chart manager [0.7s]
    ❯ Load configuration
    ✔ Load configuration [0.3s]
    ❯ Initialize
    ✔ Initialize 
    ❯ Validate nodes states
    ❯ Validating state for node node1
    ✔ Validating state for node node1 - valid state: configured 
    ✔ Validate nodes states 
    ❯ Identify existing network nodes
    ❯ Check network pod: node1
    ✔ Check network pod: node1 
    ✔ Identify existing network nodes 
    ❯ Upload state files network nodes
    ↓ Upload state files network nodes [SKIPPED: Upload state files network nodes]
    ❯ Starting nodes
    ❯ Start node: node1
    ✔ Start node: node1 [1s]
    ✔ Starting nodes [1s]
    ❯ Enable port forwarding for debug port and/or GRPC port
    Using requested port 35211
    ✔ Enable port forwarding for debug port and/or GRPC port 
    ❯ Check nodes are ACTIVE and proxies are ready
    ❯ Check all nodes are ACTIVE
    ❯ Check node proxies are ACTIVE
    ❯ Check proxy for node: node1
    ❯ Check network pod: node1 
    ✔ Check proxy for node: node1 
    ✔ Check node proxies are ACTIVE 
    Using requested port 30212
    Stopping port-forward for port [30212]
    Using requested port 30212
    Stopping port-forward for port [30212]
    Using requested port 30212
    ✔ Check network pod: node1  - gRPC readiness 3/3, attempt: 2/20 [40s]
    ✔ Check all nodes are ACTIVE [40s]
    ✔ Check nodes are ACTIVE and proxies are ready [40s]
    ❯ Wait for TSS
    ❯ Waiting for node: node1
    ✔ Waiting for node: node1, attempt 1/60 [10s]
    ✔ Wait for TSS [10s]
    ❯ set gRPC Web endpoint
    Stopping port-forward for port [30212]
    Using requested port 30212
    ✔ set gRPC Web endpoint [4s]
    ❯ Change node state to started in remote config
    ✔ Change node state to started in remote config 
    ❯ Add node stakes
    ❯ Adding stake for node: node1
    ✔ Adding stake for node: node1 [2s]
    ✔ Add node stakes [2s]
    ❯ Emit node started event
    ✔ Emit node started event 
    Stopping port-forward for port [30212]

8. Deploy Mirror Node

• Deploy the Hedera Mirror Node, which indexes all transaction data and exposes a REST API and gRPC endpoint:

  solo mirror node add \
    --deployment "${SOLO_DEPLOYMENT}" \
    --cluster-ref kind-${SOLO_CLUSTER_NAME} \
    --enable-ingress \
    --pinger
  

  The --pinger flag keeps the mirror node’s importer active by regularly submitting record files. The --enable-ingress flag installs the HAProxy ingress controller for the mirror node REST API.

• Expected output:

  ******************************* Solo *********************************************
    Version			: 0.80.0
    Kubernetes Context	: kind-solo
    Kubernetes Cluster	: kind-solo
    Current Command		: mirror node add --deployment solo-deployment --cluster-ref kind-solo --enable-ingress --quiet-mode
    **********************************************************************************
    ❯ Pre-flight: check Docker Desktop containerd setting
    ✔ Pre-flight: check Docker Desktop containerd setting 
    ❯ Check dependencies
    ❯ Check dependency: helm [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ❯ Check dependency: kind [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ❯ Check dependency: kubectl [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ✔ Check dependency: kind [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependency: helm [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependency: kubectl [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependencies 
    ❯ Setup chart manager
    ✔ Setup chart manager [0.7s]
    ❯ Initialize
    ❯ Acquire lock
    ✔ Acquire lock - lock acquired successfully, attempt: 1/10 
    ✔ Initialize [0.4s]
    ❯ Add mirror node to remote config
    ✔ Add mirror node to remote config 
    ❯ load node client
    Using requested port 30212
    ✔ load node client [1s]
    ❯ Deploy charts
    ❯ Enable shared resources
    ❯ Install Shared Resources chart
    ✔ Install Shared Resources chart [3s]
    ❯ Load redis credentials
    ✔ Load redis credentials 
    ❯ Initialize Postgres pod
    ❯ Wait for Postgres pod to be ready
    ✔ Wait for Postgres pod to be ready [11s]
    ✔ Initialize Postgres pod [11s]
    ❯ Add shared resource components to remote config
    ✔ Add shared resource components to remote config 
    ✔ Enable shared resources [14s]
    ❯ Prime mirror-node postgres secret
    ✔ Prime mirror-node postgres secret [0.7s]
    ❯ Delete stale mirror redis secret
    ✔ Delete stale mirror redis secret 
    ❯ Run database initialization script
    ✔ Run database initialization script [1s]
    ❯ Enable mirror-node
    ❯ Prepare address book
    ✔ Prepare address book 
    ❯ Install mirror ingress controller
     - Installed haproxy-ingress-1 chart, version: 0.14.5
    ✔ Install mirror ingress controller [0.7s]
    ❯ Deploy mirror-node
     - Installed mirror chart, version: v0.157.0
    ✔ Deploy mirror-node [2s]
    ✔ Enable mirror-node [3s]
    ✔ Deploy charts [20s]
    ❯ Check pods are ready
    ❯ Check Grpc
    ❯ Check Importer
    ❯ Check Rest
    ❯ Check Rest Java
    ❯ Check Web3
    ✔ Check Rest Java [10s]
    ✔ Check Web3 [14s]
    ✔ Check Grpc [18s]
    ✔ Check Importer [18s]
    ✔ Check Rest [20s]
    ✔ Check pods are ready [20s]
    ❯ Enable port forwarding for mirror ingress controller
    Using requested port 38081
    ✔ Enable port forwarding for mirror ingress controller 
    ❯ Show user messages
    
     *** Port forwarding enabled: ***
    -------------------------------------------------------------------------------
     - Mirror ingress controller port forward enabled on 127.0.0.1:38081
    -------------------------------------------------------------------------------
    ✔ Show user messages 
    Stopping port-forward for port [30212]

9. Deploy Explorer

• Deploy the Hiero Explorer, a web UI for browsing transactions and accounts:

  solo explorer node add \
    --deployment "${SOLO_DEPLOYMENT}" \
    --cluster-ref kind-${SOLO_CLUSTER_NAME}
  

• Expected output:

  ******************************* Solo *********************************************
    Version			: 0.80.0
    Kubernetes Context	: kind-solo
    Kubernetes Cluster	: kind-solo
    Current Command		: explorer node add --deployment solo-deployment --cluster-ref kind-solo --quiet-mode
    **********************************************************************************
    ❯ Pre-flight: check Docker Desktop containerd setting
    ✔ Pre-flight: check Docker Desktop containerd setting 
    ❯ Check dependencies
    ❯ Check dependency: helm [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ❯ Check dependency: kind [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ❯ Check dependency: kubectl [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ✔ Check dependency: kind [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependency: helm [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependency: kubectl [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependencies 
    ❯ Setup chart manager
    ✔ Setup chart manager [0.7s]
    ❯ Initialize
    ❯ Acquire lock
    ✔ Acquire lock - lock acquired successfully, attempt: 1/10 
    ✔ Initialize [0.4s]
    ❯ Load remote config
    ✔ Load remote config [0.1s]
    ❯ Add explorer to remote config
    ✔ Add explorer to remote config 
    ❯ Install cert manager
    ↓ Install cert manager [SKIPPED: Install cert manager]
    ❯ Install explorer
     - Installed hiero-explorer-1 chart, version: 26.1.0
    ✔ Install explorer [0.7s]
    ❯ Install explorer ingress controller
    ↓ Install explorer ingress controller [SKIPPED: Install explorer ingress controller]
    ❯ Check explorer pod is ready
    ✔ Check explorer pod is ready [4s]
    ❯ Check haproxy ingress controller pod is ready
    ↓ Check haproxy ingress controller pod is ready [SKIPPED: Check haproxy ingress controller pod is ready]
    ❯ Enable port forwarding for explorer
    No port forward config found for Explorer
    Using requested port 38080
    ✔ Enable port forwarding for explorer 
    ❯ Show user messages
    
     *** Port forwarding enabled: ***
    -------------------------------------------------------------------------------
     - Explorer port forward enabled on 127.0.0.1:38080
    -------------------------------------------------------------------------------
    ✔ Show user messages 

10. Deploy JSON-RPC Relay

• Deploy the Hiero JSON-RPC Relay to expose an Ethereum-compatible JSON-RPC endpoint for EVM tooling (MetaMask, Hardhat, Foundry, etc.):

  solo relay node add \
    -i node1 \
    --deployment "${SOLO_DEPLOYMENT}"
  

TODO: double check these, and update in solo repo if needed to match, also double check the exported variables match

• Expected output:

  ******************************* Solo *********************************************
    Version			: 0.80.0
    Kubernetes Context	: kind-solo
    Kubernetes Cluster	: kind-solo
    Current Command		: relay node add --node-aliases node1 --deployment solo-deployment --cluster-ref kind-solo --relay-version 0.77.0
    **********************************************************************************
    ❯ Pre-flight: check Docker Desktop containerd setting
    ✔ Pre-flight: check Docker Desktop containerd setting 
    ❯ Check dependencies
    ❯ Check dependency: helm [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ❯ Check dependency: kind [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ❯ Check dependency: kubectl [OS: linux, Release: 6.8.0-117-generic, Arch: x64]
    ✔ Check dependency: kind [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependency: helm [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependency: kubectl [OS: linux, Release: 6.8.0-117-generic, Arch: x64] 
    ✔ Check dependencies 
    ❯ Setup chart manager
    ✔ Setup chart manager [0.8s]
    ❯ Initialize
    ❯ Acquire lock
    ✔ Acquire lock - lock acquired successfully, attempt: 1/10 
    ✔ Initialize [0.4s]
    ❯ Add relay component in remote config
    ✔ Add relay component in remote config 
    ❯ Check chart is installed
    ✔ Check chart is installed [0.1s]
    ❯ Prepare chart values
    ✔ Prepare chart values 
    ❯ Deploy JSON RPC Relay
     - Installed relay-1 chart, version: 0.77.0
    ✔ Deploy JSON RPC Relay [0.6s]
    ❯ Check relay is running
    ✔ Check relay is running [4s]
    ❯ Check relay is ready
    ✔ Check relay is ready [3s]
    ❯ Enable port forwarding for relay node
    No port forward config found for JSON RPC Relay
    Using requested port 37546
    ✔ Enable port forwarding for relay node 
    ❯ Show user messages
    
     *** Port forwarding enabled: ***
    -------------------------------------------------------------------------------
     - JSON RPC Relay port forward enabled on 127.0.0.1:37546
    -------------------------------------------------------------------------------
    ✔ Show user messages 

Cleanup

When you are done, destroy components in the reverse order of deployment.

Important: Always destroy components before destroying the network. Skipping this order can leave orphaned Helm releases and PVCs in your cluster.

1. Destroy JSON-RPC Relay

solo relay node destroy \
  -i node1 \
  --deployment "${SOLO_DEPLOYMENT}" \
  --cluster-ref kind-${SOLO_CLUSTER_NAME}

2. Destroy Explorer

solo explorer node destroy \
  --deployment "${SOLO_DEPLOYMENT}" \
  --force

3. Destroy Mirror Node

solo mirror node destroy \
  --deployment "${SOLO_DEPLOYMENT}" \
  --force

4. Destroy the Network

solo consensus network destroy \
  --deployment "${SOLO_DEPLOYMENT}" \
  --force

2.4 - Custom Application Properties

Overview

Solo lets you provide a custom application.properties file for consensus nodes with the --application-properties flag. By default, Solo merges your file with its generated defaults. If you need complete control over the final file, add an overwrite marker to your custom file.

Use the default merge mode when you only need to change or add a few properties. Use overwrite mode only when you want your file to replace Solo’s generated application.properties content.

Default merge mode

Pass your file to solo consensus network deploy:

solo consensus network deploy \
  --deployment "${SOLO_DEPLOYMENT}" \
  --application-properties ./config/application.properties

In merge mode, Solo starts with its generated application.properties, then applies your file as key-level overrides:

• If your file contains a key that already exists in Solo’s generated file, Solo replaces that key’s value.
• If your file contains a new key, Solo appends it to the final file.
• Blank lines and comments in your file are ignored during the merge.
• Solo-generated keys that you do not mention remain in the final file.

Example custom file for merge mode:

# Override only the properties that need to change.
contracts.chainId=298
hedera.recordStream.logPeriod=1

This is the recommended mode for most deployments because Solo keeps its generated defaults while still applying your overrides.

Overwrite mode

To replace Solo’s generated application.properties file, add the overwrite marker as a comment in your custom file:

# SOLO_ENABLE_OVERWRITE=true

contracts.chainId=298
hedera.recordStream.logPeriod=1
# Include every other property your consensus nodes require.

Then deploy with the same flag:

solo consensus network deploy \
  --deployment "${SOLO_DEPLOYMENT}" \
  --application-properties ./config/application.properties

The marker must be on a comment line that starts with #. Solo looks for the exact text SOLO_ENABLE_OVERWRITE=true inside a comment. If the marker is missing, or if it is written as a normal property instead of a comment, Solo uses default merge mode.

In overwrite mode, your file becomes the full application.properties content. Solo does not carry over defaults that are missing from your file, so include all properties required by the consensus node version and deployment topology you are running.

Falcon values file

For One-shot Falcon deployments, put the same flag under the network section:

network:
  --application-properties: "./config/application.properties"

The merge or overwrite behavior is still controlled by the contents of the referenced application.properties file. Add # SOLO_ENABLE_OVERWRITE=true to that file only when you want overwrite mode.

For the complete list of Falcon network flags, see the Falcon Values File Reference.

2.5 - Dynamically add, update, and remove Consensus Nodes

Overview

This guide covers how to dynamically manage consensus nodes in a running Solo network - adding new nodes, updating existing ones, and removing nodes that are no longer needed. All three operations can be performed without taking the network offline.

Prerequisites

Before proceeding, ensure you have:

• A running Solo network. If you don’t have one, deploy using one of the following methods:

  1. Quickstart - single command deployment using solo one-shot single deploy.
  2. Manual Deployment - step-by-step deployment with full control over each component.

• Set the required environment variables as described below:

• Bash
• PowerShell

export SOLO_CLUSTER_NAME=solo
export SOLO_NAMESPACE=solo-deployment
export SOLO_CLUSTER_SETUP_NAMESPACE=solo-cluster
export SOLO_DEPLOYMENT=solo-deployment

$env:SOLO_CLUSTER_NAME = 'solo'
$env:SOLO_NAMESPACE = 'solo-deployment'
$env:SOLO_CLUSTER_SETUP_NAMESPACE = 'solo-cluster'
$env:SOLO_DEPLOYMENT = 'solo-deployment'

Key and Storage Concepts

Before running any node operation, it helps to understand two concepts that appear in the prepare step.

1. Cryptographic Keys

   Solo generates two types of keys for each consensus node:

   • Gossip keys — used for encrypted node-to-node communication within the network. Stored as s-private-node*.pem and s-public-node*.pem under ~/.solo/cache/keys/.
   • TLS keys — used to secure gRPC connections to the node. Stored as hedera-node*.crt and hedera-node*.key under ~/.solo/cache/keys/.

   When adding a new node, Solo generates a fresh key pair and stores it alongside the keys for existing nodes in the same directory. For more detail, see Where are my keys stored?.

2. Persistent Volume Claims (PVCs)

   By default, consensus node storage is ephemeral - data stored by a node is lost if its pod crashes or is restarted. This is intentional for lightweight local testing where persistence is not required.

   The --pvcs true flag creates Persistent Volume Claims (PVCs) for the node, ensuring its state survives pod restarts. Enable this flag for any node that needs to persist across restarts or that will participate in longer-running test scenarios.

   Note: PVCs are not enabled by default. Enable them only if your node needs to persist state across pod restarts.

3. Staging Directory

   The --output-dir context flag specifies a local staging directory where Solo writes all artifacts produced during prepare. Solo’s working files are stored under ~/.solo/ — if you use a relative path like context, the directory is created in your current working directory. Do not delete it until execute has completed successfully.

Adding a Node to an Existing Network

You can dynamically add a new consensus node to a running network without taking the network offline. This process involves three stages: preparing the node’s keys and configuration, submitting the on-chain transaction, and executing the addition.

Step 1: Prepare the new node

Generate the new node’s gossip and TLS keys, create its persistent volumes, and stage its configuration into an output directory:

solo consensus dev-node-add prepare \
  --gossip-keys true \
  --tls-keys true \
  --deployment "${SOLO_DEPLOYMENT}" \
  --pvcs true \
  --admin-key <admin-key> \
  --node-alias node2 \
  --output-dir context

Step 2: Submit the transaction to add the node

Submit the on-chain transaction to register the new node with the network:

solo consensus dev-node-add submit-transactions \
  --deployment "${SOLO_DEPLOYMENT}" \
  --input-dir context

Step 3: Execute the node addition

Apply the node addition and bring the new node online:

solo consensus dev-node-add execute \
  --deployment "${SOLO_DEPLOYMENT}" \
  --input-dir context

Note: For a complete walkthrough with expected outputs, see the Node Create Transaction example.

Updating a Node

You can update an existing consensus node - for example, to upgrade its software version or modify its configuration - without removing it from the network.

Step 1: Prepare the update

Stage the updated configuration and any new software version for the target node:

solo consensus dev-node-update prepare \
  --deployment "${SOLO_DEPLOYMENT}" \
  --node-alias node1 \
  --release-tag v0.66.0 \
  --output-dir context

Step 2: Submit the update transaction

Submit the on-chain transaction to register the node update with the network:

solo consensus dev-node-update submit-transactions \
  --deployment "${SOLO_DEPLOYMENT}" \
  --input-dir context

Step 3: Execute the update

Apply the update and restart the node with the new configuration:

solo consensus dev-node-update execute \
  --deployment "${SOLO_DEPLOYMENT}" \
  --input-dir context

Note: For a complete walkthrough with expected outputs, see the Node Update Transaction example.

Removing a Node from a Network

You can dynamically remove a consensus node from a running network without taking the remaining nodes offline.

Note: Removing a node permanently reduces the number of consensus nodes in the network. Ensure the remaining nodes meet the minimum threshold required for consensus before proceeding.

Step 1: Prepare the Node for Deletion

Stage the deletion context for the target node:

solo consensus dev-node-delete prepare \
  --deployment "${SOLO_DEPLOYMENT}" \
  --node-alias node2 \
  --output-dir context

Step 2: Submit the delete transaction

Submit the on-chain transaction to deregister the node from the network:

solo consensus dev-node-delete submit-transactions \
  --deployment "${SOLO_DEPLOYMENT}" \
  --input-dir context

Step 3: Execute the deletion

Remove the node and clean up its associated resources:

solo consensus dev-node-delete execute \
  --deployment "${SOLO_DEPLOYMENT}" \
  --input-dir context

Note: For a complete walkthrough with expected outputs, see the Node Delete Transaction example.

3 - Attach JVM Debugger and Retrieve Logs

Overview

This guide covers three debugging workflows:

• Retrieve logs from a running consensus node using k9s or the Solo CLI
• Attach a JVM debugger in IntelliJ IDEA to a running or restarting node
• Save and restore network state files to replay scenarios across sessions

Prerequisites

Before proceeding, ensure you have completed the following:

• System Readiness — your local environment meets all hardware and software requirements.
• Quickstart — you have a running Solo cluster and are familiar with the basic Solo workflow.

You will also need:

• k9s installed (brew install k9s)
• IntelliJ IDEA with a Remote JVM Debug run configuration (for JVM debugging only)
• A local checkout of hiero-consensus-node that has been built with assemble or build (for JVM debugging only)

1. Retrieve Consensus Node Logs

Using k9s

Run k9s -A in your terminal to open the cluster dashboard, then select one of the network node pods.

Select the root-container and press s to open a shell inside the container.

Navigate to the Hedera application directory to browse logs and configuration:

cd /opt/hgcapp/services-hedera/HapiApp2.0/

From there you can inspect logs and configuration files:

[root@network-node1-0 HapiApp2.0]# ls -ltr data/config/
total 0
lrwxrwxrwx 1 root root 27 Dec  4 02:05 bootstrap.properties -> ..data/bootstrap.properties
lrwxrwxrwx 1 root root 29 Dec  4 02:05 application.properties -> ..data/application.properties
lrwxrwxrwx 1 root root 32 Dec  4 02:05 api-permission.properties -> ..data/api-permission.properties

[root@network-node1-0 HapiApp2.0]# ls -ltr output/
total 1148
-rw-r--r-- 1 hedera hedera       0 Dec  4 02:06 hgcaa.log
-rw-r--r-- 1 hedera hedera       0 Dec  4 02:06 queries.log
drwxr-xr-x 2 hedera hedera    4096 Dec  4 02:06 transaction-state
drwxr-xr-x 2 hedera hedera    4096 Dec  4 02:06 state
-rw-r--r-- 1 hedera hedera     190 Dec  4 02:06 swirlds-vmap.log
drwxr-xr-x 2 hedera hedera    4096 Dec  4 16:01 swirlds-hashstream
-rw-r--r-- 1 hedera hedera 1151446 Dec  4 16:07 swirlds.log

Using the Solo CLI (Alternative option)

To download hgcaa.log and swirlds.log as a zip archive without entering the container shell, run:

# Downloads logs to ~/.solo/logs/<namespace>/<timestamp>
solo deployment diagnostics all --deployment solo-deployment

2. Attach a JVM Debugger in IntelliJ IDEA

Solo supports pausing node startup at a JDWP debug port so you can attach IntelliJ IDEA before the node begins processing transactions.

Configure IntelliJ IDEA

Create a Remote JVM Debug run configuration in IntelliJ IDEA.

For the Hedera Node application:

If you are working on the Platform test application instead:

Set any breakpoints you need before launching the Solo command in the next step.

Note: The local-build-path in the commands below references ../hiero-consensus-node/hedera-node/data. Adjust this path to match your local checkout location. Ensure the directory is up to date by running ./gradlew assemble in the hiero-consensus-node repo before proceeding.

Example 1 — Debug a node during initial network deployment

This example deploys a three-node network and pauses node2 for debugger attachment.

SOLO_CLUSTER_NAME=solo-cluster
SOLO_NAMESPACE=solo-deployment
SOLO_CLUSTER_SETUP_NAMESPACE=solo-setup
SOLO_DEPLOYMENT=solo-deployment

# Remove any previous state to avoid name collision issues
rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"

solo cluster-ref config setup -s "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect --cluster-ref ${SOLO_CLUSTER_NAME} --context kind-${SOLO_CLUSTER_NAME}

solo deployment config create --namespace "${SOLO_NAMESPACE}" --deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach --deployment "${SOLO_DEPLOYMENT}" --cluster-ref ${SOLO_CLUSTER_NAME} --num-consensus-nodes 3
solo keys consensus generate --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys -i node1,node2,node3

solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --debug-node-alias node2
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --local-build-path ../hiero-consensus-node/hedera-node/data
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --debug-node-alias node2

When Solo reaches the active-check phase for node2, it pauses and displays:

❯ Check all nodes are ACTIVE
  Check node: node1,
  Check node: node2,  Please attach JVM debugger now.
  Check node: node3,
? JVM debugger setup for node2. Continue when debugging is complete? (y/N)

At this point, launch the remote debug configuration in IntelliJ IDEA. The node will stop at your breakpoint:

When you are done debugging, resume execution in IntelliJ, then type y in the terminal to allow Solo to continue.

Example 2 — Debug a node during a node add operation

This example starts a three-node network and then attaches a debugger while adding node4.

SOLO_CLUSTER_NAME=solo-cluster
SOLO_NAMESPACE=solo-deployment
SOLO_CLUSTER_SETUP_NAMESPACE=solo-setup
SOLO_DEPLOYMENT=solo-deployment

rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"

solo cluster-ref config setup -s "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect --cluster-ref ${SOLO_CLUSTER_NAME} --context kind-${SOLO_CLUSTER_NAME}

solo deployment config create --namespace "${SOLO_NAMESPACE}" --deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach --deployment "${SOLO_DEPLOYMENT}" --cluster-ref ${SOLO_CLUSTER_NAME} --num-consensus-nodes 3
solo keys consensus generate --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys -i node1,node2,node3

solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --pvcs
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --local-build-path ../hiero-consensus-node/hedera-node/data
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3

solo consensus node add --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys \
  --debug-node-alias node4 \
  --local-build-path ../hiero-consensus-node/hedera-node/data \
  --pvcs

Example 3 — Debug a node during a node update operation

This example attaches a debugger to node2 while it restarts as part of an update operation.

SOLO_CLUSTER_NAME=solo-cluster
SOLO_NAMESPACE=solo-deployment
SOLO_CLUSTER_SETUP_NAMESPACE=solo-setup
SOLO_DEPLOYMENT=solo-deployment

rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"

solo cluster-ref config setup -s "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect --cluster-ref ${SOLO_CLUSTER_NAME} --context kind-${SOLO_CLUSTER_NAME}

solo deployment config create --namespace "${SOLO_NAMESPACE}" --deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach --deployment "${SOLO_DEPLOYMENT}" --cluster-ref ${SOLO_CLUSTER_NAME} --num-consensus-nodes 3
solo keys consensus generate --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys -i node1,node2,node3

solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --local-build-path ../hiero-consensus-node/hedera-node/data
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3

solo consensus node update --deployment "${SOLO_DEPLOYMENT}" \
  --node-alias node2 \
  --debug-node-alias node2 \
  --local-build-path ../hiero-consensus-node/hedera-node/data \
  --new-account-number 0.0.7 \
  --gossip-public-key ./s-public-node2.pem \
  --gossip-private-key ./s-private-node2.pem \
  --release-tag v0.71.0

Example 4 — Debug a node during a node delete operation

This example attaches a debugger to node3 while node2 is being removed from the network.

SOLO_CLUSTER_NAME=solo-cluster
SOLO_NAMESPACE=solo-deployment
SOLO_CLUSTER_SETUP_NAMESPACE=solo-setup
SOLO_DEPLOYMENT=solo-deployment

rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"

solo cluster-ref config setup -s "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect --cluster-ref ${SOLO_CLUSTER_NAME} --context kind-${SOLO_CLUSTER_NAME}

solo deployment config create --namespace "${SOLO_NAMESPACE}" --deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach --deployment "${SOLO_DEPLOYMENT}" --cluster-ref ${SOLO_CLUSTER_NAME} --num-consensus-nodes 3
solo keys consensus generate --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys -i node1,node2,node3

solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --local-build-path ../hiero-consensus-node/hedera-node/data
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3

solo consensus node destroy --deployment "${SOLO_DEPLOYMENT}" \
  --node-alias node2 \
  --debug-node-alias node3 \
  --local-build-path ../hiero-consensus-node/hedera-node/data

3. Save and Restore Network State

You can snapshot the state of a running network and restore it later. This is useful for replaying specific scenarios or sharing reproducible test cases with the team.

Save state

Stop the nodes first, then download the state archives:

# Stop all nodes before downloading state
solo consensus node stop --deployment "${SOLO_DEPLOYMENT}"

# Download state files to ~/.solo/logs/<namespace>/
solo consensus state download -i node1,node2,node3 --deployment "${SOLO_DEPLOYMENT}"

The state files are saved under ~/.solo/logs/:

└── logs
    ├── solo-deployment
    │   ├── network-node1-0-state.zip
    │   └── network-node2-0-state.zip
    └── solo.log

Restore state

Create a fresh cluster, deploy the network, then upload the saved state before starting the nodes:

SOLO_CLUSTER_NAME=solo-cluster
SOLO_NAMESPACE=solo-deployment
SOLO_CLUSTER_SETUP_NAMESPACE=solo-setup
SOLO_DEPLOYMENT=solo-deployment

rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"

solo cluster-ref config setup -s "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect --cluster-ref ${SOLO_CLUSTER_NAME} --context kind-${SOLO_CLUSTER_NAME}

solo deployment config create --namespace "${SOLO_NAMESPACE}" --deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach --deployment "${SOLO_DEPLOYMENT}" --cluster-ref ${SOLO_CLUSTER_NAME} --num-consensus-nodes 3
solo keys consensus generate --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys -i node1,node2,node3

solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --local-build-path ../hiero-consensus-node/hedera-node/data
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3
solo consensus node stop --deployment "${SOLO_DEPLOYMENT}"

# Upload previously saved state files
solo consensus node state download  -i node1,node2,node3 --deployment "${SOLO_DEPLOYMENT}"

# Restart the network using the uploaded state
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" --state-file network-node1-0-state.zip

4 - One-Shot Deploy with Custom Component Versions

Overview

Solo’s one-shot single deploy and one-shot multi deploy commands accept an --edge flag that switches every component from its built-in stable default to a separate set of “edge” versions. Each edge version is read from an environment variable at startup, so you can pin any component to any tag the container registry exposes — including release candidates and unreleased builds — without editing Solo source or rebuilding the CLI.

Use this guide when you need to:

• Test a Hiero Consensus Node release candidate against the rest of the Solo-managed stack.
• Reproduce a specific component version combination for a bug report or regression test.
• Iterate on a single component (Mirror Node, Relay, Explorer, …) while the other components stay on stable defaults.

For the canonical list of *_EDGE_VERSION variables, see Edge Component Versions in the environment variables reference.

Local binary builds vs published version overrides: --edge and *_EDGE_VERSION variables pin components to published container image tags — they require the image to exist in the registry. If you need to deploy a binary you compiled locally (before any tag or release exists), use --local-build-path instead. See Deploying a Local Consensus Node Build.

How It Works

*_EDGE_VERSION env var (e.g. CONSENSUS_NODE_EDGE_VERSION)
      │
      ▼
solo one-shot ... deploy --edge
      │
      ▼
Each component is pinned to its edge version for this deploy.
Components without an explicit override fall back to the compiled-in
edge defaults, which themselves fall back to the stable defaults.

• Without --edge, Solo uses the stable defaults compiled into the CLI.
• With --edge, Solo reads the *_EDGE_VERSION constants — and any matching environment variable you set in the shell overrides those constants.

You only need to set variables for the components you want to override. All others fall back to their compiled-in defaults.

Image cache: Because you pin versions with environment variables, Solo’s image cache pulls the matching image versions automatically. Pinning a version with a --*-version CLI flag (or in solo.config.yaml) instead does not update the cache — it would pull the default versions and cause a cache miss on first deploy. Use the environment variables shown here to keep the cache aligned with the deployed versions.

Quick Start

Deploy a single-node network with a custom Consensus Node release candidate:

CONSENSUS_NODE_EDGE_VERSION=v0.74.0-rc.1 \
solo one-shot single deploy --edge --dev

What this does:

• CONSENSUS_NODE_EDGE_VERSION=v0.74.0-rc.1 overrides the consensus node version for this command invocation.
• --edge tells Solo to read *_EDGE_VERSION variables instead of stable defaults.
• --dev enables Solo’s developer mode — appropriate for local development, not for production-shaped deployments.
• Mirror Node, Relay, Explorer, Block Node, and the Solo chart keep their compiled-in edge defaults because no *_EDGE_VERSION was set for them.

Note: If you already have a running one-shot deployment and want to keep it, the command above fails with “A deployment named one-shot already exists” because one-shot is the default deployment name. Pass --deployment <name> --namespace <name> to deploy the edge build alongside the existing one:

CONSENSUS_NODE_EDGE_VERSION=v0.74.0-rc.1 \
solo one-shot single deploy --edge --dev \
  --deployment one-shot-edge --namespace one-shot-edge

Every solo one-shot deploy overwrites ~/.solo/cache/last-one-shot-deployment.txt with its own deployment name. After this command, the cache file points at one-shot-edge, not the original one-shot. Pass --deployment explicitly when running follow-up commands against a specific deployment.

Where to Find Version Tags

Each *_EDGE_VERSION value is a published release tag from the component’s GitHub release page. Pick a tag from the appropriate page below, and match the format the component publishes — a missing or extra v prefix is the most common cause of image-pull failures.

Note: Consensus Node, Mirror Node, and Block Node tags are prefixed with v; Relay, Explorer, and Solo Chart tags are not. The tag must exist in the component’s container registry, otherwise the deploy fails with an image-pull error — see Troubleshooting.

Command Reference

In Solo v0.72.0, --edge is accepted by the single and multi one-shot deploy variants. solo one-shot falcon deploy does not currently accept --edge — use one of the two variants below to test custom component versions.

Single-node deploy

CONSENSUS_NODE_EDGE_VERSION=<version> \
MIRROR_NODE_EDGE_VERSION=<version> \
solo one-shot single deploy --edge [--dev] [other flags]

Multi-node deploy

CONSENSUS_NODE_EDGE_VERSION=<version> \
MIRROR_NODE_EDGE_VERSION=<version> \
solo one-shot multi deploy --edge --num-consensus-nodes 3 [--dev] [other flags]

Examples

Override Consensus Node and Mirror Node

CONSENSUS_NODE_EDGE_VERSION=v0.73.0 \
MIRROR_NODE_EDGE_VERSION=v0.153.1 \
solo one-shot single deploy --edge --dev

Override every component

CONSENSUS_NODE_EDGE_VERSION=v0.73.0 \
MIRROR_NODE_EDGE_VERSION=v0.153.1 \
RELAY_EDGE_VERSION=0.77.0 \
EXPLORER_EDGE_VERSION=27.0.0 \
BLOCK_NODE_EDGE_VERSION=v0.32.0 \
SOLO_CHART_EDGE_VERSION=0.64.0 \
solo one-shot single deploy --edge --dev

Export once, reuse across a development session

If you are iterating and running deploy/destroy/deploy cycles, export the variables so every one-shot command in the shell session picks them up:

export CONSENSUS_NODE_EDGE_VERSION=v0.74.0-rc.1
export MIRROR_NODE_EDGE_VERSION=v0.153.1

solo one-shot single deploy --edge --dev

# Destroy and redeploy without re-typing the variables
solo one-shot single destroy
solo one-shot single deploy --edge --dev

Verifying the Versions in Use

After the deploy starts, confirm the resolved versions in the structured Solo log:

tail -f $HOME/.solo/logs/solo.ndjson | jq '.msg, .version // empty'

Note: Use solo.ndjson (newline-delimited JSON, machine-readable) for jq pipes. The companion solo.log is pino-pretty formatted text and will not parse as JSON.

Inspect the deployed Helm releases and their chart versions:

helm list -A
helm get values <release-name> -n <namespace>

Confirm the consensus node container image tag:

kubectl get pods -n <namespace> -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'

Replace <namespace> with your deployment namespace (default one-shot — see Find your deployment namespace).

Without --edge

Omitting --edge uses the stable defaults compiled into the Solo CLI you are running — any *_EDGE_VERSION variables you have set are ignored for that invocation.

# Stable defaults — *_EDGE_VERSION variables are ignored.
solo one-shot single deploy --dev

If you want to pin versions without using --edge (for example, to test a specific stable release of one component), see Pinning Component Versions in the environment variables reference.

Troubleshooting

The version I set is not being used.

Confirm you passed --edge. Without it, Solo ignores every *_EDGE_VERSION variable and uses the compiled-in stable defaults.

Solo is ignoring my environment variable.

The variable must be exported in (or prefixed to) the same shell process that runs Solo. Verify with:

echo $CONSENSUS_NODE_EDGE_VERSION   # should print your value

If you set the variable inline (FOO=bar solo ...), double-check the variable name is spelled exactly as listed in Edge Component Versions — the names are case-sensitive.

The deploy fails with an image-pull error.

The tag you supplied does not exist in the component’s container registry, or the format is wrong (missing v prefix, extra spaces, …). Cross-check the tag against the official release list for that component before retrying.

The deploy starts but a component crashes immediately.

Different component versions are not guaranteed to be mutually compatible. When mixing edge versions, prefer combinations Solo’s CI already exercises (see the Version Compatibility Reference).

5 - Customizing Solo with Tasks

Overview

The Task tool (task) is a task runner that enables you to deploy and customize Solo networks using infrastructure-as-code patterns. Rather than running individual Solo CLI commands, you can use predefined Taskfile targets to orchestrate complex deployment workflows with a single command.

This guide covers installing the Task tool, understanding available Taskfile targets, and using them to deploy networks with various configurations. It also points to maintained example projects that demonstrate common Solo workflows.

Note: This guide assumes you have cloned the Solo repository and have basic familiarity with command-line interfaces and Docker.

Prerequisites

Before you begin, ensure you have completed the following:

• System Readiness: Prepare your local environment (Docker, Kind, Kubernetes, and related tooling).
• Quickstart: You are familiar with the basic Solo workflow and the solo one-shot single deploy command.

Tip: Task-based workflows are ideal for developers who want to:

• Run the same deployment multiple times reliably.
• Customize network components (add mirror nodes, relays, block nodes, etc.).
• Use version control to track deployment configurations.
• Integrate Solo deployments into CI/CD pipelines.

Install the Task Tool

The Task tool is a dependency for using Taskfile targets in the Solo repository. Install it using one of the following methods:

Using Homebrew (macOS/Linux) (recommended)

brew install go-task/tap/go-task

Using npm

npm install -g @go-task/cli

Verify the installation:

task --version

Expected output:

Task version: v3.X.X

Using package managers

Visit the Task installation guide for additional installation methods for your operating system.

Understanding the Task Structure

The Solo repository uses a modular Task architecture located in the scripts/ directory:

scripts/
├── Taskfile.yml                    # Main entry point (includes other Taskfiles)
├── Taskfile.scripts.yml            # Core deployment and management tasks
├── Taskfile.examples.yml           # Example project tasks
├── Taskfile.release.yml            # Package publishing tasks
└── [other helper scripts]

How to Run Tasks

From the root directory or any example directory, run:

# Run the default task
task

# Run a specific task
task <task-name>

# Run tasks with variables
task <task-name> -- VAR_NAME=value

Deploy Network Configurations

Basic Network Deployment

Deploy a standalone Hiero Consensus Node network with a single command:

# From the repository root, navigate to scripts directory
cd scripts

# Deploy default network (2 consensus nodes)
task default

This command performs the following actions:

• Initializes Solo and downloads required dependencies.
• Creates a local Kubernetes cluster using Kind.
• Deploys 2 consensus nodes.
• Sets up gRPC and JSON-RPC endpoints for client access.

Deploy Network with Mirror Node

Deploy a network with a consensus node, mirror node, and Hiero Explorer:

cd scripts

task default-with-mirror

This configuration includes:

Access the Explorer at: http://localhost:38080/localnet/dashboard (Solo 0.63+) or http://localhost:8080/localnet/dashboard (Solo 0.62 and earlier). See Port availability if the port is in use.

Deploy Network with Relay and Explorer

Deploy a network with consensus nodes, mirror node, explorer, and JSON-RPC relay for Ethereum-compatible access:

cd scripts

task default-with-relay

This configuration includes:

Access the services at (Solo 0.63+ defaults; for Solo 0.62 and earlier use the legacy ports in parentheses):

• Explorer: http://localhost:38080/localnet/dashboard (legacy: http://localhost:8080/localnet/dashboard)
• JSON-RPC Relay: http://localhost:37546 (legacy: http://localhost:7546)

See Port availability if a port is already in use on your machine.

Available Taskfile Targets

The Taskfile includes a comprehensive set of targets for deploying and managing Solo networks. Below are the most commonly used targets, organized by category.

Core Deployment Targets

These targets handle the primary deployment lifecycle:

Example: Deploy, then clean up

cd scripts

# Deploy the network
task default

# ... (use the network)

# Stop the network
task stop

# Remove all traces of the deployment
task clean

Cache and Log Cleanup

When cleaning up, you can selectively remove specific components:

Mirror Node Management

Add, configure, or remove mirror nodes from an existing deployment:

Example: Add mirror node to running network

cd scripts

# Start with a basic network
task default

# Add mirror node later
task solo:mirror-node

# Remove mirror node
task solo:destroyer-mirror-node

Explorer UI Management

Deploy or remove the Hiero Explorer for transaction/account viewing:

Example: Deploy network with explorer

cd scripts

task default
task solo:explorer

# Access at http://localhost:38080/localnet/dashboard (Solo 0.63+) or http://localhost:8080/localnet/dashboard (Solo 0.62 and earlier)

JSON-RPC Relay Management

Deploy or remove the Relay for Ethereum-compatible access:

Example: Add relay to running network

cd scripts

task default-with-mirror
task solo:relay

# Access JSON-RPC at http://localhost:37546 (Solo 0.63+) or http://localhost:7546 (Solo 0.62 and earlier)

Block Node Management

Deploy or remove block nodes for streaming block data:

Example: Deploy network with block node

cd scripts

task default
task solo:block:add

# Block node will stream block data

Infrastructure Tasks

Low-level tasks for managing clusters and network infrastructure:

Tip: Unless you need custom cluster management, use the higher-level tasks like default, install, or destroy which orchestrate these infrastructure tasks automatically.

Utility Tasks

Helpful tasks for inspecting and managing running networks:

Example: View network IPs and logs

cd scripts

# See which nodes are running and their IPs
task show:ips

# Retrieve node logs for debugging
task solo:node:logs

Database Tasks

Deploy external databases for specialized configurations:

Advanced Configuration with Environment Variables

You can customize Task behavior by setting environment variables before running tasks. Common variables include:

For a comprehensive reference of all available environment variables, see Using Environment Variables.

Example: Deploy with custom versions

cd scripts

# Deploy with specific component versions
CONSENSUS_NODE_VERSION=v0.66.0 \
MIRROR_NODE_VERSION=v0.139.0 \
task default-with-mirror

Example Projects

The Solo repository includes 14+ maintained example projects that demonstrate common Solo workflows. These examples serve as templates and starting points for custom implementations.

Getting Started with Examples

Each example is located in the examples/ directory and includes:

• Pre-configured Taskfile.yml with deployment settings.
• init-containers-values.yaml for customization.
• Example-specific README with detailed instructions.

To run an example:

cd examples/<example-name>

# Deploy the example
task

# Clean up when done
task clean

Available Examples

Network Setup Examples

• Address Book: Use Yahcli to pull ledger and mirror node address books for querying network state
• Network with Domain Names: Setup a network with custom domain names for nodes instead of IP addresses
• Network with Block Node: Deploy a network with block node for streaming block data

Configuration Examples

• Custom Network Config: Customize consensus network configuration for your specific needs
• Local Build with Custom Config: Deploy using a locally-built consensus node with custom configuration
• Consensus Node JVM Parameters: Customize JVM parameters (memory, GC settings, etc.) for consensus nodes

Database Examples

• External Database Test: Deploy Solo with an external PostgreSQL database instead of embedded storage
• Multi-Cluster Backup and Restore: Backup state from one cluster and restore to another using external database

State Management Examples

• State Save and Restore: Save the network state with mirror node, then restore to a new deployment
• Version Upgrade Test: Upgrade all network components to the current version to test compatibility

Node Transaction Examples

These examples demonstrate manual operations for adding, modifying, and removing nodes:

• Node Create Transaction: Create a new node manually using the NodeCreate transaction
• Node Update Transaction: Update an existing node configuration with NodeUpdate transaction
• Node Delete Transaction: Remove a node from the network with NodeDelete transaction

Integration Examples

• Hardhat with Solo: Test smart contracts locally with Hardhat using Solo as the test network
• One-Shot Falcon Deployment: One-shot deployment using Falcon (consensus node implementation)
• One-Shot Local Build: One-shot deployment using a locally-built consensus node

Testing Examples

• Rapid-Fire: Rapid-fire deployment and teardown commands for stress testing the deployment workflow
• Running Solo Inside Cluster: Deploy Solo within an existing Kubernetes cluster instead of creating a new one

Practical Workflows

Workflow 1: Quick Development Network with Logging

Deploy a network for development and debugging:

cd scripts

# Set logging level (PowerShell: $env:SOLO_LOG_LEVEL = 'debug')
export SOLO_LOG_LEVEL=debug

# Deploy with mirror and relay
task default-with-relay

# Retrieve logs if needed
task solo:node:logs

# View network endpoints
task show:ips

# Clean up
task clean

Workflow 2: Test Configuration Changes

Iterate on network configuration:

cd examples/custom-network-config

# Edit the Taskfile or init-containers-values.yaml

# Deploy with your changes
task

# Test your configuration

# Clean up and try again
task clean

Workflow 3: Upgrade Network Components

Test upgrading Solo components:

cd examples/version-upgrade-test

# Deploy with current versions
task

# The example automatically tests the upgrade path

# Clean up
task clean

Workflow 4: Backup and Restore Network State

Test disaster recovery and state migration:

cd examples/state-save-and-restore

# Deploy initial network with state
task

# The example includes backup/restore operations

# Clean up
task clean

Troubleshooting

Common Issues

Task command not found

Ensure Task is installed and on your PATH:

which task
task --version

Taskfile not found

Run Task commands from the scripts/ directory or an examples/ subdirectory where a Taskfile.yml exists:

cd scripts
task default

Insufficient resources

Some deployments require significant resources. Verify your Docker has at least 12 GB of memory and 6 CPU cores allocated:

docker info --format 'CPU: {{.NCPU}}, Memory: {{.MemTotal | div 1000000000}}GB'

Cluster cleanup issues

If the cluster becomes unstable, perform a full cleanup:

cd scripts

# Remove all traces
task clean

# As a last resort, manually delete the Kind cluster
kind delete cluster --name solo-e2e

Next Steps

After deploying a network with Task, explore:

• Using the JavaScript SDK: Interact with your network programmatically
• Using Network Load Generator: Stress test your network
• Environment Variables Reference: Fine-tune deployment behavior
• Solo CI Workflow: Integrate Solo deployments into CI/CD pipelines

Additional Resources

• Task Official Documentation
• Solo Repository
• Hiero Consensus Node
• Hiero Mirror Node
• JSON-RPC Relay

6 - Solo CI Workflow

Overview

This guide walks you through integrating Solo into a GitHub Actions CI pipeline - covering runner requirements, tool installation, and automated network deployment. Each step installs dependencies directly in the workflow, since CI runners are fresh environments with no pre-installed tools.

Prerequisites

Before proceeding, ensure you have completed the following:

• System Readiness — your local environment meets all hardware and software requirements.
• Quickstart — you are familiar with the basic Solo workflow and the solo one-shot single deploy command.

This guide assumes you are integrating Solo into a GitHub Actions workflow where each runner is a fresh environment. The steps below install all required tools directly inside the workflow rather than relying on pre-installed dependencies.

Runner Requirements

Solo requires a minimum of 6 CPU cores and 12 GB of memory on the runner. If these requirements are not met, Solo components may hang or fail to install during deployment.

Note: The Kubernetes cluster does not have full access to all memory available on the host. Setting Docker to 12 GB of memory means the Kind cluster running inside Docker will have access to less than 12 GB. Memory and CPU utilisation also increase over time as transaction load grows. The requirements above are validated for solo one-shot single deploy as documented in this guide.

To verify that your runner meets these requirements, add the following step to your workflow:

  - name: Check Docker Resources
    run: |
      read cpus mem <<<"$(docker info --format '{{.NCPU}} {{.MemTotal}}')"
      mem_gb=$(awk -v m="$mem" 'BEGIN{printf "%.1f", m/1000000000}')
      echo "CPU cores: $cpus"
      echo "Memory: ${mem_gb} GB"

Expected Output:

  CPU cores: 6
  Memory: 12 GB

Step 1: Set Up Kind

Install Kind to create and manage a local Kubernetes cluster in your workflow.

  - name: Setup Kind
    uses: helm/kind-action@a1b0e391336a6ee6713a0583f8c6240d70863de3
    with:
      install_only: true
      node_image: kindest/node:v1.32.2@sha256:3966f21e12b760f6585bde7140cae5e8cdc0e52b37a6f90ce39834b6e72e3f49
      version: v0.29.0
      kubectl_version: v1.32.2
      verbosity: 3
      wait: 120s

Important: Kind version must be v0.29.0 or later and Kubernetes version must be v1.32.2 or later. Solo enforces this minimum version at runtime. Installing an older version will cause deployment failures.

Step 2: Install Node.js

  - name: Set up Node.js
    uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
    with:
      node-version: 22.12.0

Step 3: Install Solo CLI

Install the Solo CLI globally using npm.

Important: Always pin the CLI version. Unpinned installs may pick up breaking changes from newer releases and cause unexpected workflow failures.

  - name: Install Solo CLI
    run: |
      set -euo pipefail
      npm install -g @hiero-ledger/solo@<version>
      solo --version
      kind --version

Step 4: Deploy Solo

Deploy a Solo network to your Kind cluster. This command creates and configures a fully functional local Hiero network, including:

• Consensus Node

• Mirror Node

• Mirror Node Explorer

• JSON-RPC Relay

    - name: Deploy Solo
      env:
        SOLO_CLUSTER_NAME: solo
        SOLO_NAMESPACE: one-shot
        SOLO_CLUSTER_SETUP_NAMESPACE: solo-cluster
        SOLO_DEPLOYMENT: solo-deployment
      run: |
        set -euo pipefail
        kind create cluster -n "${SOLO_CLUSTER_NAME}"
        solo one-shot single deploy | tee solo-deploy.log
  

Resetting Between Tests

If several tests each need a clean genesis ledger, you do not have to redeploy for each one. After deploying once, reset the ledger to genesis between tests to return to a known starting state without recreating the cluster:

  - name: Reset ledger to genesis
    env:
      SOLO_DEPLOYMENT: solo-deployment
    run: |
      set -euo pipefail
      solo ledger system reset --deployment "${SOLO_DEPLOYMENT}"

This is faster than a destroy-and-redeploy cycle. See Reset the ledger to genesis for details and available flags.

Cleanup

After the workflow completes, destroy the Solo deployment and delete the Kind cluster to avoid leaving resources behind.

  - name: Destroy Solo deployment
    env:
      SOLO_DEPLOYMENT: solo-deployment
    run: |
      set -euo pipefail
      solo one-shot single destroy --deployment "${SOLO_DEPLOYMENT}"

  - name: Delete Kind cluster
    env:
      SOLO_CLUSTER_NAME: solo
    run: |
      set -euo pipefail
      kind delete cluster -n "${SOLO_CLUSTER_NAME}"

Complete Example Workflow

The following is the full workflow combining all steps above. Copy this into your .github/workflows/ directory as a starting point.

name: Solo CI Example

on:
  workflow_dispatch:
    inputs:
      solo_version:
        description: 'Solo CLI version to install'
        required: false
        default: '0.69.0'
      kind_version:
        description: 'Kind version to install (minimum v0.29.0)'
        required: false
        default: 'v0.29.0'
      kubectl_version:
        description: 'kubectl version to install (minimum v1.32.2)'
        required: false
        default: 'v1.32.2'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Check Docker Resources
        run: |
          read cpus mem <<<"$(docker info --format '{{.NCPU}} {{.MemTotal}}')"
          mem_gb=$(awk -v m="$mem" 'BEGIN{printf "%.1f", m/1000000000}')
          echo "CPU cores: $cpus"
          echo "Memory: ${mem_gb} GB"
          
      - name: Setup Kind
        uses: helm/kind-action@a1b0e391336a6ee6713a0583f8c6240d70863de3
        with:
          install_only: true
          node_image: kindest/node:v1.32.2@sha256:3966f21e12b760f6585bde7140cae5e8cdc0e52b37a6f90ce39834b6e72e3f49
          version: v0.29.0
          kubectl_version: v1.32.2
          verbosity: 3
          wait: 120s
         
      - name: Set up Node.js
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
        with:
          node-version: 22.12.0
      
      - name: Install Solo CLI
        run: |
          set -euo pipefail
          npm install -g @hiero-ledger/solo@<version>
          solo --version
          kind --version
      
      - name: Deploy Solo
        env:
          SOLO_CLUSTER_NAME: solo
          SOLO_NAMESPACE: one-shot
          SOLO_CLUSTER_SETUP_NAMESPACE: solo-cluster
          SOLO_DEPLOYMENT: solo-deployment
        run: |
          set -euo pipefail
          kind create cluster -n "${SOLO_CLUSTER_NAME}"
          solo one-shot single deploy | tee solo-deploy.log

      - name: Destroy Solo deployment
        env:
          SOLO_DEPLOYMENT: solo-deployment
        run: |
          set -euo pipefail
          solo one-shot single destroy --deployment "${SOLO_DEPLOYMENT}"

      - name: Delete Kind cluster
        env:
          SOLO_CLUSTER_NAME: solo
        run: |
          set -euo pipefail
          kind delete cluster -n "${SOLO_CLUSTER_NAME}"