> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celo.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Running a Celo Node with Docker

This guide is designed to help node operators run a Celo L2 node with Docker.

<Info>
  **Execution client: op-reth**

  These instructions use `op-reth`, the execution client Celo is adopting as its primary client. A fresh node starts from an empty datadir and bootstraps from a published snapshot (required on mainnet) or, on Celo Sepolia, syncs from genesis — no L1 data migration required.

  `op-geth` remains supported until your network's switch date — see the **Still running op-geth?** notes at the end of this guide, and [End of Support for op-geth](/infra-partners/notices/op-geth-deprecation) for the switch dates.
</Info>

## Recommended Hardware

### Mainnet

* 16GB+ RAM
* 1TB+ SSD (NVME Recommended)
* Minimum 4 CPU, recommended 8 CPU
* 100mb/s+ Download

### Celo Sepolia Testnet

* 16GB+ RAM
* 500GB SSD (NVME Recommended)
* Minimum 4 CPU, recommended 8 CPU
* 100mb/s+ Download

<Warning>
  **Storage Requirements**

  Storage size requirements will increase over time, especially for archive nodes.

  If running an archive node, please make sure you also have enough storage for the legacy Celo L1 archive datadir. See [Running an archive node](/infra-partners/operators/archive-node).
</Warning>

## Run Node with Docker

To simplify running nodes, Celo has created the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) repository with all the necessary configuration files and docker compose templates to make running a Celo L2 node easy.

### Running a Full Node

Follow these steps to run a full node. If you would like to run an archive node, see [Running an archive node](/infra-partners/operators/archive-node).

1. Pull the latest version of [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) and `cd` into the root of the project.

   ```bash theme={null}
   git clone https://github.com/celo-org/celo-l2-node-docker-compose.git
   cd celo-l2-node-docker-compose
   ```

2. Configure your `.env` file.

   #### Copy default configurations

   The [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) repo contains a `<network>.env` file for each Celo network (`celo-sepolia`, `mainnet`). Start by copying the default configuration for the appropriate network.

   ```bash theme={null}
   export NETWORK=<celo-sepolia or mainnet>
   cp $NETWORK.env .env
   ```

   #### Bootstrap your datadir

   `op-reth` syncs by executing every block. A new node starts from an **empty** datadir, populated in one of two ways depending on your network:

   * **From a snapshot.** Set `OP_RETH__SNAPSHOT=true` in `.env`. On first start with an empty datadir, your node downloads a recent published snapshot (from `snapshots.celo.org`) and continues from there. Once the datadir holds data, the snapshot step is skipped.

     ```text theme={null}
     OP_RETH__SNAPSHOT=true
     ```

     **On mainnet a snapshot is required** — it provides the pre-L2 (Celo L1) history, which `op-reth` cannot reproduce by executing blocks.

   * **From genesis.** On **Celo Sepolia**, which has no pre-L2 history, you can leave `OP_RETH__SNAPSHOT=false` (the default) and execute every block from genesis. This needs no external data but takes considerably longer to reach the chain tip.

   <Warning>
     **Datadirs from op-geth cannot be reused**

     `op-reth` uses a different on-disk format. A datadir written by `op-geth` — including one produced by the [L1→L2 migration](/infra-partners/operators/migrate-node) — cannot be used with `op-reth`. Start from an empty `DATADIR_PATH`. Pre-L2 historical state is served separately; see [Running an archive node](/infra-partners/operators/archive-node).
   </Warning>

   #### Configure node type

   Your node will run as a `full` node by default, but can also be configured as an `archive` node if you wish to preserve access to all historical state. See [Running an archive node](/infra-partners/operators/archive-node) for more information.

   #### Configure P2P for external network access

   <Warning>
     **Network Configuration**

     If the following options are not configured correctly, your node will not be discoverable or reachable to other nodes on the network. This is likely to impair your node's ability to stay reliably connected to and synced with the network.
   </Warning>

   * `OP_NODE__P2P_ADVERTISE_IP` - Specifies the public IP to be shared via discovery so that other nodes can connect to your node. If unset, other nodes on the network will not be able to discover and connect to your op-node.
   * `PORT__OP_NODE_P2P` - Specifies the port to be shared via discovery so that other nodes can connect to your node. Defaults to 9222.
   * `OP_RETH__NAT` - Controls how op-reth determines its public IP that is shared via the discovery mechanism. If the public IP is not correctly configured then other nodes on the network will not be able to discover and connect to your node. The default value of `any` will try to automatically determine the public IP, but the most reliable approach is to explicitly set the public IP using `extip:<your-public-ip>`. Other acceptable values are `(any|none|upnp|publicip|extip:<IP>|stun:<IP:PORT>)`.
   * `PORT__OP_RETH_P2P` - Specifies the port to be shared via discovery so that other nodes can connect to your node. Defaults to 30303.

3. Start the node.

   ```bash theme={null}
   docker compose up -d --build
   ```

4. Check the progress of the node as it syncs.

   ```bash theme={null}
   docker compose logs -n 50 -f op-reth
   ```

   This will display and follow the last 50 lines of logs. As the node syncs you will see `op-reth` executing blocks and its head advancing toward the network's latest block.

5. Check that node is fully synced.

   You can validate that your node is following the network by fetching the current block number via the RPC API and seeing that it climbs as the node syncs and then tracks the network's latest block.

   ```bash theme={null}
   cast block-number --rpc-url http://localhost:9993
   ```

<Accordion title="Still running op-geth? (until your switch date)">
  Until your network's [switch date](/infra-partners/notices/op-geth-deprecation), you can keep running `op-geth` from an existing checkout of [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) (the latest version runs `op-reth` only). The steps above are the same, with these differences:

  * **Sync mode instead of a snapshot.** `op-geth` starts with `snap` sync by default, which downloads pre-hardfork block data from peers — no migrated L1 datadir required. To run `full` sync against a migrated L1 datadir instead, set:

    ```text theme={null}
    OP_GETH__SYNCMODE=full
    DATADIR_PATH=<path to a migrated L1 datadir>
    ```

  * **P2P variables.** Use `OP_GETH__NAT` (values `any|none|upnp|pmp|pmp:<IP>|extip:<IP>|stun:<IP:PORT>`) and `PORT__OP_GETH_P2P` (default `30303`) in place of their `OP_RETH__` equivalents.

  * **Logs.** Follow `docker compose logs -n 50 -f op-geth`. A syncing node shows `Syncing beacon headers downloaded=...` and later `"Syncing: chain download in progress","synced":"21.07%"`; until fully synced the RPC API returns `0` for the head block number.

  After your network's switch date, `op-geth` will no longer follow the chain — migrate to `op-reth` before then.
</Accordion>

## Build from source

Docker images are the easiest way to run a Celo node, but you can also build from source — for example to run on a specific architecture or to inspect the code. The [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) codebase is the best reference, and the [Network Config & Assets](/infra-partners/operators/network-config) page lists everything you need to participate in the network.

## Next steps

* [Run an archive node](/infra-partners/operators/archive-node) — preserve access to all historical state.
* [Network Config & Assets](/infra-partners/operators/network-config) — bootnodes, container images, and downloadable artifacts.
* [Troubleshooting](/infra-partners/operators/troubleshooting) — fixes for common node issues, plus how to get help.