Skip to main content

Running a Node with Docker

This tutorial will walk you through the process of using Docker to run an BOBA Sepolia node, OP Mainnet node and OP Sepolia node. You can find all Docker Compose files here.

Choose Your Execution Client​

Boba supports multiple execution clients. Pick the one that suits your needs:

Compose FileExecution ClientConsensus ClientStatus
docker-compose-boba-{network}-reth.ymlop-rethop-nodeRecommended
docker-compose-boba-{network}-geth.ymlop-gethop-nodeDeprecated (removal 2026-05-31)

op-reth is the recommended execution client for new deployments. It uses the upstream OP Labs op-reth image. The Boba chain spec is supplied at runtime via a JSON file mounted from boba-community/chainspecs/ — no custom op-reth build is required. See boba-community/chainspecs/README.md for background on why this is required and how to regenerate the chain spec files.

Prerequisites​

Setup​

Clone the boba repository to get started

git clone https://github.com/bobanetwork/boba.git
cd boba
cd boba-community

Configuration​

Configuration for the docker-compose is handled through environment variables inside of an .env file.

Create an .env file​

The repository includes a sample environment variable file located at .env.example that you can copy and modify to get started. Make a copy of this file and name it .env.

cp .env.example .env

Configure the .env file​

Open the .env in your directory and set the variables inside. Read the descriptions of each variable to understand what they do and how to set them. Read the software release page to set the correct version.

DB Configuration​

Create a Shared Secret (JWT Token)​

openssl rand -hex 32 > jwt-secret.txt

Download Snapshots​

Download the database snapshot for the client and network you wish to run. Always verify snapshots by comparing the sha256sum of the downloaded file to the sha256sum listed on the snapshot downloads page.

sha256sum <filename>

  • BOBA Mainnet

    curl -o boba-mainnet-reth-db-20260526.tar.zst -sL https://boba-db.s3.us-east-2.amazonaws.com/mainnet/boba-mainnet-reth-db-20260526.tar.zst

  • BOBA Sepolia

    curl -o boba-sepolia-reth-db-20260526.tar.zst -sL https://boba-db.s3.us-east-2.amazonaws.com/sepolia/boba-sepolia-reth-db-20260526.tar.zst

Extract the snapshot into a reth-data directory:

mkdir -p reth-data
tar --zstd -xf boba-{network}-reth-db-initial.tar.zst -C reth-data

These snapshots contain a pre-initialized reth database built from the op-geth state at the Bedrock migration block (block 1149019 for mainnet, block 511 for sepolia). No manual init-state step is needed — just extract and run. To regenerate the database from scratch, see the migration guide.

Set the DATA_DIR in your .env to point to this directory (or leave it blank to use the default ./reth-data).

op-geth (Deprecated)​

Deprecated: op-geth support ends 2026-05-31. Migrate to op-reth.

See the snapshot downloads page for available geth snapshots.

Extract geth snapshots:

tar xvf data.tgz

Modify Volume Location​

The volumes of l2 and op-node should be modified to your file locations.

l2:
  volumes:
    - ./jwt-secret.txt:/config/jwt-secret.txt
    - DATA_DIR:/db
op-node:
  volumes:
  	- ./jwt-secret.txt:/config/jwt-secret.txt

Run the Node​

Once you've configured your .env file, you can run the node using Docker Compose.

# BOBA Mainnet
docker compose -f docker-compose-boba-mainnet-reth.yml up -d

# BOBA Sepolia
docker compose -f docker-compose-boba-sepolia-reth.yml up -d

op-geth (Deprecated — removal 2026-05-31)​

# BOBA Sepolia
docker compose -f docker-compose-boba-sepolia-geth.yml up -d

# BOBA Mainnet
docker compose -f docker-compose-boba-mainnet-geth.yml up -d

Operating the Node​

Start​

docker-compose -f [docker-compose-file] up -d

Will start the node in a detatched shell (-d), meaning the node will continue to run in the background.

View Logs​

docker-compose logs -f --tail 10

To view logs of all containers.

docker-compose logs <CONTAINER_NAME> -f --tail 10

Stop​

docker-compose -f [docker-compose-file] down

Wipe [DANGER]​

docker-compose -f [docker-compose-file] down -v