fiftysix/erigon repository overview

⁠Fiftysix Erigon Docker Image

Maintainer: [email protected]⁠

⁠Overview

This Docker image provides a fully functional Erigon client built using the Fiftysix base image. Erigon is an Ethereum execution engine, written in Go, that processes transactions, executes smart contracts, and maintains the Ethereum state — built on the efficiency frontier, with its own staged-sync pipeline and snapshot downloader in place of the block-by-block sync most other clients use. 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 Erigon.
• <version>: Points to a specific version of Erigon. For example, 3.6.1.

⁠What is Erigon?

Erigon is an implementation of Ethereum's execution layer, written in Go and built for efficiency. It operates as an execution engine in Ethereum's Proof of Stake (PoS) network, handling transaction processing, smart contract execution, and maintaining the state of the Ethereum blockchain. Rather than syncing block-by-block, Erigon uses its own staged pipeline and a BitTorrent/webseed-based snapshot downloader (OtterSync) to fetch pre-verified chain segments. Following the merge⁠, Erigon works in tandem with Ethereum consensus clients to manage the blockchain's consensus mechanism.

⁠Usage

⁠Prerequisites

To run Erigon effectively as an execution engine, you'll need a system with sufficient storage and memory to handle the Ethereum blockchain — see Hardware Requirements below, since Erigon's needs vary a lot by pruning mode. Erigon is designed to work alongside Ethereum consensus clients, such as Lighthouse, Prysm, Teku, Lodestar, and Nimbus, to form a complete Ethereum node.

⁠Basic Usage

To run an Erigon node:

docker pull fiftysix/erigon
docker run --name erigon -d fiftysix/erigon

This command will start the Erigon container, exposing the default RPC and P2P ports.

Note: Erigon requires an Ethereum consensus client alongside, such as Lighthouse, Prysm, Teku, Lodestar, or Nimbus, to properly sync. Example Erigon compose files can be found here⁠.

⁠Directory Structure

In this Docker image, the following directories are used:

• Data Directory (/node/erigon/data): This is where Erigon stores the Ethereum blockchain data and other related files, including the shared jwt.hex secret used to authenticate with a paired consensus client. This directory is specified in the Dockerfile and should be mounted if you want to persist data across container restarts.
• Config Directory (/node/erigon/configs): This directory holds config.toml, which the entrypoint always passes to Erigon via --config. It sets the default chain, RPC, WS, and Engine API settings and can be replaced with your own.
• Scripts Directory (/node/erigon/scripts): This directory contains the entrypoint script (erigon-entrypoint.sh) and any other scripts that may be needed for starting or managing Erigon.

⁠Mounting Directories

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

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

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

This command mounts the /path/to/local/data directory on your host to /node/erigon/data in the container, ensuring that blockchain data is preserved between container instances.

Mounting a Config File: To use a custom Erigon configuration file, mount your configuration file to the container's config directory:

docker run --name erigon -v /path/to/local/config.toml:/node/erigon/configs/config.toml -d fiftysix/erigon

This command mounts your custom config.toml file over the default one, which the entrypoint always passes to Erigon via --config.

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

This command mounts your local scripts directory to /node/erigon/scripts in the container, allowing you to customize the startup behavior.

⁠Logging Erigon

docker logs erigon --tail 100

⁠Using Erigon

⁠Starting Erigon with Custom Options

To start Erigon with custom options, you can pass additional flags to the erigon command — they're appended after the default config.toml is applied, so any flag here overrides the file:

docker run --name erigon -d \
  -p 8545:8545 -p 8546:8546 -p 30303:30303 -p 30303:30303/udp -p 42069:42069 -p 42069:42069/udp \
  fiftysix/erigon \
  --chain=mainnet --http --http.addr="0.0.0.0" --http.port=8545 --http.api="eth,net,web3"

This command starts Erigon with the HTTP RPC server enabled, listening on port 8545, and connected to the Ethereum mainnet.

docker stop sends SIGINT rather than SIGTERM to this image, matching Erigon's own upstream image, so a stop triggers a clean MDBX database shutdown instead of a forced kill after the grace period.

⁠Exposing Ports

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

• 8545: HTTP-RPC server
• 8546: WebSocket-RPC server
• 8551: Engine API server (used for communication between the execution engine and consensus client)
• 30303: P2P communication (TCP and UDP)
• 42069: Snapshot downloader (OtterSync) — BitTorrent/webseed traffic for historical chain segments; expose this alongside 30303 for good sync performance

⁠Hardware Requirements

Disk and RAM needs scale with the chosen --prune.mode. Per Erigon's hardware requirements documentation⁠, on Ethereum mainnet:

A locally-mounted NVMe/SSD is required — network or cloud block storage is explicitly called out as too slow for Erigon's random-access workload.

⁠NAT and Peering

The default image sets nat = "none" in config.toml, which is fine for a non-validating RPC node but results in inbound-only-restricted peering (worse tx-gossip freshness). If the host has a static public IP (e.g. a VPS or datacenter box), mount a custom config.toml with nat = "extip:<your-public-ip>" for healthier peering. See Erigon's NAT documentation⁠ for details.

⁠JWT Secret

Erigon auto-generates jwt.hex on first launch if it doesn't already exist at the path given to --authrpc.jwtsecret, and both the execution and consensus client must share that same file. The Fiftysix entrypoint only creates it when missing, so restarting the erigon container does not invalidate the paired consensus client's cached secret.

⁠Binary Verification

Erigon publishes a checksums.txt alongside each release. The Fiftysix image downloads it at build time, verifies the release tarball against the matching sha256sum entry, and only then extracts the binary — so bumping the pinned Erigon version is always sufficient on its own, with no separate checksum to update by hand.

⁠Docker Compose

Erigon can also be run using Docker Compose. Various Docker Compose files are available to run Erigon as the execution engine alongside different Ethereum consensus clients, such as Lighthouse, Prysm, Teku, Lodestar, and Nimbus. These setups enable a complete Ethereum node configuration, with Erigon handling execution and the chosen client managing 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⁠.