# Run Node using Docker

> Run a Flare node using Docker.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

Source: https://dev.flare.network/run-node/using-docker

This guide will walk you through deploying an RPC node using the [go-flare](https://hub.docker.com/r/flarefoundation/go-flare) images on Docker Hub.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

-   A machine meeting the [minimum hardware requirements](/run-node/system-requirements).
-   [Docker Engine](https://docs.docker.com/engine/install/)
-   [jq](https://stedolan.github.io/jq/download/)

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[​](#configure-the-machine "Direct link to 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[​](#disk-setup "Direct link to 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 permissionssudo mkdir -p /mnt/dbsudo 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 disksudo 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 filesudo cp /etc/fstab /etc/fstab.backup# Get the UUID of your newly formatted diskDISK_UUID=$(sudo blkid -o value -s UUID ${DISK_DEVICE})# Add the new entry to /etc/fstabecho "UUID=${DISK_UUID} /mnt/db ext4 discard,defaults 0 2" | sudo tee -a /etc/fstab# Verify the mountsudo mount -alsblk | grep /mnt/db
    ```
    

### Configuration File and Logs Directory Setup[​](#configuration-file-and-logs-directory-setup "Direct link to 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/logssudo 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. Most of the C-Chain configuration options can be found in the [Avalanche C-Chain Configuration docs](https://build.avax.network/docs/nodes/chain-configs/avalanche-l1s/subnet-evm). Note that the default values are overridden only if specified in the given config file. Only provide values which differ from the defaults to avoid issues with future updates.
    
    /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[​](#run-the-node "Direct link to Run the node")

You can run your node using either the [Docker CLI](#using-docker-cli) directly or with [Docker Compose](#using-docker-compose) for easier management.

### Using Docker CLI[​](#using-docker-cli "Direct link to 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.12.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 psdocker logs flare-node -f
    ```
    
    ```
    docker run -d --name coston2-node \  -e NETWORK_ID="costwo" \  -e AUTOCONFIGURE_BOOTSTRAP="1" \  -e AUTOCONFIGURE_PUBLIC_IP="1" \  -e AUTOCONFIGURE_BOOTSTRAP_ENDPOINT="https://coston2-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 psdocker logs coston2-node -f
    ```
    
    ```
    docker run -d --name songbird-node \  -e NETWORK_ID="songbird" \  -e AUTOCONFIGURE_BOOTSTRAP="1" \  -e AUTOCONFIGURE_PUBLIC_IP="1" \  -e AUTOCONFIGURE_BOOTSTRAP_ENDPOINT="https://songbird-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 psdocker logs songbird-node -f
    ```
    
    ```
    docker run -d --name coston-node \  -e NETWORK_ID="coston" \  -e AUTOCONFIGURE_BOOTSTRAP="1" \  -e AUTOCONFIGURE_PUBLIC_IP="1" \  -e AUTOCONFIGURE_BOOTSTRAP_ENDPOINT="https://coston-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 psdocker logs coston-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](/run-node/register-validator). Make sure to copy the staking keys to a persistent directory outside the default location. Consider also backing up these keys to a secure vault of your choice. This is important for ensuring that your staking keys are not lost if the node is restarted or updated.
    
    ```
    # Create a dedicated directorysudo mkdir -p /opt/flare/staking# Move your keysdocker cp flare-node:/root/.avalanchego/staking /opt/flare/staking
    ```
    
    ```
    # Create a dedicated directorysudo mkdir -p /opt/coston2/staking# Move your keysdocker cp coston2-node:/root/.avalanchego/staking /opt/coston2/staking
    ```
    
    ```
    # Create a dedicated directorysudo mkdir -p /opt/songbird/staking# Move your keysdocker cp songbird-node:/root/.avalanchego/staking /opt/songbird/staking
    ```
    
    ```
    # Create a dedicated directorysudo mkdir -p /opt/coston/staking# Move your keysdocker cp coston-node:/root/.avalanchego/staking /opt/coston/staking
    ```
    

<details>
<summary>Explanation of the CLI arguments.</summary>

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](/network/overview#configuration) page.

</details>

### Using Docker Compose[​](#using-docker-compose "Direct link to 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/nodesudo 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.12.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
    ```
    
    /opt/node/docker-compose.yaml
    
    ```
    services:  node:    container_name: coston2-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.12.0    restart: on-failure    environment:      - NETWORK_ID=costwo      - AUTOCONFIGURE_BOOTSTRAP=1      - AUTOCONFIGURE_PUBLIC_IP=1      - AUTOCONFIGURE_BOOTSTRAP_ENDPOINT=https://coston2-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
    ```
    
    /opt/node/docker-compose.yaml
    
    ```
    services:  node:    container_name: songbird-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.12.0    restart: on-failure    environment:      - NETWORK_ID=songbird      - AUTOCONFIGURE_BOOTSTRAP=1      - AUTOCONFIGURE_PUBLIC_IP=1      - AUTOCONFIGURE_BOOTSTRAP_ENDPOINT=https://songbird-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
    ```
    
    /opt/node/docker-compose.yaml
    
    ```
    services:  node:    container_name: coston-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.12.0    restart: on-failure    environment:      - NETWORK_ID=coston      - AUTOCONFIGURE_BOOTSTRAP=1      - AUTOCONFIGURE_PUBLIC_IP=1      - AUTOCONFIGURE_BOOTSTRAP_ENDPOINT=https://coston-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/nodedocker compose up -d
    ```
    
4.  **Monitor logs and check health:**
    
    Check the status of your service and follow its logs.
    
    ```
    docker psdocker 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](/run-node/register-validator). Make sure to copy the staking keys to a persistent directory outside the default location. Consider also backing up these keys to a secure vault of your choice. This is important for ensuring that your staking keys are not lost if the node is restarted or updated.
    
    ```
    # Create a dedicated directorysudo mkdir -p /opt/flare/staking# Move your keysdocker compose cp flare-node:/root/.avalanchego/staking /opt/flare/staking
    ```
    
    ```
    # Create a dedicated directorysudo mkdir -p /opt/coston2/staking# Move your keysdocker compose cp coston2-node:/root/.avalanchego/staking /opt/coston2/staking
    ```
    
    ```
    # Create a dedicated directorysudo mkdir -p /opt/songbird/staking# Move your keysdocker compose cp songbird-node:/root/.avalanchego/staking /opt/songbird/staking
    ```
    
    ```
    # Create a dedicated directorysudo mkdir -p /opt/coston/staking# Move your keysdocker compose cp coston-node:/root/.avalanchego/staking /opt/coston/staking
    ```
    

<details>
<summary>Additional configuration options</summary>

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 Name**

**Default**

**Description**

`NETWORK_ID`

`costwo`

The network ID to connect to

`HTTP_HOST`

`0.0.0.0`

HTTP host binding address

`HTTP_PORT`

`9650`

The listening port for the HTTP host

`STAKING_PORT`

`9651`

The staking port for bootstrapping nodes

`PUBLIC_IP`

(empty)

Public facing IP. Must be set if `AUTOCONFIGURE_PUBLIC_IP=0`

`DB_DIR`

`/app/db`

The database directory location

`DB_TYPE`

`leveldb`

The 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/conf`

Configuration folder where you should mount your configuration file

`LOG_DIR`

`/app/logs`

Logging directory

`LOG_LEVEL`

`info`

Logging verbosity level that is logged into the file

`AUTOCONFIGURE_PUBLIC_IP`

`0`

Set to 1 to autoconfigure `PUBLIC_IP`, skipped if `PUBLIC_IP` is set

`AUTOCONFIGURE_BOOTSTRAP`

`0`

Set to 1 to autoconfigure `BOOTSTRAP_IPS` and `BOOTSTRAP_IDS`

`AUTOCONFIGURE_BOOTSTRAP_ENDPOINT`

`https://coston2-bootstrap.flare.network/ext/info`

Endpoint 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

</details>

## Update the node[​](#update-the-node "Direct link to 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](https://hub.docker.com/r/flarefoundation/go-flare/tags).
    
2.  Stop and remove the old container:
    
    ```
    docker stop flare-node # Or coston2-node, songbird-node, coston-nodedocker rm flare-node
    ```
    
3.  Update the `LATEST_TAG` to the new stable tag and run the same `docker run` command as [previously detailed](/run-node/using-docker#using-docker-cli). Your data in `/mnt/db` (or your chosen volume) will be preserved.
    

1.  Find the latest stable tag from the go-flare Docker Hub [tags page](https://hub.docker.com/r/flarefoundation/go-flare/tags).
    
2.  Stop the old container:
    
    ```
    docker compose -f /opt/node/docker-compose.yaml down
    ```
    
3.  Update the `docker-compose.yaml` file with the new tag and start the new container:
    
    ```
    LATEST_TAG="vX.Y.Z" # <-- Replace with the actual latest tag e.g v1.12.0yq -i ".services.node.image = flarefoundation/go-flare:${LATEST_TAG}" /opt/node/docker-compose.yamldocker compose -f /opt/node/docker-compose.yaml up -d
    ```
    

## Troubleshooting[​](#troubleshooting "Direct link to 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 outputcurl -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`