fiftysix/teku repository overview

⁠Fiftysix Teku Docker Image

Maintainer: [email protected]⁠

⁠Overview

This Docker image provides a fully functional Teku client built using the Fiftysix base image. Teku is an Ethereum consensus (beacon) client maintained by Consensys, containing a full beacon node and validator client implementation. It connects to the Ethereum P2P network, tracks the beacon chain, and works together with a paired execution client to keep a full Ethereum node in sync. It is ideal for developers, blockchain enthusiasts, and institutions looking to participate in the Ethereum network. The code can be viewed on the Fiftysix Github⁠.

⁠Tags

• latest: Points to the latest version of Teku.
• <version>: Points to a specific version of Teku. For example, 26.9.0.

⁠What is Teku?

Teku is an Ethereum consensus client implemented in Java, built and maintained by Consensys. It operates as a beacon node in Ethereum's Proof of Stake (PoS) network, implementing the consensus protocol, tracking validator duties, and communicating with a paired execution client over the authenticated Engine API. Following the merge⁠, a consensus client like Teku is required alongside an execution client (such as Reth, Geth, Erigon, Besu, or Nethermind) to run a complete Ethereum node.

⁠Usage

⁠Prerequisites

Teku cannot run standalone. To run Teku effectively, you'll need a paired Ethereum execution client (such as Reth, Geth, Erigon, Besu, or Nethermind) already running, and the exact same JWT secret the execution client generated (at <execution client's data dir>/jwt.hex) shared into the Teku container - Teku must never generate its own. See the execution/consensus pairing notes⁠ for the full mechanism.

⁠Basic Usage

To run a Teku node paired with an execution client already running on the same Docker network as reth-node:

docker pull fiftysix/teku
docker run --name teku -d \
  -v /path/to/execution-client/data:/node/teku/exec-jwt:ro \
  fiftysix/teku \
  teku --ee-endpoint http://reth-node:8551 --ee-jwt-secret-file /node/teku/exec-jwt/jwt.hex

This command starts the Teku container, pointed at the paired execution client's Engine API and shared JWT secret, exposing the default REST API and P2P ports.

⁠Directory Structure

In this Docker image, the following directories are used:

• Data Directory (/node/teku/data): This is where Teku stores the beacon chain database and other related files. This directory is specified in the Dockerfile and should be mounted if you want to persist data across container restarts.
• Scripts Directory (/node/teku/scripts): This directory contains the entrypoint script (teku-entrypoint.sh) and any other scripts that may be needed for starting or managing Teku.

⁠Mounting Directories

You can mount host directories to the container's data and scripts directories to customize the behavior of the Teku software.

Mounting the Data Directory: To persist Teku data across container restarts, you can mount a host directory to the container's data directory:

docker run --name teku -v /path/to/local/data:/node/teku/data -d fiftysix/teku ...

Mounting the Scripts Directory: If you have custom scripts you want to include, you can mount them to the scripts directory. For example, to replace the entrypoint script:

docker run --name teku -v /path/to/local/scripts:/node/teku/scripts -d fiftysix/teku ...

⁠Logging Teku

docker logs teku --tail 100

⁠Using Teku

⁠Starting Teku with Custom Options

To start Teku with custom options, such as checkpoint sync, pass additional flags:

docker run --name teku -d \
  -p 5051:5051 -p 9000:9000 -p 9000:9000/udp \
  -v /path/to/execution-client/data:/node/teku/exec-jwt:ro \
  fiftysix/teku \
  teku --ee-endpoint http://reth-node:8551 --ee-jwt-secret-file /node/teku/exec-jwt/jwt.hex \
  --checkpoint-sync-url https://your-trusted-checkpoint-provider

⁠Exposing Ports

The following ports are commonly used by Teku and are exposed in this Docker image:

• 5051: REST API server
• 9000: P2P communication (TCP and UDP)

⁠Docker Compose

Teku can also be run using Docker Compose, paired with any Fiftysix Ethereum execution client (Reth, Geth, Erigon, Besu, or Nethermind) to form a complete Ethereum node, with Teku handling consensus. Examples of these Docker Compose files can be found on the Fiftysix Github⁠.

⁠Support

For support, please contact [email protected]⁠.

⁠About Fiftysix

Fiftysix is committed to making blockchain technology accessible, efficient, and reliable through robust decentralization. Learn more at fiftysix.tech⁠.