Skip to main content
This guide is designed to help node operators run a Celo L2 node with Docker.
L1 to L2 data migrationIf you wish to migrate data from a Celo L1 node and have not yet done so, please see the migration guide before continuing. Alternatively, you can snap sync from scratch without migrating existing L1 data.
Execution client: op-geth today, op-reth nextThese instructions use op-geth. Celo is transitioning to op-reth as the primary execution client ahead of the Ethereum Glamsterdam hardfork; op-geth remains fully supported until then. See End of Support for op-geth for the transition timeline.

​
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. 
    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 repo contains a <network>.env file for each Celo network (celo-sepolia, mainnet). Start by copying the default configuration for the appropriate network. 
    export NETWORK=<celo-sepolia or mainnet>
cp $NETWORK.env .env

    ​
    Configure sync mode

    By default, celo-l2-node-docker-compose will start your node with snap sync. This allows your node to start without a migrated L1 datadir, as pre-hardfork block data will be automatically downloaded from peers during syncing. This is the easiest way to start an L2 node. Alternatively, you can start your node with full sync if you have a migrated L1 datadir. For instructions on obtaining a migrated L1 datadir, please see Migrating an L1 Node. To use full sync, configure .env as follows: 
    OP_GETH__SYNCMODE=full
DATADIR_PATH=<path to a migrated L1 datadir>

    ​
    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. Note that full has a different meaning here than in the context of syncing. See Running an archive node for more information.

    ​
    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 op-node other nodes on the network will not be able to discover and connect to your 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_GETH__NAT - Controls how op-geth 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|pmp|pmp:<IP>|extip:<IP>|stun:<IP:PORT>).
    • PORT__OP_GETH_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. 
    docker-compose up -d --build
  4. Check the progress of the node as it syncs. 
    docker-compose logs -n 50 -f op-geth
    This will display and follow the last 50 lines of logs. In a syncing node, you would expect to see Syncing beacon headers downloaded=... where the downloaded number is increasing and later lines such as "Syncing: chain download in progress","synced":"21.07%" where the percentage is increasing. Once the percentage reaches 100%, the node should be synced.
  5. Check that node is fully synced. Once the node is fully synced, you can validate that it’s following the network by fetching the current block number via the RPC API and seeing that it’s increasing as expected. 
    cast block-number --rpc-url http://localhost:9993
    Note that until fully synced, the RPC API will return 0 for the head block number.

​
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