Skip to main content

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

Build the binary

  1. 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
  2. Clone and build the binary:

    git clone --branch ${LATEST_TAG} https://github.com/flare-foundation/go-flare.git
    cd go-flare/avalanchego
    ./scripts/build.sh

    The resulting executable will be stored in build/avalanchego.

  3. 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

  1. 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.

    ./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')"
  2. 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
  3. (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.

    # 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/
Node stuck when bootstrapping?

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 from localhost are accepted.

  • --http-port: The port through which the node will listen to API requests. The default value is 9650.

  • --http-allowed-hosts: Use --http-allowed-hosts="*" to allow connections from any machine. Otherwise, only connections from localhost 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 is 9651.

  • --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:

<chain-config-dir>/C/config.json
{
"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:

  1. Stop the running node (e.g., using Ctrl+C if running in the foreground, or via your service manager like systemd).

  2. Navigate to the source directory:

    cd /path/to/go-flare
  3. 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}
  4. Rebuild the binary:

    cd go-flare/avalanchego
    ./scripts/build.sh
  5. 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. Run df -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.