gnosis/lighthouse
1
0
Fork 0
mirror of https://github.com/sigp/lighthouse.git synced 2026-05-07 08:52:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Optimized Docker images (#2966)

Browse Source 
## Issue Addressed

Closes #2938

## Proposed Changes

* Build and publish images with a `-modern` suffix which enable CPU optimizations for modern hardware.
* Add docs for the plethora of available images!
* Unify all the Docker workflows in `docker.yml` (including for tagged releases).

## Additional Info

The `Dockerfile` is no longer used by our Docker Hub builds, as we use `cross` and a generic approach for ARM and x86. There's a new CI job `docker-build-from-source` which tests the `Dockerfile` without publishing anything.
This commit is contained in:
Michael Sproul
2022-01-31 22:55:03 +00:00
parent bdd70d7aef
commit 139b44342f
10 changed files with 187 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
book/src/cross-compiling.md
View File

@@ -19,15 +19,16 @@ project.
The `Makefile` in the project contains four targets for cross-compiling:
- `build-x86_64`: builds an optimized version for x86_64 processors (suitable for most users).
Supports Intel Broadwell (2014) and newer, and AMD Ryzen (2017) and newer.
- `build-x86_64-portable`: builds a version for x86_64 processors which avoids using some modern CPU
instructions that are incompatible with older CPUs. Suitable for pre-Broadwell/Ryzen CPUs.
- `build-aarch64`: builds an optimized version for 64-bit ARM processors
(suitable for Raspberry Pi 4).
instructions that are incompatible with older CPUs.
- `build-aarch64`: builds an optimized version for 64-bit ARM processors (suitable for Raspberry Pi 4).
- `build-aarch64-portable`: builds a version for 64-bit ARM processors which avoids using some
modern CPU instructions. In practice, very few ARM processors lack the instructions necessary to
run the faster non-portable build.
For more information about optimized vs portable builds see
[Portability](./installation-binaries.md#portability).
### Example
```bash

86
book/src/docker.md
View File

@@ -1,20 +1,17 @@
# Docker Guide
This repository has a `Dockerfile` in the root which builds an image with the
`lighthouse` binary installed. A pre-built image is available on Docker Hub.
There are two ways to obtain a Lighthouse Docker image:
## Obtaining the Docker image
1. [Docker Hub](#docker-hub), or
2. By [building a Docker image from source](#building-the-docker-image).
There are two ways to obtain the docker image, either via Docker Hub or
building the image from source. Once you have obtained the docker image via one
of these methods, proceed to [Using the Docker image](#using-the-docker-image).
Once you have obtained the docker image via one of these methods, proceed to [Using the Docker
image](#using-the-docker-image).
### Docker Hub
## Docker Hub
Lighthouse maintains the
[sigp/lighthouse](https://hub.docker.com/repository/docker/sigp/lighthouse/)
Docker Hub repository which provides an easy way to run Lighthouse without
building the image yourself.
Lighthouse maintains the [sigp/lighthouse][docker_hub] Docker Hub repository which provides an easy
way to run Lighthouse without building the image yourself.
Obtain the latest image with:
@@ -28,26 +25,69 @@ Download and test the image with:
$ docker run sigp/lighthouse lighthouse --version
```
If you can see the latest [Lighthouse
release](https://github.com/sigp/lighthouse/releases) version (see example
below), then you've
successfully installed Lighthouse via Docker.
If you can see the latest [Lighthouse release](https://github.com/sigp/lighthouse/releases) version
(see example below), then you've successfully installed Lighthouse via Docker.
#### Example Version Output
> Pro tip: try the `latest-modern` image for a 20-30% speed-up! See [Available Docker
> Images](#available-docker-images) below.
### Example Version Output
```
Lighthouse vx.x.xx-xxxxxxxxx
BLS Library: xxxx-xxxxxxx
```
> Note: when you're running the Docker Hub image you're relying upon a
> pre-built binary instead of building from source.
### Available Docker Images
> Note: due to the Docker Hub image being compiled to work on arbitrary machines, it isn't as highly
> optimized as an image built from source. We're working to improve this, but for now if you want
> the absolute best performance, please build the image yourself.
There are several images available on Docker Hub.
### Building the Docker Image
Most users should use the `latest-modern` tag, which corresponds to the latest stable release of
Lighthouse with optimizations enabled. If you are running on older hardware then the default
`latest` image bundles a _portable_ version of Lighthouse which is slower but with better hardware
compatibility (see [Portability](./installation-binaries.md#portability)).
To install a specific tag (in this case `latest-modern`) add the tag name to your `docker` commands
like so:
```
$ docker pull sigp/lighthouse:latest-modern
```
Image tags follow this format:
```
${version}${arch}${stability}${modernity}
```
The `version` is:
* `vX.Y.Z` for a tagged Lighthouse release, e.g. `v2.1.1`
* `latest` for the `stable` branch (latest release) or `unstable` branch
The `stability` is:
* `-unstable` for the `unstable` branch
* empty for a tagged release or the `stable` branch
The `arch` is:
* `-amd64` for x86_64, e.g. Intel, AMD
* `-arm64` for aarch64, e.g. Rasperry Pi 4
* empty for a multi-arch image (works on either `amd64` or `arm64` platforms)
The `modernity` is:
* `-modern` for optimized builds
* empty for a `portable` unoptimized build
Examples:
* `latest-unstable-modern`: most recent `unstable` build for all modern CPUs (x86_64 or ARM)
* `latest-amd64`: most recent Lighthouse release for older x86_64 CPUs
* `latest-amd64-unstable`: most recent `unstable` build for older x86_64 CPUs
## Building the Docker Image
To build the image from source, navigate to
the root of the repository and run:
@@ -103,3 +143,5 @@ If you use the `--http` flag you may also want to expose the HTTP port with `-p
```bash
$ docker run -p 9000:9000 -p 127.0.0.1:5052:5052 sigp/lighthouse lighthouse beacon --http --http-address 0.0.0.0
```
[docker_hub]: https://hub.docker.com/repository/docker/sigp/lighthouse/

17
book/src/installation-binaries.md
View File

@@ -20,13 +20,13 @@ Additionally there is also a `-portable` suffix which indicates if the `portable
- Without `portable`: uses modern CPU instructions to provide the fastest signature verification times (may cause `Illegal instruction` error on older CPUs)
- With `portable`: approx. 20% slower, but should work on all modern 64-bit processors.
For details, see [Portability](#portability).
## Usage
Each binary is contained in a `.tar.gz` archive. For this example, lets assume the user needs
a portable `x86_64` binary.
> Whilst this example uses `v0.2.13` we recommend always using the latest release.
### Steps
1. Go to the [Releases](https://github.com/sigp/lighthouse/releases) page and
@@ -41,6 +41,19 @@ a portable `x86_64` binary.
> Windows users will need to execute the commands in Step 3 from PowerShell.
## Portability
Portable builds of Lighthouse are designed to run on the widest range of hardware possible, but
sacrifice the ability to make use of modern CPU instructions.
If you have a modern CPU then you should try running a non-portable build to get a 20-30% speed up.
* For **x86_64**, any CPU supporting the [ADX](https://en.wikipedia.org/wiki/Intel_ADX) instruction set
extension is compatible with the optimized build. This includes Intel Broadwell (2014)
and newer, and AMD Ryzen (2017) and newer.
* For **ARMv8**, most CPUs are compatible with the optimized build, including the Cortex-A72 used by
the Raspberry Pi 4.
## Troubleshooting
If you get a SIGILL (exit code 132), then your CPU is incompatible with the optimized build