Cheeta ·
I've created a Teranode complete guide so you can try it out too !
Complete Guide: Installing a [[Teranode]] BSV Node for Beginners
Objective: Install and run your own Teranode node on the BSV test network, even if you have no computer science experience.
Estimated time: 2-3 hours
Level: Complete beginner
📋 Table of Contents
Hardware Requirements
Installing Linux on Windows (WSL2)
Installing Docker
Installing Teranode
Starting and Verification
Exploring Your Node
Maintenance and Troubleshooting
1. Hardware Requirements
Before starting, make sure your computer has:
Operating System: Windows 10 version 2004+ or Windows 11
Processor: 4 cores minimum (8 cores recommended)
RAM: 16 GB minimum (32 GB recommended)
Disk Space: 100 GB free space minimum
Internet Connection: Stable and fast
2. Installing Linux on Windows (WSL2)
WSL2 (Windows Subsystem for Linux) allows you to run Linux directly on Windows.
Step 2.1: Enable WSL2
Open PowerShell as administrator:
Click on the Start menu
Type PowerShell
Right-click on "Windows PowerShell"
Click on "Run as administrator"
Copy and paste this command, then press Enter:
wsl --install
Restart your computer when prompted.
Step 2.2: Configure Ubuntu
After restart, Ubuntu will open automatically.
Create your user account:
Enter a username (for example: myname)
Enter a password (⚠️ nothing displays when you type, this is normal)
Confirm the password
Update the system:
sudo apt update && sudo apt upgrade -y
Enter your password when prompted.
Step 2.3: Verify Installation
lsb_release -a
You should see "Ubuntu" and a version number.
3. Installing Docker
Docker is the software that will run your Teranode node.
Step 3.1: Install Prerequisites
Copy these commands one by one:
sudo apt install -y ca-certificates curl gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
Step 3.2: Install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin docker-compose
Step 3.3: Configure Permissions
sudo usermod -aG docker $USER
Close your Ubuntu terminal completely and reopen it.
Step 3.4: Verify Installation
docker --version
docker-compose --version
You should see the versions displayed (e.g., Docker version 24.0.7).
Step 3.5: Increase Docker Memory (IMPORTANT)
sudo nano /etc/wsl.conf
Copy and paste this text:
[wsl2]
memory=16GB
processors=4
swap=8GB
Save:
Press Ctrl + X
Press Y
Press Enter
Restart WSL in PowerShell (Windows):
wsl --shutdown
Wait 10 seconds, then reopen Ubuntu.
4. Installing Teranode
Step 4.1: Create a Working Directory
cd ~
mkdir teranode-setup
cd teranode-setup
Step 4.2: Download Teranode
git clone https://github.com/bsv-blockchain/teranode-teratestnet.git
cd teranode-teratestnet
Step 4.3: Check Contents
ls -la
You should see files like docker-compose.yml and start-teratestnet.sh.
Step 4.4: Install ngrok (optional but recommended)
Ngrok allows other nodes to connect to yours.
Create a free account:
Go to https://ngrok.com
Click on "Sign up"
Create an account (with email and password)
Log in
Get your token:
On the ngrok dashboard, go to "Your Authtoken"
Copy the token (a long string of characters)
Install ngrok:
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt update
sudo apt install ngrok
Configure your token:
ngrok config add-authtoken YOUR_TOKEN_HERE
Replace YOUR_TOKEN_HERE with the token copied from the website.
Verify:
ngrok version
Step 4.5: Free Up Memory
sudo sync
echo 3 | sudo tee /proc/sys/vm/drop_caches
free -h
Check that you have at least 10 GB of available RAM.
5. Starting and Verification
Step 5.1: Run the Configuration Script
cd ~/teranode-setup/teranode-teratestnet
./start-teratestnet.sh
Answer the questions:
"Do you want to use ngrok for external access?"
"Configure RPC credentials - Username:"
"Password:"
"Enable mining?"
The script will now download and start all services. This can take 10-20 minutes.
Step 5.2: Monitor Startup
In a new terminal, open the logs:
cd ~/teranode-setup/teranode-teratestnet
docker-compose logs -f
You'll see many messages scrolling. This is normal!
To stop log display:
Press Ctrl + C
Step 5.3: Verify Everything is Running
docker-compose ps
You should see a list of services with "Up" or "Running" in the STATUS column.
Main services to check:
blockchain
peer
kafka-shared
postgres
kafka-console-shared (Redpanda Console)
grafana
Step 5.4: Fix Memory Issues (if necessary)
If you see memory errors in Aerospike:
docker-compose restart aerospike
Wait 30 seconds, then check again:
docker-compose ps
6. Exploring Yo…