Run Node from Source
This guide will walk you through deploying an RPC node from the go-flare source code. Building from source gives you more control over the build process and access to the very latest code, but requires managing dependencies manually. Make sure to check the hardware requirements before proceeding.
Prerequisites
- A machine meeting the minimum hardware requirements.
- Go (
1.21.8
) - git
- GCC
- jq
- rsync
- cURL
- Ubuntu (
>=24.10
)
Build the binary
-
Retrieve the source code from the latest stable release:
# 1. Find the latest stable release tag from:
# https://github.com/flare-foundation/go-flare/releases
# 2. Set the tag name in the variable below:
LATEST_TAG="vX.Y.Z" # <-- REPLACE vX.Y.Z WITH THE ACTUAL LATEST TAG e.g. v1.11.0 -
Clone and build the binary:
git clone --branch ${LATEST_TAG} https://github.com/flare-foundation/go-flare.git
cd go-flare/avalanchego
./scripts/build.shThe resulting executable will be stored in
build/avalanchego
. -
Verify the installation by running:
go test $(go list ./... | grep -v /tests/) # avalanchego unit tests
cd ../coreth
go test ./... # coreth unit tests
cd -
Run the node
-
The following command is the simplest way to quickly get your node up and running. The next section explains the parameters used here, along with additional parameters you may wish to configure.
- Flare Mainnet
- Flare Testnet Coston2
- Songbird Canary-Network
- Songbird Testnet Coston
./build/avalanchego --network-id=flare \
--http-host= \
--http-allowed-hosts="*" \
--bootstrap-ips="$(curl -m 10 -sX POST --data '{"jsonrpc":"2.0", "id":1, "method":"info.getNodeIP"}' -H 'content-type:application/json;' https://flare-bootstrap.flare.network/ext/info | jq -r '.result.ip')" \
--bootstrap-ids="$(curl -m 10 -sX POST --data '{"jsonrpc":"2.0", "id":1, "method":"info.getNodeID"}' -H 'content-type:application/json;' https://flare-bootstrap.flare.network/ext/info | jq -r '.result.nodeID')"./build/avalanchego --network-id=costwo \
--http-host= \
--http-allowed-hosts="*" \
--bootstrap-ips="$(curl -m 10 -sX POST --data '{"jsonrpc":"2.0", "id":1, "method":"info.getNodeIP"}' -H 'content-type:application/json;' https://coston2-bootstrap.flare.network/ext/info | jq -r '.result.ip')" \
--bootstrap-ids="$(curl -m 10 -sX POST --data '{"jsonrpc":"2.0", "id":1, "method":"info.getNodeID"}' -H 'content-type:application/json;' https://coston2-bootstrap.flare.network/ext/info | jq -r '.result.nodeID')"./build/avalanchego --network-id=songbird \
--http-host= \
--http-allowed-hosts="*" \
--bootstrap-ips="$(curl -m 10 -sX POST --data '{"jsonrpc":"2.0", "id":1, "method":"info.getNodeIP"}' -H 'content-type:application/json;' https://songbird-bootstrap.flare.network/ext/info | jq -r '.result.ip')" \
--bootstrap-ids="$(curl -m 10 -sX POST --data '{"jsonrpc":"2.0", "id":1, "method":"info.getNodeID"}' -H 'content-type:application/json;' https://songbird-bootstrap.flare.network/ext/info | jq -r '.result.nodeID')"./build/avalanchego --network-id=coston \
--http-host= \
--http-allowed-hosts="*" \
--bootstrap-ips="$(curl -m 10 -sX POST --data '{"jsonrpc":"2.0", "id":1, "method":"info.getNodeIP"}' -H 'content-type:application/json;' https://coston-bootstrap.flare.network/ext/info | jq -r '.result.ip')" \
--bootstrap-ids="$(curl -m 10 -sX POST --data '{"jsonrpc":"2.0", "id":1, "method":"info.getNodeID"}' -H 'content-type:application/json;' https://coston-bootstrap.flare.network/ext/info | jq -r '.result.nodeID')" -
After a lot of log messages the node should start synchronizing with the network, which might take anywhere from a few hours to a few days depending on the chosen network and hardware specification. Node syncing can be stopped at any time. Use the same command to resume the node syncing from where it left off.
You will know your node is fully booted and accepting transactions when the output of this command contain the field
"healthy" : true
in the returned JSON object:curl http://127.0.0.1:9650/ext/health | jq
-
(Optional) If you plan to register your node as a validator. Make sure to copy the staking keys to a persistent directory outside the default location. This is important for ensuring that your staking keys are not lost if the node is restarted or updated.
- Flare Mainnet
- Flare Testnet Coston2
- Songbird Canary-Network
- Songbird Testnet Coston
# Create a dedicated directory
sudo mkdir -p /opt/flare/staking
# Move your keys
sudo mv ~/.avalanchego/staking/staker.key /opt/flare/staking/
sudo mv ~/.avalanchego/staking/staker.crt /opt/flare/staking/# Create a dedicated directory
sudo mkdir -p /opt/coston2/staking
# Move your keys
sudo mv ~/.avalanchego/staking/staker.key /opt/coston2/staking/
sudo mv ~/.avalanchego/staking/staker.crt /opt/coston2/staking/# Create a dedicated directory
sudo mkdir -p /opt/songbird/staking
# Move your keys
sudo mv ~/.avalanchego/staking/staker.key /opt/songbird/staking/
sudo mv ~/.avalanchego/staking/staker.crt /opt/songbird/staking/# Create a dedicated directory
sudo mkdir -p /opt/coston/staking
# Move your keys
sudo mv ~/.avalanchego/staking/staker.key /opt/coston/staking/
sudo mv ~/.avalanchego/staking/staker.crt /opt/coston/staking/
If the node gets stuck during bootstrap (or it takes far longer than the estimates given above), try adding the parameter --bootstrap-retry-enabled=false
when running the node.
CLI parameters
These are some of the most relevant CLI parameters you can use. Read more about them in the Avalanche documentation.
-
--bootstrap-ips
,--bootstrap-ids
: IP address and node ID of the peer used to connect to the rest of the network for bootstrapping. In the run command above, the bootstrap details are programmatically retrieved from the Flare bootstrap nodes upon startup. This is the recommended approach as the bootstrap node's IP and ID can rotate. -
--http-host
: Use--http-host=
(empty) to allow connections from other machines. Otherwise, only connections fromlocalhost
are accepted. -
--http-port
: The port through which the node will listen to API requests. The default value is9650
. -
--http-allowed-hosts
: Use--http-allowed-hosts="*"
to allow connections from any machine. Otherwise, only connections fromlocalhost
are accepted. -
--staking-port
: The port through which the network peers will connect to this node externally. Having this port accessible from the internet is required for correct node operation. The default value is9651
. -
--db-dir
: Directory where the database is stored, defaults to~/.avalanchego/db
. Make sure to use a disk with enough space as recommended in the hardware requirements page. For example, you can use this option to store the database on an external drive. -
--chain-config-dir
: Optional JSON configuration file for using non-default values.
Sample JSON configuration:
{
"snowman-api-enabled": false,
"coreth-admin-api-enabled": false,
"eth-apis": [
"eth",
"eth-filter",
"net",
"web3",
"internal-eth",
"internal-blockchain",
"internal-transaction"
],
"rpc-gas-cap": 50000000,
"rpc-tx-fee-cap": 100,
"pruning-enabled": true, // Set to false for archival nodes, but requires more disk space
"local-txs-enabled": false,
"api-max-duration": 0,
"api-max-blocks-per-request": 0,
"allow-unfinalized-queries": false,
"allow-unprotected-txs": false,
"remote-tx-gossip-only-enabled": false,
"log-level": "info"
}
Update the node
To update your node to a newer version of go-flare:
-
Stop the running node (e.g., using
Ctrl+C
if running in the foreground, or via your service manager likesystemd
). -
Navigate to the source directory:
cd /path/to/go-flare
-
Fetch the latest changes and checkout the new version:
git fetch origin
# 1. Find the latest stable release tag from:
# https://github.com/flare-foundation/go-flare/releases
# 2. Set the tag name in the variable below:
LATEST_TAG="vX.Y.Z" # <-- REPLACE vX.Y.Z WITH THE ACTUAL LATEST TAG e.g. v1.11.0
git checkout ${LATEST_TAG} -
Rebuild the binary:
cd go-flare/avalanchego
./scripts/build.sh -
Restart the node using the same run command and parameters as before.
Troubleshooting
If you encounter issues, here are some common troubleshooting steps.
- Check Peer Count: A node needs sufficient peers (typically at least 16) to sync and operate correctly. Use the health endpoint to check your connection count.
# Check the "connectedPeers" value in the output
curl -s http://127.0.0.1:9650/ext/health | jq -r '.checks.network.message' - Monitor Disk Space: If your node stops syncing, ensure the database location (
/mnt/db
) has enough free space. Rundf -h /mnt/db
to check. - Restart on Errors: If the node becomes unhealthy or you see persistent
GetAcceptedFrontier
errors in the logs, a simple restart can often resolve the issue.