Why Docker?

BuilderHub hosted nodes are convenient, but they don't allow direct access to configuration files. To perform network upgrades (like disabling/enabling precompiles), you need to:

Edit the upgrade.json file in the node's config directory
Restart the node to apply changes

This requires running your own validator with full access to the filesystem.

Important: Your Docker validator will become the primary node for this exercise. Make sure you have Docker installed and running on your machine.

Prerequisites

Before starting, ensure you have:

Docker installed and running
Your Blockchain ID from the L1 you created earlier
Your Subnet ID from the L1 you created earlier

Instructions

Step 1: Launch Docker Validator

Use the tool below to run a self-hosted AvalancheGo node in Docker:

Interactive exercise

Builder Console

L1 Node Setup with Docker

Configure your node settings, select your L1, and run Docker to start your node.

Configure Node Settings
Choose your network, node type, and settings. The config preview updates as you go.
Network
Node type
Log level · info is the default
Min block delay2000ms
0ms (fastest)1000ms2000ms (default)
Minimum time between blocks. Lower is faster blocks but more network load.
Storage
Enable Pruning
Removes old state data to cut disk usage. Savings depend on your L1's transaction volume. Recommended for validators and pruned RPC nodes.
Enable State Sync
Bootstraps from a recent state snapshot instead of replaying every block from genesis. Recommended for faster initial sync.
API
Enable Admin API
Enables administrative APIs. Only enable if needed and secured.
Configuration Preview
Subnet-EVM config.json
Configure your node to see the Subnet-EVM chain config
Storage Requirements
Mainnet · estimate
Initial
240GB
Growth
+12GB/mo
After 1 yr
384GB
1.2TB0
Now6mo1yr
Your config
Archival (1.2TB)
Pruning ONState SyncTX Index
Set up Instance
Provision a server with these specs.
CPU4 vCPU
RAM8 GB
Storage~200 GB Mainnet
Open ports9651 P2P
Port 9651 is P2P and 9650 is RPC. For a production L1, run 5+ validator nodes across regions. A single node is fine for local dev and quick demos.

Docker Installation

Make sure you have Docker installed on your system. You can use the following commands to install it:

# Install Docker using convenience script
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker

# Test installation
docker run -it --rm hello-world

# Install Docker using convenience scriptcurl -fsSL https://get.docker.com -o get-docker.shsudo sh get-docker.shsudo usermod -aG docker $USERnewgrp docker# Test installationdocker run -it --rm hello-world

Not using Docker? Follow the manual installation instructions.

Select L1
Enter the Subnet ID of the L1 you want to run a node for.
Subnet ID
No L1 selected
Enter a Subnet ID to generate the config files and Docker command.

The tool will generate the Docker command with the correct configuration for your L1.

Step 2: Verify the Node is Running

Check that your container is running:

docker ps

You should see a container running AvalancheGo.

Step 3: Verify Bootstrap Status

Run this check in a terminal on the Docker host, not inside the container. The container image does not include curl, and the Docker command publishes port 9650 on the host.

Check if your chain is bootstrapped:

curl -X POST --data '{
  "jsonrpc":"2.0",
  "id":1,
  "method":"info.isBootstrapped",
  "params": {
    "chain":"YOUR_BLOCKCHAIN_ID"
  }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info

Replace YOUR_BLOCKCHAIN_ID with your L1's blockchain ID. You should see:

{"jsonrpc":"2.0","result":{"isBootstrapped":true},"id":1}

Step 4: Connect Core Wallet

Add your L1's RPC to Core Wallet:

RPC URL: http://localhost:9650/ext/bc/YOUR_BLOCKCHAIN_ID/rpc
Chain ID: Your L1's chain ID

Verify you can see your balance and send transactions.

Expected Output

You should have:

A running Docker container with AvalancheGo
Your L1 chain bootstrapped and producing blocks
Core Wallet connected to your local node

What You Can Now Do

With your own Docker validator, you can:

Access the node's config directory at ~/.avalanchego/configs/chains/<BLOCKCHAIN_ID>/
Create and modify upgrade.json files
Restart the node to apply network upgrades

Next Steps

Now that your Docker validator is running, you'll learn the rules for creating network upgrades.

Set Up Docker Validator

Why Docker?

Prerequisites

Instructions

Step 1: Launch Docker Validator

L1 Node Setup with Docker

Configure Node Settings

Configuration Preview

Storage Requirements

Set up Instance