How to Set Up a Base Node Using Docker: A Complete Guide

Deploy a Base node by running two Docker services—an execution client (reth, geth, or nethermind) and the OP-Node—using Docker Compose with environment files for mainnet or Sepolia testnet.

Setting up a Base node using Docker provides a streamlined way to run the Layer 2 infrastructure without complex manual builds. The base/node repository orchestrates the deployment through Docker Compose, coordinating an execution client with the Optimism rollup node to sync with the Base network.

Understanding the Base Node Docker Architecture

The Base node architecture consists of two distinct Docker services that run side-by-side:

• execution – The execution client responsible for processing transactions and maintaining the EVM state. The default client is reth, with geth and nethermind available as alternatives.
• node – The Optimism OP-Node that handles rollup consensus, derivation, and P2P networking.

Both services share configuration through environment variables defined in .env.mainnet or .env.sepolia files. The docker-compose.yml file orchestrates these services, pulling the appropriate client Dockerfile via the CLIENT build argument and establishing a private Docker network for inter-container communication.

Key architectural files include:

File	Purpose
docker-compose.yml	Orchestrates the two services, ports, volumes, and environment files
.env.mainnet / .env.sepolia	Network-specific configuration for L1 RPCs and node settings
reth/Dockerfile	Builds the Reth client and bundles the OP-Node binary
geth/Dockerfile	Builds the Geth client and bundles the OP-Node binary
op-node-entrypoint	Entry script that waits for the execution client, resolves public IP, writes JWT auth, and starts OP-Node
reth/reth-entrypoint	Client-specific startup script for Reth

Configuring Environment Variables

Before starting the node, you must configure the .env file with your L1 Ethereum RPC endpoints. The repository provides templates for both mainnet (.env.mainnet) and Sepolia testnet (.env.sepolia).

Required environment variables include:

• OP_NODE_L1_ETH_RPC – Your preferred L1 Ethereum RPC endpoint
• OP_NODE_L1_BEACON – Your preferred L1 Beacon API endpoint
• OP_NODE_L1_BEACON_ARCHIVER – Archiver endpoint for historical beacon data

Additional variables control sync mode, engine RPC settings, metrics endpoints, and optional features such as snapshots or Flashblocks. The entrypoint scripts (op-node-entrypoint and client-specific entrypoints) consume these variables to configure the node at runtime.

Step-by-Step Docker Deployment

Running a Mainnet Node with Default Reth

To start a Base mainnet node using the default Reth execution client:

# Clone the repository

git clone https://github.com/base/node.git
cd node

# Build and launch the node (uses .env.mainnet automatically)

docker compose up --build

The docker-compose.yml automatically loads .env.mainnet and builds the Reth client via reth/Dockerfile.

Connecting to Sepolia Testnet

To run a node on the Base Sepolia testnet:

# Override the environment file with the Sepolia configuration

NETWORK_ENV=.env.sepolia docker compose up --build

This instructs Docker Compose to use .env.sepolia instead of the default mainnet configuration.

Selecting Alternative Execution Clients

You can switch from the default Reth client to Geth or Nethermind using the CLIENT environment variable:

# Use Geth instead of the default Reth

CLIENT=geth docker compose up --build

# Or use Nethermind

CLIENT=nethermind docker compose up --build

The docker-compose.yml passes this variable as a build argument to select the appropriate Dockerfile (e.g., geth/Dockerfile or reth/Dockerfile).

Combining Testnet and Specific Client Selection

You can combine network and client selection in a single command:

NETWORK_ENV=.env.sepolia CLIENT=geth docker compose up --build

Persisting Blockchain Data

To prevent data loss when containers restart, mount a host directory to the /data volume:

# Export a host path, e.g., $HOME/base-data

export HOST_DATA_DIR=$HOME/base-data
docker compose up --build

The docker-compose.yml defines this mount as:

volumes:
  - ${HOST_DATA_DIR}:/data

This ensures chain data survives container restarts and updates.

Summary

• The Base node consists of two Docker services: an execution client (reth, geth, or nethermind) and the OP-Node for rollup consensus.
• Configuration happens through .env.mainnet or .env.sepolia, requiring L1 RPC endpoints (OP_NODE_L1_ETH_RPC, OP_NODE_L1_BEACON).
• Use docker compose up --build to start the node, with NETWORK_ENV to select testnet and CLIENT to switch execution clients.
• Data persistence requires mounting a host directory to /data via HOST_DATA_DIR.

Frequently Asked Questions

What execution clients are supported for running a Base node?

The Base node Docker setup supports three execution clients: reth (the default), geth, and nethermind. You select your preferred client by setting the CLIENT environment variable before running Docker Compose. The docker-compose.yml passes this value as a build argument to pull the corresponding Dockerfile (e.g., reth/Dockerfile or geth/Dockerfile).

How do I switch between Base mainnet and Sepolia testnet?

To run on Sepolia testnet instead of mainnet, set the NETWORK_ENV environment variable to .env.sepolia before executing Docker Compose. For example: NETWORK_ENV=.env.sepolia docker compose up --build. By default, the compose file uses .env.mainnet for mainnet configuration.

What are the required environment variables for L1 connectivity?

You must configure three critical L1 RPC endpoints in your .env file: OP_NODE_L1_ETH_RPC for the L1 Ethereum RPC, OP_NODE_L1_BEACON for the L1 Beacon API, and OP_NODE_L1_BEACON_ARCHIVER for historical beacon data access. The op-node-entrypoint script consumes these variables to establish communication with Ethereum L1 and authenticate via JWT.

How do I persist chain data when restarting the Docker containers?

Mount a host directory to the container's /data path using the HOST_DATA_DIR environment variable. For example, run export HOST_DATA_DIR=$HOME/base-data before docker compose up --build. The docker-compose.yml defines this volume mapping as ${HOST_DATA_DIR}:/data, ensuring that blockchain data survives container restarts and image updates.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}