Skip to main content
This guide uses Kona’s pre-packaged docker config.For detailed usage of the kona-node binary, head over to the binary guide. To run an op-node + op-reth stack with Docker instead, see Running a Node With Docker.
Kona provides a kona-node docker recipe with detailed instructions for running a complete node setup.

​
Quick Start

The easiest way to run kona-node with Docker is using the provided recipe:
  1. Navigate to the recipe directory:
  2. Configure environment variables: Edit cfg.env to set your L1 RPC endpoints:
  3. Start the services:
This will start:
  • kona-node - The OP Stack node implementation
  • op-reth - Execution layer client
  • prometheus - Metrics collection
  • grafana - Monitoring dashboards (accessible at http://localhost:3000)

​
Docker Compose

In the provided docker compose, there are a few services aside from the kona-node and op-reth. These are prometheus and grafana which automatically come provisioned with dashboards for monitoring and insight into the kona-node and op-reth services. For more detail into how Prometheus and Grafana work, head over to the Monitoring docs. The docker-compose.yaml uses published images from GitHub Container Registry:
  • op-reth: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-reth:develop
  • kona-node: us-docker.pkg.dev/oplabs-tools-artifacts/images/kona-node:develop

​
Service Configuration

​
kona-node Service

The kona-node service is configured with the following key settings:
  • Ports:
    • 5060 - RPC endpoint
    • 9223 - P2P discovery (TCP/UDP)
    • 9002 - Metrics
  • Environment: L1 RPC and Beacon API endpoints are required
  • Volumes: Persistent data storage and JWT token for engine API authentication

​
op-reth Service

The op-reth service provides the execution layer:
  • Ports:
    • 8545 - HTTP RPC
    • 8551 - Engine API (authenticated)
    • 30303 - P2P discovery
    • 9001 - Metrics
  • Configuration: Pre-configured for OP Sepolia testnet

​
Configuration

​
Network Selection

By default, the recipe is configured for OP Sepolia. To sync a different OP Stack chain:
  1. Set appropriate L1 endpoints for your target network in cfg.env
  2. Modify the docker-compose.yaml:
    • Update op-reth --chain parameter
    • Update op-reth --rollup.sequencer-http endpoint
    • Update kona-node --chain parameter

​
RPC Trust Configuration

By default, kona-node trusts RPC providers (both L1 and L2). When using public or untrusted RPC endpoints, you should disable trust to enable block hash verification:
Or modify the docker-compose.yaml command:
See configure RPC trust for more details on RPC trust settings.

​
Port Configuration

All host ports can be customized via environment variables in cfg.env:

​
Logging

Adjust log levels by setting the RUST_LOG environment variable:

​
Management Commands

The recipe includes convenient Just commands:

​
Getting the kona-node Image

The recipe pulls published kona-node and op-reth images automatically. Use this section when you want to pull or build the kona-node image yourself, for example to pin a release version or test local changes.

​
Pulling a published image

Kona docker images are published with every release on GitHub Container Registry. You can obtain the latest kona-node image with:
Specify a specific version (e.g. v0.1.0) like so.
You can test the image with:
If you can see the latest release version, then you’ve successfully installed Kona via Docker.

​
Building the Docker image

To build the image from source, navigate to the root of the kona directory in the monorepo and run:
This will create an image with the tag kona:local. To specify a custom tag, just pass it in after kona-node in the command above, like so:
The build will likely take several minutes. Once it’s built, test it with:
To use the locally built image with the recipe, update docker-compose.yaml to use kona:local instead of the published image.