fiftysix/nimbus repository overview

⁠Fiftysix Nimbus Docker Image

Maintainer: [email protected]⁠

⁠Overview

This Docker image provides a fully functional Nimbus client built using the Fiftysix base image. Nimbus is an Ethereum consensus (beacon) client maintained by Status, optimised for embedded systems and resource-restricted devices while remaining an excellent choice for any server or desktop. 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. The code can be viewed on the Fiftysix Github⁠.

⁠Tags

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

⁠What is Nimbus?

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

⁠Usage

⁠Prerequisites

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

Note: Nimbus's own CLI only accepts flags in --flag=value form (not --flag value) - use = for any flag you pass to this image.

⁠Basic Usage

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

docker pull fiftysix/nimbus
docker run --name nimbus -d \
  -v /path/to/execution-client/data:/node/nimbus/exec-jwt:ro \
  fiftysix/nimbus \
  nimbus_beacon_node --el=http://reth-node:8551 --jwt-secret=/node/nimbus/exec-jwt/jwt.hex

This command starts the Nimbus 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/nimbus/data): This is where Nimbus 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/nimbus/scripts): This directory contains the entrypoint script (nimbus-entrypoint.sh) and any other scripts that may be needed for starting or managing Nimbus.

⁠Mounting Directories

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

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

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

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

⁠Logging Nimbus

docker logs nimbus --tail 100

⁠Using Nimbus

⁠Starting Nimbus with Custom Options

To start Nimbus with custom options, remember every flag must use =:

docker run --name nimbus -d \
  -p 5052:5052 -p 9000:9000 -p 9000:9000/udp -p 9001:9001/udp \
  -v /path/to/execution-client/data:/node/nimbus/exec-jwt:ro \
  fiftysix/nimbus \
  nimbus_beacon_node --el=http://reth-node:8551 --jwt-secret=/node/nimbus/exec-jwt/jwt.hex \
  --rest-port=5052

⁠Exposing Ports

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

• 5052: REST API server
• 9000: P2P communication (TCP and UDP)
• 9001: QUIC transport (UDP)

⁠Docker Compose

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