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

> Easily deploy a Base node using Docker Compose. This guide details setting up your execution client and OP-Node for mainnet or Sepolia testnet.

- Repository: [Base/node](https://github.com/base/node)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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`](https://github.com/base/node/blob/main/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`](https://github.com/base/node/blob/main/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:

```bash

# 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`](https://github.com/base/node/blob/main/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:

```bash

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

```bash

# 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`](https://github.com/base/node/blob/main/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:

```bash
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:

```bash

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

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

```

The [`docker-compose.yml`](https://github.com/base/node/blob/main/docker-compose.yml) defines this mount as:

```yaml
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`](https://github.com/base/node/blob/main/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`](https://github.com/base/node/blob/main/docker-compose.yml) defines this volume mapping as `${HOST_DATA_DIR}:/data`, ensuring that blockchain data survives container restarts and image updates.