Skip to content

Getting Started with Teranode

Index

Introduction

This tutorial will guide you through your first steps with Teranode using Docker Compose. By the end of this guide, you'll have a running testnet Teranode instance suitable for testing and development.

Prerequisites

Before you begin, ensure you have:

  • Basic understanding of blockchain technology
  • Familiarity with command-line operations
  • The AWS CLI
  • Docker Engine 17.03+
  • Docker Compose
  • The Teranode Docker Compose file
  • 100GB+ available disk space
  • Stable internet connection

What is Teranode?

Teranode is a scalable Bitcoin SV node implementation that:

  • Processes over 1 million transactions per second
  • Uses a microservices architecture
  • Maintains full Bitcoin protocol compatibility

Components Overview

Your Teranode Docker Compose setup will include:

  1. Core Teranode Services

    • Asset Server
    • Block Assembly
    • Block Validation
    • Blockchain
    • Legacy Gateway
    • P2P
    • Propagation
    • Subtree Validation

  2. Optional Services

    • Block Persister
    • UTXO Persister

  3. Supporting Services

    • Kafka for message queuing
    • PostgreSQL for blockchain data
    • Aerospike for UTXO storage
    • Grafana and Prometheus for monitoring

First-Time Setup

Step 1: Prepare Your Environment

  • Checkout the Teranode public repository:
cd $YOUR_WORKING_DIR
git clone git@github.com:bsv-blockchain/teranode.git
cd teranode

Step 2: Initial Setup

  • Go to the testnet docker compose path:
cd $YOUR_WORKING_DIR/teranode/deploy/docker/testnet
  • Pull required images:
docker compose pull

Step 3: Start Teranode

  • Launch all services:
docker compose up -d

Force the node to transition to Run mode:

Option 1: Using Admin Dashboard (Easiest)

# Access the dashboard at http://localhost:8090/admin (default credentials bitcoin:bitcoin)
# Navigate to FSM State section and select RUNNING or LEGACYSYNCING

Note: The embedded dashboard is only available when Teranode is built with dashboard support (default in Docker images). The dashboard provides:

  • /admin - FSM management, block invalidation/revalidation (requires authentication)
  • /viewer - Blockchain viewer (blocks, transactions, UTXOs, subtrees)
  • /home - Node overview and statistics
  • /peers - Peer management and reputation
  • /network - Network status and connected nodes
  • /p2p - P2P message monitor

For comprehensive dashboard documentation, see Dashboard Documentation.

Option 2: Using teranode-cli

# Transition to Run mode
docker exec -it blockchain teranode-cli setfsmstate --fsmstate RUNNING

# Or transition to LegacySync mode
docker exec -it blockchain teranode-cli setfsmstate --fsmstate LEGACYSYNCING
  • Verify services are running:
docker compose ps
  • Check individual service logs:
# Example commands
docker compose logs asset
docker compose logs blockchain
  • Verify legacy sync status:

When the node is started for the first time, its first action is to perform a initial blockchain sync. You can check the sync progress by checking the Legacy service logs:

docker compose logs legacy

Step 4: Verify Installation

  • Check service health:
curl http://localhost:8090/health

Note: The docker compose configuration in this repository includes Grafana but does not include pre-configured Teranode dashboards. You will see an empty Grafana instance that can collect metrics but won't have the "Teranode" folder with pre-built service dashboards.

For a complete deployment with pre-configured Grafana dashboards (Teranode Service Overview, Legacy Service metrics, etc.), use the teranode-teratestnet repository which includes:

  • Pre-built Grafana dashboards for all Teranode services
  • Automated setup and configuration
  • Production-ready monitoring visualization

You can also manually create custom dashboards in Grafana by connecting to the Prometheus data source at http://prometheus:9090.

Common Issues

  1. Services fail to start

    • Check logs: docker compose logs
    • Verify disk space: df -h
    • Ensure all ports are available

  2. Cannot connect to services

    • Verify services are running: docker compose ps
    • Check service logs for specific errors
    • Ensure ports are not blocked by firewall

Basic Operations

Checking Node Status

  1. View all services status:

    docker compose ps

  2. Check blockchain sync:

    curl http://localhost:8090/api/v1/blockstats

  3. Monitor specific service logs:

    docker compose logs -f legacy
docker compose logs -f blockchain
docker compose logs -f asset

Working with Transactions

  1. Get transaction details:

    curl http://localhost:8090/api/v1/tx/<txid>

Monitoring Your Node

  1. Access Grafana dashboards:

  2. Key metrics to watch:

    • Block queue length (should be near 0)
    • Transaction processing rate
    • Memory and CPU usage
    • Disk space utilization

Basic Maintenance

  1. View logs:

    # All services
docker compose logs

# Specific service
docker compose logs blockchain

  2. Check disk usage:

    df -h

  3. Restart a specific service:

    docker compose restart blockchain

  4. Restart all services:

    docker compose down
docker compose up -d

Common Operations

  1. Check current block height:

    curl http://localhost:8090/api/v1/bestblockheader/json

  2. Get block information:

    curl http://localhost:8090/api/v1/block/<blockhash>

  3. Check UTXO status:

    curl http://localhost:8090/api/v1/utxo/<utxohash>

Next Steps

  • Explore the How-to Guides for advanced tasks
  • Review the Reference documentation for detailed endpoint information

Docker Compose Setup

  1. Installation Guide
  2. Starting and Stopping Teranode
  3. Configuration Guide
  4. Blockchain Synchronization
  5. Update Procedures
  6. Troubleshooting Guide
  7. Security Best Practices

Kubernetes Deployment

  1. Installation with Kubernetes Operator
  2. Starting and Stopping Teranode
  3. Configuration Guide
  4. Blockchain Synchronization
  5. Update Procedures
  6. Backup Procedures
  7. Troubleshooting Guide
  8. Security Best Practices
  9. Remote Debugging Guide