Running with Eth Docker

Eth Docker is a Docker Compose setup for Ethereum nodes, maintained by EthStaker. It supports Grandine in every mode Grandine offers: as a standalone beacon node or embedded in Nethermind, with the integrated validator client, with a separate grandine vc, or as a validator client on its own.

Eth Docker is the recommended way to deploy Grandine for most regular use cases, such as a solo staking node or a node that serves your own applications. It sets up the execution client, Grandine, MEV-Boost and key management together, and keeps them updated with one command. Run Grandine directly only when you need a setup that Eth Docker does not cover.

Note: Support for the separate grandine vc (grandine.yml, grandine-vc-only.yml, grandine-plugin-cl-only.yml, and the separate validator client in grandine-plugin.yml) comes from eth-docker#2832, which is not merged yet. Released Eth Docker versions offer grandine-allin1.yml, grandine-cl-only.yml, grandine-plugin-allin1.yml, and grandine-plugin.yml as a beacon node without a validator client.

Choose a mode

Eth Docker picks the clients from the Compose files listed in COMPOSE_FILE in its .env file. Each Grandine mode has its own file. In the table, EL is the execution client, BN the beacon node and VC the validator client:

The standalone files go together with the Compose file of any execution client, for example nethermind.yml or geth.yml. The plugin files run Grandine inside Nethermind, so they go only with nethermind.yml, and there is no separate consensus container. See How Grandine works for the differences between the integrated and the separate validator client, and Grandine embedded in Nethermind for the embedded setup.

Set up

Install Eth Docker and run its configuration wizard:

git clone https://github.com/ethstaker/eth-docker.git
cd eth-docker
./ethd install
./ethd config

The wizard asks for the network, the clients and the fee recipient, and writes them to .env. Choose Grandine as the consensus client, or as the validator client for a validator-only setup.

For a mode that the wizard does not offer, such as the Nethermind plugin files, set COMPOSE_FILE in .env yourself, for example:

COMPOSE_FILE=nethermind.yml:grandine-plugin.yml

With grandine-plugin.yml, Grandine serves the Beacon Node API from the Nethermind container, so point the validator client at it with CL_NODE=http://execution:5052.

Start the node and follow the logs:

./ethd up
./ethd logs -f consensus

With the plugin files, Grandine logs as part of the execution service.

Storage mode

CL_NODE_TYPE in .env selects the storage mode:

Eth Docker's blob-archive node type is not supported for Grandine, and is not needed. For other clients, archive still prunes blob data and blob-archive keeps it. Grandine in archive mode never prunes blob sidecars or data columns, so for Grandine archive already keeps all blob data. Two limits apply to every client:

• Peers serve blob data only for the data availability window of about 18 days, so the node keeps blob data from about 18 days before it started onwards. Older blob data cannot be back-synced.
• After PeerDAS, a node stores only the data columns it custodies. To keep all blob data, also run it as a supernode with CL_EXTRAS=--supernode.

Changing the node type usually requires a resync. See Back-sync and archive nodes.

Validator keys

Import keys with:

./ethd keys import

Eth Docker imports them through the Keymanager API of the validator client: the beacon node in the integrated modes, and grandine vc in the separate ones. ./ethd keys list shows the loaded keys. Grandine writes each imported keystore to its own file in the validator directory, with its password in a plain file under secrets/. The wallet password that Eth Docker generates (./ethd get-grandine-wallet prints it) only unlocks keys that older Grandine versions kept in the legacy keystores.json storage. See Managing validator keys.

DOPPELGANGER=true enables doppelganger protection, WEB3SIGNER=true uses Web3Signer for the keys, and GRAFFITI sets the graffiti.

Switching modes

The validator keys and slashing protection data live in a Docker volume that depends on where the validator client runs:

• The integrated validator client (grandine-allin1.yml, grandine-plugin-allin1.yml) keeps them in the beacon node's volume.
• The separate validator client (grandine.yml, grandine-plugin.yml, grandine-vc-only.yml) keeps them in its own volume.

Switching between files of the same group keeps the validator data, so you do not need to import the keys again. Switching between the groups, for example from grandine-allin1.yml to grandine.yml, starts the new validator client with no keys. Move them like this:

1. Run ./ethd keys delete all. This removes the keys from the old validator client and exports their slashing protection data to .eth/validator_keys.
2. Change COMPOSE_FILE and run ./ethd up.
3. Put the keystore files into .eth/validator_keys next to the exported slashing protection data, and run ./ethd keys import.

Eth Docker recommends treating this like a move to another machine, with about 15 minutes of downtime. Never run the same keys in two validator clients at once. See Slashing protection.

Extra options

CL_EXTRAS passes extra options to the beacon node, and VC_EXTRAS to the validator client. For example:

CL_EXTRAS=--target-peers 100
VC_EXTRAS=--publish-to-every-node attestations,blocks

See the Command line reference for the options, and Redundancy and fallback beacon nodes for a validator client that uses several beacon nodes, set as a comma-separated list in CL_NODE.

Updating

./ethd update
./ethd up

This updates Eth Docker and the client images. See Updating Grandine for what to check before you update.