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.
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
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
Your Teranode Docker Compose setup will include:
-
Core Teranode Services
- Asset Server
- Block Assembly
- Block Validation
- Blockchain
- Legacy Gateway
- P2P
- Propagation
- Subtree Validation
-
Optional Services
- Block Persister
- UTXO Persister
-
Supporting Services
- Kafka for message queuing
- PostgreSQL for blockchain data
- Aerospike for UTXO storage
- Grafana and Prometheus for monitoring
- Checkout the Teranode public repository:
cd $YOUR_WORKING_DIR
git clone git@github.com:bsv-blockchain/teranode.git
cd teranode- Go to the testnet docker compose path:
cd $YOUR_WORKING_DIR/teranode/deploy/docker/testnet- Pull required images:
docker compose pull- Launch all services:
docker compose up -dForce the node to transition to Run mode:
# Access the dashboard at http://localhost:8090/admin (default credentials bitcoin:bitcoin)
# Navigate to FSM State section and select RUNNING or LEGACYSYNCINGNote: 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 monitorFor comprehensive dashboard documentation, see Dashboard Documentation.
# 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- Check service health:
curl http://localhost:8090/health-
Access the built-in Teranode dashboard:
- Service Viewer: http://localhost:8090/viewer - View blocks, transactions, UTXOs, and subtrees
- Admin Interface: http://localhost:8090/admin (credentials: bitcoin/bitcoin) - FSM state management and block operations
- Home Overview: http://localhost:8090/home - Node statistics and block graphs
- Peer Management: http://localhost:8090/peers - Connected peers and reputation scores
- Network Status: http://localhost:8090/network - Connected nodes and chain status
- For complete dashboard features, see Dashboard Documentation
-
Access Grafana monitoring (metrics and time-series data):
- Open Grafana: http://localhost:3005
- Login with the default credentials: admin/admin
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.
-
Services fail to start
- Check logs:
docker compose logs - Verify disk space:
df -h - Ensure all ports are available
- Check logs:
-
Cannot connect to services
- Verify services are running:
docker compose ps - Check service logs for specific errors
- Ensure ports are not blocked by firewall
- Verify services are running:
-
View all services status:
docker compose ps
-
Check blockchain sync:
curl http://localhost:8090/api/v1/blockstats
-
Monitor specific service logs:
docker compose logs -f legacy docker compose logs -f blockchain docker compose logs -f asset
-
Get transaction details:
curl http://localhost:8090/api/v1/tx/<txid>
-
Access Grafana dashboards:
- Open http://localhost:3005
- Navigate to "TERANODE Service Overview"
-
Key metrics to watch:
- Block queue length (should be near 0)
- Transaction processing rate
- Memory and CPU usage
- Disk space utilization
-
View logs:
# All services docker compose logs # Specific service docker compose logs blockchain
-
Check disk usage:
df -h
-
Restart a specific service:
docker compose restart blockchain
-
Restart all services:
docker compose down docker compose up -d
-
Check current block height:
curl http://localhost:8090/api/v1/bestblockheader/json
-
Get block information:
curl http://localhost:8090/api/v1/block/<blockhash>
-
Check UTXO status:
curl http://localhost:8090/api/v1/utxo/<utxohash>
- Explore the How-to Guides for advanced tasks
- Review the Reference documentation for detailed endpoint information