Skip to main content

Step 1: Install Prerequisites.

Eth Docker relies on Docker and Docker Compose, and git for initial install and updates. It has been tested on Linux, and is expected to work on MacOS.

The following prerequisites will be installed on the Linux server you will run your node on. The machine you use to connect to the Linux server only requires an SSH client.

Ubuntu Prerequisites​

Ubuntu can be installed with the Docker snap package, which can cause issues including complete data loss on upgrade. We highly recommend removing this via sudo snap remove --purge docker. Note this action will delete all data kept in Docker. If you are running the snap Docker package and have data you need to keep, please ask for help in the ethstaker Discord.

Eth Docker has been tested on Ubuntu 24.04 "Mantic Minotaur", Ubuntu 22.04 "Jammy Jellyfish" and Ubuntu 20.04 "Focal Fossa". An LTS, Long Term Support, version of Ubuntu is recommended, either Ubuntu Server or Ubuntu Desktop. If installing Ubuntu Server, make doubly sure to extend the "lv", logical volume, to use your entire disk during the install.

Automatic installation​

Clone the project: git clone https://github.com/eth-educators/eth-docker.git && cd eth-docker

Run ./ethd install and follow prompts

Manual installation​

Install docker-ce:

sudo apt-get update
sudo apt-get -y install ca-certificates curl gnupg lsb-release whiptail
sudo mkdir -p /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

You know it was successful when you saw messages scrolling past that install Docker and Docker Compose.

If you like, you can also add a docker-compose alias, replacing MYUSERNAME with your actual user name: echo 'alias docker-compose="docker compose"' >>/home/MYUSERNAME/.profile

Debian Prerequisites​

Eth Docker has been tested on Debian 11 "Bullseye" and Debian 12 "Bookworm".

Automatic installation​

Clone the project: git clone https://github.com/eth-educators/eth-docker.git && cd eth-docker

Run ./ethd install and follow prompts

Manual installation​

Install docker-ce:

sudo apt-get update
sudo apt-get -y install ca-certificates curl gnupg lsb-release whiptail
sudo mkdir -p /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

You know it was successful when you saw messages scrolling past that install docker and docker compose.

If you like, you can also add a docker-compose alias, replacing MYUSERNAME with your actual user name: echo 'alias docker-compose="docker compose"' >>/home/MYUSERNAME/.profile

Generic Linux​

Other distributions are expected to work as long as they support git, Docker, and Docker Compose.

On Linux, Docker Compose runs as root by default. The individual containers do not, they run as local users inside the containers. "Rootless mode" is expected to work for docker with this project, as it does not use AppArmor.

Change Docker storage location​

Taken from the RocketPool docs

By default, Docker will store all of its container data on your operating system's drive. In some cases, this is not what you want. For example, you may have a small boot drive and a second larger SSD for the chain data.

If you have just one drive and are good with the default behavior, don't make these adjustments

To change the Docker volume location, create a new file called /etc/docker/daemon.json as the root user:

sudo nano /etc/docker/daemon.json

Add this as the contents:

{
    "data-root": "<your external mount point>/docker"
}

where <your external mount point> is the directory that your other drive is mounted to.

Next, make the folder:

sudo mkdir -p <your external mount point>/docker

If you already have existing volumes that you want to move, stop Docker and move them over:

sudo systemctl stop docker
sudo cp -rp /var/lib/docker <your external mount point>/

Now, restart the Docker daemon so it picks up on the changes:

sudo systemctl restart docker

After that, Docker will store its data on your desired disk.

Switching from docker.io to docker-ce​

If you are currently running Canonical's docker.io and you'd like to switch to docker-ce, the "Community Edition" released by Docker, Inc., this is how.

You do not need to stop running containers manually, and they will be back up and running after. All volumes and other data kept in Docker will stay intact.

If you came here because of a nag message, you can switch out docker.io for docker-ce, or you can narrowly just upgrade Compose to V2, and remove Compose V1. In that case, stop before "Prepare docker-ce repo".

If you want to keep docker.io, and add the Compose V2 plugin, you can do so by:

sudo apt-mark manual docker.io && sudo apt-get remove --autoremove -y docker-compose && sudo apt-get install -y docker-compose-v2

Only if you wish to replace docker.io with docker-ce, continue below.

Prepare docker-ce repo:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu  $(lsb_release -cs) stable" \
| sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
 
sudo apt-get update

Remove docker.io:

sudo apt-get remove --autoremove -y docker.io containerd runc docker-compose docker-compose-v2

Reboot - yes this is mandatory:

sudo reboot

Install docker-ce:

sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin docker-buildx-plugin

Verify that all containers started automatically:

sudo docker ps

If you like, you can also add a docker-compose alias, replacing MYUSERNAME with your actual user name: echo 'alias docker-compose="docker compose"' >>/home/MYUSERNAME/.profile

rootless Docker​

Eth Docker works with rootless Docker.

If using Grafana, use grafana-rootless.yml instead of grafana.yml. This omits node-exporter, cadvisor, promtail and Loki.

If using traefik, either change its ports in .env to be above 1024, or expose privileged ports.

macOS Prerequisites​

The following prerequisites apply if you are going to use macOS as a server to run an Ethereum staking full node. If you use macOS to connect to a node server, all you need is an SSH client.

  • Install Docker Desktop and allocate 16+ GiB of RAM and 3TB or so of storage space to it, in Preferences->Resources->Advanced.
  • Install prerequisites via homebrew: brew install coreutils newt bash
  • You may need to log out and back into your terminal session to have the right version of bash. Try bash --version and verify it's 5.x or higher.
  • Verify git is installed with git --version. It will show a Desktop prompt to install it if it isn't.

Docker Desktop on macOS has its ideosyncrasies. An arguable easier path could be to keep macOS just for firmware updates and dual-boot into Debian Linux.

Windows 11​

It is technically possible to run Eth Docker on Windows 11.

However, the challenges inherent in running on Windows 11 are easier to solve when using the Windows-native versions of the clients, rather than wrapping Docker around them.

Windows 10/11 is fine as an SSH client to connect to your Linux server.