fiftysix/lighthouse repository overview

⁠Fiftysix Lighthouse Docker Image

Maintainer: [email protected]⁠

⁠Overview

This Docker image provides a fully functional Lighthouse client built using the Fiftysix base image. Lighthouse is an Ethereum consensus (beacon) client maintained by Sigma Prime that currently carries the largest share of Ethereum mainnet consensus traffic. 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 Lighthouse.
• <version>: Points to a specific version of Lighthouse. For example, 8.2.2.

⁠What is Lighthouse?

Lighthouse is an Ethereum consensus client implemented in Rust, built and maintained by Sigma Prime. 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 Lighthouse is required alongside an execution client (such as Reth, Geth, Erigon, Besu, or Nethermind) to run a complete Ethereum node.

⁠Usage

⁠Prerequisites

Lighthouse cannot run standalone. To run Lighthouse 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 Lighthouse container - Lighthouse must never generate its own. See the execution/consensus pairing notes⁠ for the full mechanism.

⁠Basic Usage

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

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

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

Note: for a fast, practical sync (rather than syncing from genesis, which Lighthouse refuses by default for safety), also pass --checkpoint-sync-url <a trusted checkpoint sync provider>.

⁠Directory Structure

In this Docker image, the following directories are used:

• Data Directory (/node/lighthouse/data): This is where Lighthouse 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/lighthouse/scripts): This directory contains the entrypoint script (lighthouse-entrypoint.sh) and any other scripts that may be needed for starting or managing Lighthouse.

⁠Mounting Directories

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

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

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

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 lighthouse -v /path/to/local/scripts:/node/lighthouse/scripts -d fiftysix/lighthouse ...

⁠Logging Lighthouse

docker logs lighthouse --tail 100

⁠Using Lighthouse

⁠Starting Lighthouse with Custom Options

To start Lighthouse with custom options, such as a different network or checkpoint sync, pass additional flags after bn:

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

⁠Exposing Ports

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

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

⁠Docker Compose

Lighthouse 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 Lighthouse 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⁠.