Skip to main content

Run Node using Docker

This guide will walk you through deploying an RPC node using the go-flare images on Docker Hub.

Prerequisites​

Docker without sudo

To run docker commands without sudo, add your user to the docker group:

sudo usermod -a -G docker $USER

Log out and log back in or restart your system for the changes to take effect.

Configure the machine​

First, you'll prepare your host machine by setting up a dedicated disk for blockchain data and creating necessary configuration directories.

Disk setup​

Blockchain data requires significant storage, so it's best practice to use a separate, dedicated disk. These steps will guide you through formatting and mounting it.

  1. Define environment variables: To prevent errors, define the device name and your current user as variables. This avoids having to manually replace placeholders in every command.

    # Identify your disk with `lsblk`, then set it here.
    # ⚠️ DANGER: The device you choose will be completely erased!
    DISK_DEVICE="/dev/sdb"

    # Set the user and group for directory ownership.
    DOCKER_USER=$(whoami)

  2. Format and mount the disk: The following commands will create a directory at /mnt/db, format your disk, mount it, and grant your user ownership.

    Data Loss

    The mkfs.ext4 command will erase all data on the specified device ($DISK_DEVICE). Double-check that you've selected the correct disk and backed up any important data.

    # See a list of available block devices to identify the correct one.
    lsblk

    # Create mount point and set permissions
    sudo mkdir -p /mnt/db
    sudo chown -R ${DOCKER_USER}:${DOCKER_USER} /mnt/db

    # Format the disk (EXT4 filesystem)
    sudo mkfs.ext4 -m 0 -E lazy_itable_init=0,lazy_journal_init=0,discard ${DISK_DEVICE}

    # Mount the disk
    sudo mount ${DISK_DEVICE} /mnt/db

  3. Ensure persistent mounting: To ensure the disk is automatically mounted after a system reboot, add an entry to /etc/fstab. Using the disk's UUID is a robust method because device names like /dev/sdb can sometimes change.

    # Back up your current fstab file
    sudo cp /etc/fstab /etc/fstab.backup

    # Get the UUID of your newly formatted disk
    DISK_UUID=$(sudo blkid -o value -s UUID ${DISK_DEVICE})

    # Add the new entry to /etc/fstab
    echo "UUID=${DISK_UUID} /mnt/db ext4 discard,defaults 0 2" | sudo tee -a /etc/fstab

    # Verify the mount
    sudo mount -a
    lsblk | grep /mnt/db

Configuration File and Logs Directory Setup​

Create directories on your host machine to store the node's configuration file and logs. Mounting these allows you to manage them directly without entering the container.

  1. Create directories:

    sudo mkdir -p /opt/flare/conf /opt/flare/logs
    sudo chown -R ${DOCKER_USER}:${DOCKER_USER} /opt/flare

  2. Create configuration file: Create a config.json file. This example provides a standard configuration for a public RPC node.

    /opt/flare/conf/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,
      "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"
    }

Run the node​

You can run your node using either the Docker CLI directly or with Docker Compose for easier management.

Using Docker CLI​

  1. Get the latest stable version tag:

    # 1. Find the latest stable release tag from:
    #    https://hub.docker.com/r/flarefoundation/go-flare/tags
    # 2. Set the tag name in the variable below (only use versioned tags):
    LATEST_TAG="vX.Y.Z" # <-- REPLACE vX.Y.Z WITH THE ACTUAL LATEST TAG e.g. v1.11.0

  2. Start the container:

    docker run -d --name flare-node \
      -e NETWORK_ID="flare" \
      -e AUTOCONFIGURE_BOOTSTRAP="1" \
      -e AUTOCONFIGURE_PUBLIC_IP="1" \
      -e AUTOCONFIGURE_BOOTSTRAP_ENDPOINT="https://flare-bootstrap.flare.network/ext/info" \
      -v /mnt/db:/app/db -v /opt/flare/conf:/app/conf/C \
      -v /opt/flare/logs:/app/logs \
      -p 0.0.0.0:9650:9650 \
      -p 0.0.0.0:9651:9651 \
      flarefoundation/go-flare:${LATEST_TAG}

    Confirm your container is running and inspect that logs are printing:

    docker ps
    docker logs flare-node -f

  3. Check health: Once the node is running, you can check its health. It will report "healthy": true only after it has fully synced.

    # Press Ctrl+C to exit the logs, then run:
    curl http://localhost:9650/ext/health | jq

  4. (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
    docker cp flare-node:/root/.avalanchego/staking /opt/flare/staking
Explanation of the CLI arguments.

Volumes Mounts

  • -v /mnt/db:/app/db: Mount the local database directory to the default database directory of the container.
  • -v /opt/flare/conf:/app/conf/C: Mount the local configuration directory to the default location of config.json.
  • -v /opt/flare/logs:/app/logs: Mount the local logs directory to the workloads default logs directory.

Port Mappings

  • -p 0.0.0.0:9651:9651: Mapping the container's peering port to your local machine so other peers can reach the node and allow it to gain peers on the network.

  • -p 0.0.0.0:9650:9650: Mapping the container's HTTP port to your local machine, enabling the querying of the containerized RPC node's HTTP port via your local machine's IP and port.

    warning

    Only expose port 9650 with 0.0.0.0 to make your node's RPC endpoint publicly accessible. If you need external access, it is critical to implement firewall rules that restrict access to specific, trusted IP addresses.

Environment Variables

  • -e AUTOCONFIGURE_BOOTSTRAP="1": Retrieves the bootstrap endpoints Node-IP and Node-ID automatically.
  • -e NETWORK_ID="<network>": Sets the correct network ID, either flare, costwo, songbird, or coston.
  • -e AUTOCONFIGURE_PUBLIC_IP="1": Retrieves your local machine's public IP automatically.
  • -e AUTOCONFIGURE_BOOTSTRAP_ENDPOINT="<bootstrap_host>/ext/info": Defines the bootstrap endpoint used to initialize chain sync, a list of them is available on the Network Configuration page.

Using Docker Compose​

Docker Compose simplifies node management by defining the entire configuration in a single YAML file.

  1. Create a Workspace: In this guide the docker-compose.yaml file is created in /opt/node but the location is entirely up to you.

    sudo mkdir /opt/node
    sudo chown -R ${DOCKER_USER}:${DOCKER_USER} /opt/node

  2. Create the docker-compose.yaml file:

    /opt/node/docker-compose.yaml
    services:
      node:
        container_name: flare-node
        # 1. Find the latest stable release tag from:
        #    https://hub.docker.com/r/flarefoundation/go-flare/tags
        # 2. Set the tag name in the variable below (only use versioned tags):
        image: flarefoundation/go-flare:vX.Y.Z # <-- REPLACE vX.Y.Z WITH THE ACTUAL LATEST TAG e.g. v1.11.0
        restart: on-failure
        environment:
          - NETWORK_ID=flare
          - AUTOCONFIGURE_BOOTSTRAP=1
          - AUTOCONFIGURE_PUBLIC_IP=1
          - AUTOCONFIGURE_BOOTSTRAP_ENDPOINT=https://flare-bootstrap.flare.network/ext/info
        volumes:
          - /mnt/db:/app/db
          - /opt/flare/conf:/app/conf/C
          - /opt/flare/logs:/app/logs
        ports:
          - 0.0.0.0:9650:9650
          - 0.0.0.0:9651:9651

  3. Start the service: Navigate to your workspace and launch the node in detached mode.

    cd /opt/node
    docker compose up -d

  4. Monitor logs and check health:

    Check the status of your service and follow its logs.

    docker ps
    docker compose logs -f

    Check the health endpoint to confirm it's running and accessible.

    # Press Ctrl+C to exit the logs, then run:
    curl -s http://localhost:9650/ext/health | jq

  5. (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
    docker compose cp flare-node:/root/.avalanchego/staking /opt/flare/staking
Additional configuration options

There are several environment variables to adjust your workload at runtime. The example Docker and Docker Compose guides above assumed some defaults and utilized built-in automation scripts for most of the configuration. Outlined below are all options available:

Variable NameDefaultDescription
NETWORK_IDcostwoThe network ID to connect to
HTTP_HOST0.0.0.0HTTP host binding address
HTTP_PORT9650The listening port for the HTTP host
STAKING_PORT9651The staking port for bootstrapping nodes
PUBLIC_IP(empty)Public facing IP. Must be set if AUTOCONFIGURE_PUBLIC_IP=0
DB_DIR/app/dbThe database directory location
DB_TYPEleveldbThe database type to be used
BOOTSTRAP_IPS(empty)A list of bootstrap server IPs
BOOTSTRAP_IDS(empty)A list of bootstrap server IDs
CHAIN_CONFIG_DIR/app/confConfiguration folder where you should mount your configuration file
LOG_DIR/app/logsLogging directory
LOG_LEVELinfoLogging verbosity level that is logged into the file
AUTOCONFIGURE_PUBLIC_IP0Set to 1 to autoconfigure PUBLIC_IP, skipped if PUBLIC_IP is set
AUTOCONFIGURE_BOOTSTRAP0Set to 1 to autoconfigure BOOTSTRAP_IPS and BOOTSTRAP_IDS
AUTOCONFIGURE_BOOTSTRAP_ENDPOINThttps://coston2-bootstrap.flare.network/ext/infoEndpoint used for bootstrapping when AUTOCONFIGURE_BOOTSTRAP=1
AUTOCONFIGURE_FALLBACK_ENDPOINTS(empty)Comma-divided fallback bootstrap endpoints if the primary endpoint fails
EXTRA_ARGUMENTS(empty)Extra arguments passed to flare binary

Update the node​

Keep your node up-to-date with the latest stable release of go-flare for security and performance improvements.

  1. Find the latest stable tag from the go-flare Docker Hub tags page.

  2. Stop and remove the old container:

    docker stop flare-node # Or coston2-node, songbird-node, coston-node
    docker rm flare-node

  3. Update the LATEST_TAG to the new stable tag and run the same docker run command as previously detailed. Your data in /mnt/db (or your chosen volume) will be preserved.

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.
    • Docker CLI: docker restart <container_name>
    • Docker Compose: cd /opt/node && docker compose restart