Skip to main content
This guide is designed to help node operators run a Celo L2 node with Docker.
Execution client: op-rethThese instructions use op-reth, Celo’s supported execution 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.Support for op-geth has ended, and a node still running it can follow the wrong chain; see End of Support for op-geth. To switch an existing mainnet node, RETH_MIGRATION.md in the compose repository describes running op-reth alongside op-geth on an empty datadir, repointing op-node with --l2.enginekind=reth, and moving traffic over once op-reth reaches the chain tip.

​
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
Storage RequirementsStorage 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.

​
Run Node with Docker

To simplify running nodes, Celo has created the 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.
  1. Pull the latest version of celo-l2-node-docker-compose and cd into the root of the project.
  2. Configure your .env file.

    ​
    Copy default configurations

    The 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.

    ​
    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.
      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.
    Datadirs from op-geth cannot be reusedop-reth uses a different on-disk format. A datadir written by op-geth, including one produced by the L1→L2 migration tool, cannot be used with op-reth. Start from an empty DATADIR_PATH. Pre-L2 historical state is served separately; see Running an archive node.

    ​
    Configure node type

    Your node will run as a full node by default. Set NODE_TYPE=minimal to run on the smallest disk footprint at the cost of historical RPC, or NODE_TYPE=archive to preserve access to all historical state — see Running an archive node. See the Configuration reference for what each tier retains.

    ​
    Configure P2P for external network access

    Network ConfigurationIf 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.
    • 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.
  4. Check the progress of the node as it syncs.
    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.

​
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 codebase is the best reference, and the Network Config & Assets page lists everything you need to participate in the network.

​
Next steps