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:

grpcurl -plaintext localhost:8087 blockchain_api.BlockchainAPI.Run

or LegacySync mode:

grpcurl -plaintext localhost:8087 blockchain_api.BlockchainAPI.LegacySync
  • 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

  • Access monitoring dashboard:

    • Open Grafana: http://localhost:3005
    • Login with the default credentials: admin/admin
    • Navigate to the "Teranode - Service Overview" dashboard for key metrics
    • Explore other dashboards for detailed service metrics. For example, you can check the Legacy sync metrics in the "Teranode - Legacy Service" dashboard.

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
  1. Check blockchain sync:
curl http://localhost:8090/api/v1/blockstats
  1. 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:

    • Open http://localhost:3005
    • Navigate to "TERANODE Service Overview"

  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
  1. Check disk usage:
df -h
  1. Restart a specific service:
docker-compose restart blockchain
  1. 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
  1. Get block information:
curl http://localhost:8090/api/v1/block/<blockhash>
  1. 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