lighthouse/book/src/docker.md

Docker Guide

There are two ways to obtain a Lighthouse Docker image:

1. Docker Hub, or
2. By building a Docker image from source.

Once you have obtained the docker image via one of these methods, proceed to Using the Docker image.

Docker Hub

Lighthouse maintains the sigp/lighthouse Docker Hub repository which provides an easy way to run Lighthouse without building the image yourself.

Obtain the latest image with:

docker pull sigp/lighthouse

Download and test the image with:

docker run sigp/lighthouse lighthouse --version

If you can see the latest Lighthouse release version (see example below), then you've successfully installed Lighthouse via Docker.

Example Version Output

Lighthouse vx.x.xx-xxxxxxxxx
BLS Library: xxxx-xxxxxxx

Pro tip: try the latest-modern image for a 20-30% speed-up! See Available Docker Images below.

Available Docker Images

There are several images available on Docker Hub.

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).

To install a specific tag (in this case latest-modern), add the tag name to your docker commands:

docker pull sigp/lighthouse:latest-modern

Image tags follow this format:

${version}${arch}${stability}${modernity}${features}

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 arch is:

• -amd64 for x86_64, e.g. Intel, AMD
• -arm64 for aarch64, e.g. Raspberry Pi 4
• empty for a multi-arch image (works on either amd64 or arm64 platforms)

The stability is:

• -unstable for the unstable branch
• empty for a tagged release or the stable branch

The modernity is:

• -modern for optimized builds
• empty for a portable unoptimized build

The features is:

• -dev for a development build with minimal preset enabled (spec-minimal feature).
• empty for a standard build with no custom feature enabled.

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:

docker build . -t lighthouse:local

The build will likely take several minutes. Once it's built, test it with:

docker run lighthouse:local lighthouse --help

Using the Docker image

You can run a Docker beacon node with the following command:

docker run -p 9000:9000/tcp -p 9000:9000/udp -p 9001:9001/udp -p 127.0.0.1:5052:5052 -v $HOME/.lighthouse:/root/.lighthouse sigp/lighthouse lighthouse --network mainnet beacon --http --http-address 0.0.0.0

To join the Holesky testnet, use --network holesky instead.

The -v (Volumes) and -p (Ports) and values are described below.

Volumes

Lighthouse uses the /root/.lighthouse directory inside the Docker image to store the configuration, database and validator keys. Users will generally want to create a bind-mount volume to ensure this directory persists between docker run commands.

The following example runs a beacon node with the data directory mapped to the users home directory:

docker run -v $HOME/.lighthouse:/root/.lighthouse sigp/lighthouse lighthouse beacon

Ports

In order to be a good peer and serve other peers you should expose port 9000 for both TCP and UDP, and port 9001 for UDP. Use the -p flag to do this:

docker run -p 9000:9000/tcp -p 9000:9000/udp -p 9001:9001/udp sigp/lighthouse lighthouse beacon

If you use the --http flag you may also want to expose the HTTP port with -p 127.0.0.1:5052:5052.

docker run -p 9000:9000/tcp -p 9000:9000/udp -p 9001:9001/udp -p 127.0.0.1:5052:5052 sigp/lighthouse lighthouse beacon --http --http-address 0.0.0.0