Skip to content

đź–Ą Developer Setup - Pre-requisites and Installation

This guide assists you in setting up the Teranode project on your machine. The below assumes you are running a recent version of Mac OS.

Index

  1. Install Go
  2. Set Go Environment Variables
  3. Python and Dependencies
  4. Clone the Project and Install Dependencies
  5. Configure Settings
  6. Prerequisites for Running the Node
  7. Run the Node
  8. Troubleshooting

1. Install Go

Download and install the latest version of Go. As of October 2025, it's 1.25.2.

Go Installation Guide

Test Installation:

Open a new terminal and execute:

go version

It should display go1.25.2 or above.

2. Set Go Environment Variables

Add these lines to .zprofile or .bash_profile, depending on which one your development machine uses:

export PATH="$PATH:$(go env GOPATH)/bin"
export GOPATH="$(go env GOPATH)"
export GOBIN="$(go env GOPATH)/bin"

Test Configuration:

Open a new terminal and execute:

echo $GOPATH
echo $GOBIN

Both should display paths related to Go.

3. Python and Dependencies

3.1 Install Python (via Homebrew)

brew install python

By default, Homebrew will install Python 3.x and create symlinks like python3 and pip3. You can optionally create a symlink for python and pip if you want shorter commands (but check if they already exist first):

ln -s /opt/homebrew/bin/python3 /opt/homebrew/bin/python  # might already exist
ln -s /opt/homebrew/bin/pip3 /opt/homebrew/bin/pip        # might already exist

Because of PEP 668 and Homebrew’s “externally-managed-environment” setup, you can’t do pip install ... directly into the system-wide Python.

Instead, create and activate a virtual environment:

python3 -m venv ~/my_python_env     # choose any path you like
source ~/my_python_env/bin/activate

After activating, your shell should show something like (my_python_env) as a prefix.

3.3 Install Dependencies Within the Virtual Environment

Once your virtual environment is active, you can safely use pip to install packages without system conflicts:

python -m pip install --upgrade pip
pip install PyYAML

3.4 Verify Installation

python -c "import yaml; print(yaml.__version__)"

This should print out the installed PyYAML version (e.g., 6.0.2 or similar).

If you need PyYAML as part of a standalone command-line tool, you could use pipx instead:

brew install pipx
pipx install PyYAML

However, most Teranode workflows will need PyYAML as a library for scripts, so a virtual environment is usually best.

4. Clone the Project and Install Dependencies

Clone the project:

git clone git@github.com:bsv-blockchain/teranode.git

Install all dependencies:

Execute:

cd teranode

# This will install all required dependencies (protobuf, golangci-lint, etc.)
make install

Note: If you receive an error ModuleNotFoundError: No module named 'yaml' error, refer to this issue for a potential fix. Example:

PYTHONPATH=$HOME/Library/Python/3.9/lib/python/site-packages make install  #Make sure the path is correct for your own python version

5. Configure Settings

Teranode uses two configuration files:

  • settings.conf - Contains sensible defaults for all environments. You should NOT modify this file as part of the scope of this guide.
  • settings_local.conf - Contains developer-specific and deployment-specific settings

5.1 Introducing developer-specific settings in settings_local.conf

  1. In your project directory, create a file settings_local.conf. This file is used for your personal development settings, and it's not tracked in source control.

  2. Introduce any settings override in settings_local.conf that you might require for your development. Use the settings.conf as a reference for common settings and their default values.

  3. The settings you are adding will use a prefix (settings context) that identifies your context. By default, your settings context should be dev.. You can further refine this by using a more specific prefix, such as dev.john or dev.me. However, it is recommended to use the default prefix dev., and only refine it in very specific cases.

In order for your node to read your custom lines, you set SETTINGS_CONTEXT to match the prefix you used (i.e., dev).

In zsh, open ~/.zprofile (or ~/.zshrc). In bash, open ~/.bash_profile (or ~/.bashrc).

Add:

export SETTINGS_CONTEXT=dev

(If you have used a richer prefix, such as dev.john, you would set SETTINGS_CONTEXT=dev.john)

After editing, reload your shell config:

source ~/.zprofile

(or the equivalent for your shell).

5.3 Verify

  1. Echo the environment variable to ensure it's set correctly:
echo $SETTINGS_CONTEXT

Should print dev.

  1. Run or restart your node. Check logs or console output to confirm it's picking up the lines with dev.

6. Prerequisites for Running the Node

6.1 Install OrbStack

Teranode uses Docker containers for running dependencies like Kafka and PostgreSQL. For Mac developers, we recommend using OrbStack - a fast, lightweight Docker Desktop alternative optimized for macOS.

Why OrbStack?

  • Faster: 2-3x faster than Docker Desktop for container startup and file operations
  • Lighter: Uses significantly less CPU and memory
  • Native: Built specifically for macOS with better integration
  • Compatible: Drop-in replacement for Docker Desktop - all Docker commands work the same

Installation:

  1. Download OrbStack from orbstack.dev
  2. Open the downloaded file and drag OrbStack to your Applications folder
  3. Launch OrbStack from your Applications folder
  4. Follow the brief setup wizard

Verify installation:

docker --version

6.2 Start Kafka and PostgreSQL

Once OrbStack is installed and running, start Kafka and PostgreSQL with:

# Start Kafka in Docker
./scripts/kafka.sh

# Start PostgreSQL in Docker
./scripts/postgres.sh

These scripts will set up Docker containers with the required services configured correctly for Teranode.

Note: If you configure your settings to use Aerospike for UTXO storage, you'll also need to run the Aerospike script:

# Start Aerospike in Docker
./scripts/aerospike.sh

7. Run the Node

You can run the entire node with the following command:

SETTINGS_CONTEXT=dev.[YOUR_CONTEXT] go run .

If no errors are seen, you have successfully installed the project and are ready to start working on the project or running the node.

Note that the node is initialized in IDLE mode by default. You'll need to transition it to RUNNING mode to start processing transactions.

7.1. Executing the Teranode-CLI as a Developer

The Teranode-CLI allows you to interact with Teranode services. You can use it to transition the node to different states, query its current state, and perform various maintenance operations. For a comprehensive guide on using the Teranode-CLI as a developer, see the Developer's Guide to Teranode-CLI.

Building the Teranode-CLI

Build the Teranode-CLI tool with:

go build -o teranode-cli ./cmd/teranodecli

Executing Commands

Once built, you can run commands directly:

# Get current FSM state
SETTINGS_CONTEXT=dev.[YOUR_CONTEXT] ./teranode-cli getfsmstate

# Set FSM state to RUNNING
SETTINGS_CONTEXT=dev.[YOUR_CONTEXT] ./teranode-cli setfsmstate --fsmstate running

Available Commands

The Teranode-CLI provides several commands:

Command Description
getfsmstate Get the current FSM State
setfsmstate Set the FSM State (with --fsmstate flag)
settings View system configuration
aerospikereader Read transaction data from Aerospike
filereader Read and process files
seeder Seed initial blockchain data
bitcointoutxoset Convert Bitcoin data to UTXO set
utxopersister Manage UTXO persistence
export-blocks Export blockchain to CSV
import-blocks Import blockchain from CSV
checkblocktemplate Check block template

Getting Help

For general help and a list of available commands:

# General help
./teranode-cli

# Command-specific help
./teranode-cli setfsmstate --help

The CLI will use your development settings as specified by your SETTINGS_CONTEXT environment variable.

Transitioning the Node to RUNNING Mode

To transition the node from IDLE to RUNNING mode, use:

# Get current FSM state
SETTINGS_CONTEXT=dev ./teranode-cli getfsmstate

# Set FSM state to RUNNING
SETTINGS_CONTEXT=dev ./teranode-cli setfsmstate --fsmstate running

After executing these commands, your log should show a successful transition:

[Blockchain Client] FSM successfully transitioned from IDLE to state:RUNNING

7.2. Debugging Teranode

Teranode supports debugging using Delve, the Go debugger. You can use any IDE that supports Delve, including VS Code, GoLand, or the Delve CLI directly.

Local Development Debugging

To debug Teranode during local development:

  1. Build with debug symbols:
DEBUG=true make build

This enables debug flags (-N -l) that disable optimizations and inlining, making debugging easier.

  1. Attach your debugger to the running Teranode process using your preferred IDE or tool.

Remote Debugging (Kubernetes Deployments)

For debugging Teranode running in Kubernetes environments:

  • See the Remote Debug Guide for detailed instructions on:

    • Configuring the Kubernetes cluster for remote debugging
    • Port forwarding the debugger
    • Connecting with VS Code, GoLand, or Delve CLI
    • Debugging multiple services simultaneously

8. Troubleshooting

8.1. Dependency errors and conflicts

Should you have errors with dependencies, try running the following commands:

go clean -cache
go clean -modcache
rm go.sum
go mod tidy
go mod download

This will effectively reset your cache and re-download all dependencies.

Next Steps