Docker

There are two ways to obtain a Reth Docker image:

GitHub
Building it from source

Once you have obtained the Docker image, proceed to Using the Docker image.

Note

Reth requires Docker Engine version 20.10.10 or higher due to missing support for the clone3 syscall in previous versions.

GitHub

Reth docker images for both x86_64 and ARM64 machines are published with every release of reth on GitHub Container Registry.

You can obtain the latest image with:

docker pull ghcr.io/paradigmxyz/reth

Or a specific version (e.g. v0.0.1) with:

docker pull ghcr.io/paradigmxyz/reth:v0.0.1

You can test the image with:

docker run --rm ghcr.io/paradigmxyz/reth --version

If you can see the latest Reth release version, then you've successfully installed Reth via Docker.

Building the Docker image

To build the image from source, navigate to the root of the repository and run:

docker build . -t reth:local

The build will likely take several minutes. Once it's built, test it with:

docker run reth:local --version

Using the Docker image

There are two ways to use the Docker image:

Using Docker
Using Docker Compose

Using Plain Docker

To run Reth with Docker, run:

docker run \
    -v rethdata:/root/.local/share/reth/mainnet \
    -d \
    -p 9001:9001 \
    -p 30303:30303 \
    -p 30303:30303/udp \
    --name reth \
    reth:local \
    node \
    --metrics 0.0.0.0:9001

The above command will create a container named reth and a named volume called rethdata for data persistence. It will also expose the 30303 port (TCP and UDP) for peering with other nodes and the 9001 port for metrics.

It will use the local image reth:local. If you want to use the GitHub Container Registry remote image, use ghcr.io/paradigmxyz/reth with your preferred tag.

Using Docker Compose

To run Reth with Docker Compose, run the following command from a shell inside the root directory of this repository:

./etc/generate-jwt.sh
docker compose -f etc/docker-compose.yml -f etc/lighthouse.yml up -d

Note

If you want to run Reth with a CL that is not Lighthouse:

The JWT for the consensus client can be found at etc/jwttoken/jwt.hex in this repository, after the etc/generate-jwt.sh script is run

The Reth Engine API is accessible on localhost:8551

To check if Reth is running correctly, run:

docker compose -f etc/docker-compose.yml -f etc/lighthouse.yml logs -f reth

The default docker-compose.yml file will create three containers:

Reth
Prometheus
Grafana

The optional lighthouse.yml file will create two containers:

Lighthouse
ethereum-metrics-exporter

Grafana will be exposed on localhost:3000 and accessible via default credentials (username and password is admin), with two available dashboards:

reth
Ethereum Metrics Exporter (works only if Lighthouse is also running)

Interacting with Reth inside Docker

To interact with Reth you must first open a shell inside the Reth container by running:

docker exec -it reth bash

If Reth is running with Docker Compose, replace reth with reth-reth-1 in the above command

Refer to the CLI docs to interact with Reth once inside the Reth container.

Run only Grafana in Docker

This allows importing existing Grafana dashboards, without running Reth in Docker.

docker compose -f etc/docker-compose.yml up -d --no-deps grafana

After login with admin:admin credentials, Prometheus should be listed under Grafana datasources. Replace its Prometheus server URL so it points to locally running one. On Mac or Windows, use http://host.docker.internal:9090. On Linux, try http://172.17.0.1:9090.

reth Book