Skip to content

Commit

Permalink
Modular docker-compose, improved instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
@yorickdowne
yorickdowne committed Sep 25, 2020
1 parent a61c324 commit 858e5a1
Show file tree
Hide file tree
Showing 8 changed files with 292 additions and 294 deletions.
28 changes: 10 additions & 18 deletions PREREQUISITES.md
View file
Original file line number Diff line number Diff line change
@@ -1,36 +1,28 @@
# Prerequisites

This project relies on docker and docker-compose, and git to bring the project
files themnselves in.

## Ubuntu Prerequisites
This project relies on docker and docker-compose, and git to bring the
project itself in. It has been tested on Linux and Windows 10, and is
expected to work on MacOS.

To run the client with defaults, assuming an Ubuntu host:
## Ubuntu Prerequisites

```
sudo apt update && sudo apt install docker docker-compose git
cd
git clone https://github.com/eth2-educators/eth2-docker.git
cd eth2-docker
cp default.env .env
sudo apt update && sudo apt dist-upgrade
sudo apt install docker docker-compose git
```

You **must** adjust the contents of `.env` to your environment. Specifically,
`LOCAL_UID` needs to be set to your UID, which you can get with `echo $UID`.
The default is `1000`, which hopefully covers the majority of cases.<br />
This step became necessary because of an upcoming security change to how
eth2.0-deposit-cli sets permissions on the files it creates.

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 (yet) use AppArmor.

## Windows 10 Prerequisites

Install [Docker Desktop](https://www.docker.com/products/docker-desktop), [git](https://git-scm.com/download/win), and [Python 3](https://www.python.org/downloads/windows/). Note you can also type `python3` into a Powershell window and it will bring you to the Microsoft Store for a recent Python 3 version.

You have to copy the `default.env` file to `.env`, from Powershell: `cp default.env .env`.
After copying this file, you may want to adjust the contents of `.env` to your environment.

Docker Desktop can be used with the WSL2 backend if desired, or without it.

You will run the docker-compose and docker commands from Powershell. You do not need `sudo` in front of those commands.
Expand Down
223 changes: 43 additions & 180 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# eth2-docker v0.06
# eth2-docker v0.07
Unofficial and experimental docker build instructions for eth2 clients

This project builds clients from source. A similar workflow for
Expand All @@ -11,51 +11,26 @@ Currently included clients:

# USAGE

- Generate deposit files and an eth2 wallet. This can be done within this project, or outside of it
- Choose a client, decide whether to run a local eth1 node or use a 3rd-party one
- Import the validator keystore files generated in the first step
- Run the client
- Wait until the eth1 node and beacon node are fully synchronized
- Finalize the deposit. This is not done within this project

## Before you start

A file 'default.env' is provided and needs to be copied to '.env'.
If this is not done, running docker-compose will fail.

On Linux, you will need to find your UID with `echo $UID` and then
adjust the `LOCAL_UID` parameter inside `.env`. This is necessary
so the validator can read the keystore files, see further below
on keystore import.<br />
Note that changing `LOCAL_UID` after you already started an
"eth2 node stack" with this project is difficult, as all the docker
volumes were created with that UID and you will get permissions errors.
Warnings about the dangers of running eth2 validators are in [RECOMMENDATIONS.md](RECOMMENDATIONS.md).
That file also contains a link to SomerEsat's [guide on host security](https://medium.com/@SomerEsat/guide-to-staking-on-ethereum-2-0-ubuntu-medalla-nimbus-5f4b2b0f2d7c), and comments on key security.
Please take a look.

You likely want to set `GRAFFITI` inside the file `.env`, and you might
adjust `NUM_VAL` if you are going to create keys for more than one validator.
## Steps to bring an eth2 node up

On Linux, `docker-compose` runs as root. The individual containers
do not, they run as local users inside the containers.

In the interest of readability, warnings about the dangers of running
eth2 validators have been moved to [RECOMMENDATIONS.md](RECOMMENDATIONS.md).
That file also contains comments on key security. Just know that funds can be
lost unless precautions are taken.

This README has some [troubleshooting commands](#troubleshooting).

## Install prerequisites
- Install [prerequisites](PREREQUISITES.md)
- [Choose a client](SETUP.md) and do initial setup. This is a required step.
- Generate deposit files and an eth2 wallet. This can be done within this project, or outside of it
- Import the validator keystore files generated in the previous step
- Run the client
- Optional: Wait until the eth1 node and beacon node are fully synchronized
- Finalize the deposit. This is not done within this project

This project relies on docker and docker-compose, and git to bring the
project itself in. It has been tested on Linux and Windows 10, and is
expected to work on MacOS. Notes on how to install prerequisites for
these systems are in [PREREQUISITES.md](PREREQUISITES.md).
## Build the client

Once they are met, navigate to a convenient directory that you
have write access to - your $HOME is fine - and pull this repo
via git:<br />
`git clone https://github.com/eth2-educators/eth2-docker.git`,
then `cd eth2-docker` into the newly created directory.
Build all required images from source. This will take 20-30 minutes.<br />
`sudo docker-compose build`

## Create an eth2 wallet and validator keystore and deposit files

Expand All @@ -75,138 +50,37 @@ This is also where you'd place your own keystore files if you already have some

They go into `.eth2/validator_keys` in this project directory, not directly under `$HOME`.

## Choose a client

There is no default file to avoid overwriting your file during `git pull`.

You'll be copying from the directory `clients` to the file `docker-compose.yml` in this directory. Current options are:
- [Lighthouse](#lighthouse), `cp clients/lh.yml docker-compose.yml`
- [Prysm](#prysm), `cp clients/prysm.yml docker-compose.yml`

If you are going to use a 3rd-party eth1chain provider, edit `.env` and set either `LH_ETH1_NODE` or `PRYSM_ETH1_NODE` to
point to your provider, and use the `eth2-3rd` target once you have imported keys and are ready.

## Lighthouse

Build the components you'll use, so all steps below can be done without delay.
- Lighthouse with local geth eth1 node: `sudo docker-compose build --no-cache geth deposit-cli lh-beacon`
- Lighthouse with 3rd-party eth1 node: `sudo docker-compose build --no-cache deposit-cli lh-beacon`

Go walk the dogs, have a beverage, stretch your legs: This may take 20-30 minutes.

### Create a validator wallet by importing validator keys

**Warning** Import your validator key(s) to only *one* client.

Import the validator key(s) to the Lighthouse validator client:

`sudo docker-compose run lh-validator-import`

If you specify the password during import, it'll be available to the client every
time it starts. If you do not, you'll need to be present to start the
validator and start it interactively. Determine your own risk profile.

### Start the client

To start the Lighthouse client, both beacon and validator, with local geth:

```
sudo docker-compose up -d eth2
```

Instead, if you are using a 3rd-party eth1chain, make sure that `LH_ETH1_NODE` in the file `.env` is pointing to it.

To start the Lighthouse client, both beacon and validator, with 3rd party eth1chain:

```
sudo docker-compose up -d eth2-3rd
```

If, however, you chose not to store the wallet password locally, bring the services
up individually instead:

With local geth:

```
sudo docker-compose up -d geth lh-beacon
```

Or with 3rd party eth1chain:
```
sudo docker-compose up -d lh-beacon
```

Then "run" the validator so it can prompt you for input:
```
sudo docker-compose run lh-validator
```

After providing the wallet password, use the key sequence Ctrl-p Ctrl-q to detach
from the running container.

## Prysm

Build the components you'll use, so all steps below can be done without delay.
- Prysm with local geth eth1 node: `sudo docker-compose build --no-cache geth deposit-cli prysm-beacon`
- Prysm with 3rd-party eth1 node: `sudo docker-compose build --no-cache deposit-cli prysm-beacon`

Go walk the dogs, have a beverage, stretch your legs: This may take 20-30 minutes.

### Create a validator wallet by importing validator keys
## Create a validator wallet by importing validator keys

**Warning** Import your validator key(s) to only *one* client.

Import the validator key(s) to the Prysm validator client:

`sudo docker-compose run prysm-validator-import`
Import the validator key(s) to the validator client:

You will be asked to provide a wallet directory. Use `/var/lib/prysm`.
`sudo docker-compose run validator-import`

You will be asked to provide a new wallet password.
> #### Prysm-specific
> - You will be asked to provide a wallet directory. Use `/var/lib/prysm`.
> - You will be asked to provide a "New wallet password", independent of the
> keystore password.
If you choose to store the password during import, it'll be available to the client every
If you choose to save the password during import, it'll be available to the client every
time it starts. If you do not, you'll need to be present to start the
validator and start it interactively. Determine your own risk profile.

### Start the client

The Prysm client requires copying in a file, see the [client choice](#choose-a-client) section.

Note that the Prysm client will find its external IP, but this project currently assumes
that IP is static. You can restart the container, possibly via crontab, with
`docker-compose restart prysm-beacon` if your IP is dynamic.
Work to support dynamic DNS would also be welcome.

To start the Prysm client, both beacon and validator, with local geth:
## Start the client

To start the client:
```
sudo docker-compose up -d eth2
```

Instead, if you are using a 3rd-party eth1chain, make sure that `PRYSM_ETH1_NODE` in the file `.env` is pointing to it.
To start the Prysm client, both beacon and validator, with 3rd party eth1chain:
If, however, you chose not to store the wallet password with the validator, you will need
to bring the beacon and, if in use, geth, up individually instead, then "run"
the validator so it can prompt you for input:

```
sudo docker-compose up -d eth2-3rd
```

If, however, you chose not to store the wallet password locally, bring the services
up individually instead:

With local geth:
```
sudo docker-compose up -d geth prysm-beacon
```

Or with 3rd-party eth1chain:
```
sudo docker-compose up -d prysm-beacon
```

Then "run" the validator so it can prompt you for input:
```
sudo docker-compose run prysm-validator
sudo docker-compose up -d geth beacon
sudo docker-compose run validator
```

After providing the wallet password, use the key sequence Ctrl-p Ctrl-q to detach
Expand All @@ -227,7 +101,6 @@ service.
- Copy the file: `sudo cp sample-systemd /etc/systemd/system/eth2.service`
- Edit the file `/etc/systemd/system/eth2.service`
- Adjust the `WorkingDirectory` to the directory you stored the project in.
- Adjust the `ExecStart` to use the right target - `eth2-3rd` if you don't run geth
- Adjust the path to `docker-compose` to be right for your system, see `which docker-compose`
- Test the service: `sudo systemctl daemon-reload`, `sudo systemctl start eth2`, check `docker ps` to
see all expected containers are up
Expand Down Expand Up @@ -257,7 +130,7 @@ or
sudo docker-compose logs -f SERVICENAME
```

## Update a client
## Update the software

This project does not monitor client versions. It is up to you to decide that you
are going to update a component. When you are ready to do so, the below instructions
Expand All @@ -268,6 +141,9 @@ show you how to.
Inside the project directory, run:<br />
`git pull`

Then `cp .env .env.bak` and `cp default.env .env`, and set variables inside `.env`
the way you need them, with `.env.bak` as a guide.

### Geth

Run:<br />
Expand All @@ -277,39 +153,26 @@ Then stop, remove and start geth:<br />
`sudo docker-compose stop geth && sudo docker-compose rm geth`<br />
`sudo docker-compose up -d geth`

### Lighthouse

lh-beacon and lh-validator share the same image, we only need to rebuild one.

Run:<br />
`sudo docker-compose build --no-cache lh-beacon`

Then restart the client:<br />
`sudo docker-compose down && sudo docker-compose up -d eth2`

If you did not provide the wallet password to the container, or you are not using a local geth
node, come up [more manually](#start-the-client) instead.

### Prysm
### Client

prysm-beacon and prysm-validator share the same image, we only need to rebuild one.
Beacon and validator share the same image, we only need to rebuild one.

Run:<br />
`sudo docker-compose build --no-cache prysm-beacon`
`sudo docker-compose build --no-cache beacon`

Then restart the client:<br />
`sudo docker-compose down && sudo docker-compose up -d eth2`

If you did not provide the wallet password to the container, or you are not using a local geth
node, come up [more manually](#start-the-client-1) instead.
If you did not store the wallet password with the validator, come up
[more manually](#start-the-client) instead.

# Troubleshooting

A few useful commands if you run into issues. As always, `sudo` is a Linux-ism and not needed on Windows 10.

`sudo docker-compose stop servicename` brings a service down, for example `docker-compose stop lh-validator`.<br />
`sudo docker-compose stop servicename` brings a service down, for example `docker-compose stop validator`.<br />
`sudo docker-compose down` will stop the entire stack.<br />
`sudo docker-compose up -d servicename` starts a single service, for example `sudo docker-compose up -d lh-validator`.
`sudo docker-compose up -d servicename` starts a single service, for example `sudo docker-compose up -d validator`.
The `-d` means "detached", not connected to your input session.<br />
`sudo docker-compose run servicename` starts a single service and connects your input session to it. Use the Ctrl-p Ctrl-q
key sequence to detach from it again.
Expand All @@ -321,8 +184,8 @@ key sequence to detach from it again.

You may start a service with `sudo docker-compose up -d servicename` and then find it's not in `sudo docker ps`. That means it terminated while
trying to start. To investigate, you could leave the `-d` off so you see logs on command line:<br />
`sudo docker-compose up lh-beacon`, for example.<br />
You could also run `sudo docker-compose logs lh-beacon` to see the last logs of that service and the reason it terminated.<br />
`sudo docker-compose up beacon`, for example.<br />
You could also run `sudo docker-compose logs beacon` to see the last logs of that service and the reason it terminated.<br />

If a service is not starting and you want to bring up its container manually, so you can investigate, first bring everything down:<br />
`sudo docker-compose down`, tear down everything first.<br />
Expand Down
Loading

0 comments on commit 858e5a1

Please sign in to comment.