logoDocumentation

Manually

Learn how to run an Avalanche node manually.

The quickest way to learn about Avalanche is by running a node and interacting with the network.

In this tutorial, we will:

  • Install AvalancheGo and run an Avalanche node
  • Connect to Avalanche

Hardware and OS Requirements

Avalanche is an incredibly lightweight protocol, so nodes can run on commodity hardware. Note that as network usage increases, hardware requirements may change.

  • CPU: Equivalent of 8 AWS vCPU
  • RAM: 16 GiB
  • Storage: 1 TiB SSD
  • OS: Ubuntu 20.04 or MacOS >= 12

Please do not try running a node on an HDD, as you may get poor and random read/write latencies, therefore reducing performance and reliability.

Run an Avalanche Node from Source

The following steps walk through downloading the AvalancheGo source code and locally building the binary program.

Install Dependencies

Build and Start

1. Set the $GOPATH

2. Create a directory in your $GOPATH

mkdir -p $GOPATH/src/github.com/ava-labs

3. Clone AvalancheGo

In the $GOPATH, clone AvalancheGo, the consensus engine and node implementation that is the core of the Avalanche Network.

cd $GOPATH/src/github.com/ava-labs
git clone https://github.com/ava-labs/avalanchego.git

4. Run the Build Script

From the avalanchego directory, run the build script

cd $GOPATH/src/github.com/ava-labs/avalanchego
./scripts/build.sh

5. Start the Node

On Avalanche Mainnet:

cd $GOPATH/src/github.com/ava-labs/avalanchego
./build/avalanchego

On Fuji Testnet:

cd $GOPATH/src/github.com/ava-labs/avalanchego
./build/avalanchego --network-id=fuji
Note

To kill the node, press Ctrl + C.

Run with a Pre-Built Binary

To download a pre-built binary instead of building from source, go to the AvalancheGo releases page, and select the desired version.

Download

Under Assets, select the appropriate file.

MacOS

Download: avalanchego-macos-<VERSION>.zip

Unzip:

unzip avalanchego-macos-<VERSION>.zip

the resulting folder, avalanchego-<VERSION>, contains the binaries.

Linux(PCs or Cloud Providers)

Download: avalanchego-linux-amd64-<VERSION>.tar.gz

Unzip:

tar -xvf avalanchego-linux-amd64-<VERSION>.tar.gz

The resulting folder, avalanchego-<VERSION>-linux, contains the binaries.

Linux(Arm64)

Download: avalanchego-linux-arm64-<VERSION>.tar.gz

Unzip:

tar -xvf avalanchego-linux-arm64-<VERSION>.tar.gz

The resulting folder, avalanchego-<VERSION>-linux, contains the binaries.

Start the Node

MacOS

Avalanche Mainnet:

./avalanchego-<VERSION>/build/avalanchego

Fuji Testnet:

./avalanchego-<VERSION>/build/avalanchego --network-id=fuji

Linux

Avalanche Mainnet:

./avalanchego-<VERSION>-linux/avalanchego

Fuji Testnet:

./avalanchego-<VERSION>-linux/avalanchego --network-id=fuji

Run with Docker

See the AvalancheGo GitHub repository for more information.

Networking

To run successfully, AvalancheGo needs to accept connections from the Internet on the network port 9651. Before you proceed with the installation, you need to determine the networking environment your node will run in.

Note

To be able to make API calls to your node from other machines, include the argument --http-host= when starting the node.

Bootstrapping

A new node needs to catch up to the latest network state before it can participate in consensus and serve API calls. This process (called bootstrapping) currently takes several days for a new node connected to Mainnet, and a day or so for a new node connected to Fuji Testnet. When a given chain is done bootstrapping, it will print logs like this:

[09-09|17:01:45.295] INFO <C Chain> snowman/transitive.go:392 consensus starting {"lastAcceptedBlock": "2qaFwDJtmCCbMKP4jRpJwH8EFws82Q2yC1HhWgAiy3tGrpGFeb"}
[09-09|17:01:46.199] INFO <P Chain> snowman/transitive.go:392 consensus starting {"lastAcceptedBlock": "2ofmPJuWZbdroCPEMv6aHGvZ45oa8SBp2reEm9gNxvFjnfSGFP"}
[09-09|17:01:51.628] INFO <X Chain> snowman/transitive.go:334 consensus starting {"lenFrontier": 1}

Check Bootstrapping Progress

To check if a given chain is done bootstrapping, in another terminal window call info.isBootstrapped by copying and pasting the following command:

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

If this returns true, the chain is bootstrapped; otherwise, it returns false. If you make other API calls to a chain that is not done bootstrapping, it will return API call rejected because chain is not done bootstrapping. If you are still experiencing issues please contact us on Discord.

Note

The 3 chains will bootstrap in the following order: P-chain, X-chain, C-chain.

Learn more about bootstrapping here.

RPC

When finished bootstrapping, the X, P, and C-Chain RPC endpoints will be:

localhost:9650/ext/bc/P
localhost:9650/ext/bc/X
localhost:9650/ext/bc/C/rpc

if run locally, or

XXX.XX.XX.XXX:9650/ext/bc/P
XXX.XX.XX.XXX:9650/ext/bc/X
XXX.XX.XX.XXX:9650/ext/bc/C/rpc

if run on a cloud provider. The “XXX.XX.XX.XXX" should be replaced with the public IP of your EC2 instance.

For more information on the requests available at these endpoints, please see the AvalancheGo API Reference documentation.

Going Further

Your Avalanche node will perform consensus on its own, but it is not yet a validator on the network. This means that the rest of the network will not query your node when sampling the network during consensus. If you want to add your node as a validator, check out Add a Validator to take it a step further.

Also check out the Maintain section to learn about how to maintain and customize your node to fit your needs.

To track an Avalanche L1 with your node, head to the Avalanche L1 Node tutorial.

Last updated on

On this page

Edit on Github