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:8080

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:

• Explorer: http://localhost:8080
• JSON-RPC Relay: http://localhost:7546

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:8080

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:7546

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:

| Task | Description |\n| ————————— | ———————————————————- | | cluster:create | Create a Kind (Kubernetes in Docker) cluster | | cluster:destroy | Delete the Kind cluster | | solo:cluster:setup | Setup cluster infrastructure and prerequisites | | solo:init | Initialize Solo (download tools and templates) | | solo:deployment:create | Create a new deployment configuration | | solo:deployment:attach | Attach an existing cluster to a deployment | | solo:network:deploy | Deploy the consensus network to the cluster | | solo:network:destroy | Destroy the consensus network |

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
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