Docker

The Commit-Boost program generates a cb.docker-compose.yml file from the provided .toml config file. This is the recommended approach as Docker provides sandboxing of the containers from the rest of your system.

Init

First run:

commit-boost init --config cb-config.toml

The optional -o/--output flag sets where the files are written (default: the current directory).

This will create two files:

cb.docker-compose.yml which contains the full setup of the Commit-Boost services.
.cb.env with local env variables, including JWTs for modules, only created if the Signer service is enabled.

Start

To start Commit-Boost run:

docker compose --env-file ".cb.env" -f "cb.docker-compose.yml" up -d

note

If only the PBS service is configured, no .cb.env file is generated and the --env-file ".cb.env" flag must be omitted (Docker Compose errors if the file doesn't exist). In general, use the exact command that commit-boost init prints. The same applies to the logs and down commands below.

This will run all the configured services, including PBS, signer and commit modules (if any).

The MEV-Boost server will be exposed at pbs.port from the config, 18550 in our example. You'll need to point your CL/Validator client to this port to be able to source blocks from the builder market.

Logs

To check the logs, run:

docker compose --env-file ".cb.env" -f "cb.docker-compose.yml" logs -f

This will currently show all logs from the different services via the Docker logs interface. Logs are also optionally saved to file, depending on your [logs] configuration.

Stop

To stop all the services and cleanup, simply run:

docker compose --env-file ".cb.env" -f "cb.docker-compose.yml" down

This will wind down all services and clear internal networks and file mounts.

Example with PBS Only

A minimal configuration that runs only the PBS service with its defaults, and the Docker compose file init produces from it.

All of PBS's parameters are controlled via the Commit-Boost TOML configuration file; the service cannot currently be controlled with command-line arguments. Make sure the configuration file exists with all of the settings you require before starting the service, as it is mounted into the Docker container as a read-only volume.

Below is a simple configuration for running only the PBS service on the Hoodi network with two relays:

chain = "Hoodi"

[pbs]
docker_image = "ghcr.io/commit-boost/commit-boost:v0.11.0"
relay_check = true
wait_all_registrations = true

[[relays]]
id = "abc"
url = "https://0xa1cec75a3f0661e99299274182938151e8433c61a19222347ea1313d839229cb4ce4e3e5aa2bdeb71c8fcf1b084963c2@abc.example.com"

[[relays]]
id = "def"
url = "https://0xa1cec75a3f0661e99299274182938151e8433c61a19222347ea1313d839229cb4ce4e3e5aa2bdeb71c8fcf1b084963c2@def.example.com"

There are many more parameters that Commit-Boost supports, but they are all omitted here and thus will use their default options. For a full description of the default options within the config file, go to the annotated configuration example.

The relays here are placeholders for the sake of the example; for a list of actual relays, visit the EthStaker relay list.

Commit-Boost Init Output

Run commit-boost init --config cb-config.toml with the above configuration. The program will produce the following Docker Compose file:

services:
  cb_pbs:
    healthcheck:
      test: curl -f http://localhost:18550/eth/v1/builder/status
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 5s
    image: ghcr.io/commit-boost/commit-boost:v0.11.0
    container_name: cb_pbs
    ports:
    - 127.0.0.1:18550:18550
    environment:
      CB_CONFIG: /cb-config.toml
      CB_PBS_ENDPOINT: 0.0.0.0:18550
    volumes:
    - ./cb-config.toml:/cb-config.toml:ro
    command:
    - pbs

This will run the PBS service in a container named cb_pbs.

Configuration File Volume

The program creates a read-only volume binding for the config file, which the PBS service needs to run. The Docker compose file that it creates with the init command, cb.docker-compose.yml, will be placed into your current working directory when you run the program. The volume source will be specified as a relative path to that working directory, so it's ideal if the config file is directly within your working directory (or a subdirectory). If you need to specify an absolute path for the config file, you can adjust the volumes entry within the Docker compose file manually after its creation.

Since this is a volume, the PBS service sees changes to the file: the stock PBS image watches the config file and automatically reloads the configuration whenever the file is modified, without needing a restart. That means you can change the file any time after the Docker compose file is created to tweak PBS's parameters, but it also means the config file must stay in the same location; if you move it, the PBS container won't be able to mount it anymore and will fail to start unless you manually adjust the volume's source location.

Custom PBS images may not auto-reload; see Extending PBS.

Networking

The program will force the PBS service to bind to 0.0.0.0 within Docker's internal network so other Docker containers can access it, but it will only expose the API port (default 18550) to 127.0.0.1 on your host machine. That way any processes running on the same machine can access it on that port. If you want to open the port for access across your entire network, not just your local machine, you can add the line:

host = "0.0.0.0"

to the [pbs] section in the configuration. This will cause the resulting ports entry in the Docker compose file to become:

ports:
  - 0.0.0.0:18550:18550

though you will need to add an entry to your local machine's firewall software (if applicable) for other machines to access it.

Currently, the program will always export the PBS service's API port in one of these two ways. If you don't want to expose it at all, so it can only be accessed by other Docker containers running within Docker's internal network, you will need to manually remove the ports entry from the Docker compose file after it's been created:

ports: []

Without `commit-boost init`

To run the PBS service from the image without commit-boost init, mount the config file, point CB_CONFIG at it, and pass pbs:

docker run -d --name cb_pbs \
  -v "$PWD/cb-config.toml:/cb-config.toml:ro" \
  -e CB_CONFIG=/cb-config.toml \
  -p 127.0.0.1:18550:18550 \
  ghcr.io/commit-boost/commit-boost:v0.11.0 pbs

commit-boost init sets the address PBS binds inside the container through CB_PBS_ENDPOINT. Without it, set host = "0.0.0.0" in [pbs], since PBS otherwise binds 127.0.0.1 inside the container and nothing outside it can reach the port. To reach PBS from containers on another user-defined Docker network, such as your beacon node's, add --network <that network>; they reach it by its container name, here http://cb_pbs:18550. If chain uses a spec file, add -v "$PWD/spec.json:/spec.json:ro" and set path in chain to "/spec.json". To serve metrics, also set CB_METRICS_PORT and publish that port with -p, both of which init does for you.

Example with PBS, Signer, and a Commit Module

In this scenario we will be running the PBS service, the Signer service, and a commit module (DA_COMMIT) that interacts with the Signer service's API.

The same configuration-file rules as the PBS-only example apply.

Below is a simple configuration for running only the three modules on the Hoodi network with two relays, extended from the prior scenario above:

chain = "Hoodi"

[pbs]
docker_image = "ghcr.io/commit-boost/commit-boost:v0.11.0"
relay_check = true
wait_all_registrations = true

[[relays]]
id = "abc"
url = "https://0xa1cec75a3f0661e99299274182938151e8433c61a19222347ea1313d839229cb4ce4e3e5aa2bdeb71c8fcf1b084963c2@abc.example.com"

[[relays]]
id = "def"
url = "https://0xa1cec75a3f0661e99299274182938151e8433c61a19222347ea1313d839229cb4ce4e3e5aa2bdeb71c8fcf1b084963c2@def.example.com"

[signer]
docker_image = "ghcr.io/commit-boost/commit-boost:v0.11.0"
port = 20000

[signer.local.loader]
format = "lighthouse"
keys_path = "./keys"
secrets_path = "./secrets"

[[modules]]
id = "DA_COMMIT"
type = "commit"
docker_image = "test_da_commit"
signing_id = "0x6a33a23ef26a4836979edff86c493a69b26ccf0b4a16491a815a13787657431b"
sleep_secs = 5

In this scenario there are two folders in the same directory as the configuration file (the working directory): keys and secrets. These correspond to the folders containing the EIP-2335 keystores and secrets in Lighthouse format. For your own keys, adjust the format parameter within the configuration and directory paths accordingly.

If either the docker_image under the [signer] or [pbs] is left unspecified, it defaults to ghcr.io/commit-boost/commit-boost:latest. Make sure to specify both if you intend to use versions other than the latest release.

Commit-Boost Init Output

Run commit-boost init --config cb-config.toml with the above configuration. The program will produce two files:

cb.docker-compose.yml
.cb.env

The Docker compose file will have these contents:

services:
  cb_da_commit:
    image: test_da_commit
    container_name: cb_da_commit
    environment:
      CB_MODULE_ID: DA_COMMIT
      CB_CONFIG: /cb-config.toml
      CB_SIGNER_JWT: ${CB_JWT_DA_COMMIT}
      CB_SIGNER_URL: http://cb_signer:20000
    volumes:
    - ./cb-config.toml:/cb-config.toml:ro
    networks:
    - signer_network
    depends_on:
      cb_signer:
        condition: service_healthy
  cb_pbs:
    healthcheck:
      test: curl -f http://localhost:18550/eth/v1/builder/status
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 5s
    image: ghcr.io/commit-boost/commit-boost:v0.11.0
    container_name: cb_pbs
    ports:
    - 127.0.0.1:18550:18550
    environment:
      CB_CONFIG: /cb-config.toml
      CB_PBS_ENDPOINT: 0.0.0.0:18550
    volumes:
    - ./cb-config.toml:/cb-config.toml:ro
    command:
    - pbs
  cb_signer:
    healthcheck:
      test: curl -k -f http://cb_signer:20000/status
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 5s
    image: ghcr.io/commit-boost/commit-boost:v0.11.0
    container_name: cb_signer
    ports:
    - 127.0.0.1:20000:20000
    environment:
      CB_CONFIG: /cb-config.toml
      CB_JWTS: ${CB_JWTS}
      CB_SIGNER_ADMIN_JWT: ${CB_SIGNER_ADMIN_JWT}
      CB_SIGNER_TLS_CERTIFICATES: /certs
      CB_SIGNER_ENDPOINT: 0.0.0.0:20000
      CB_SIGNER_LOADER_KEYS_DIR: /keys
      CB_SIGNER_LOADER_SECRETS_DIR: /secrets
    volumes:
    - ./cb-config.toml:/cb-config.toml:ro
    - ./keys:/keys:ro
    - ./secrets:/secrets:ro
    networks:
    - signer_network
    command:
    - signer
networks:
  signer_network:
    driver: bridge

This will create three Docker containers when executed:

cb_pbs for the PBS service
cb_signer for the Signer service
cb_da_commit for the example / test module that interacts with the Signer service API

Finally, the .cb.env file produced will look like this:

CB_JWT_DA_COMMIT=hJ0bV40p...
CB_JWTS=DA_COMMIT=hJ0bV40p...
CB_SIGNER_ADMIN_JWT=WbdxlH32...

The values shown are truncated examples; init generates fresh random secrets on every run. The file contains live secrets: restrict it with chmod 600 .cb.env and keep it out of backups and version control.

The Signer service needs JWT authentication from each of its modules. The program creates these and embeds them into the containers via environment variables automatically for convenience. This is demonstrated for the Signer service within the environment compose block: the CB_JWTS: ${CB_JWTS} forwards the CB_JWTS environment variable that's present when running Docker compose. The program requests that you do so via the command docker compose --env-file "./.cb.env" -f "./cb.docker-compose.yml" up -d; the --env-file "./.cb.env" handles loading the program's JWT output into this environment variable.

Similarly, for the cb_da_commit module, the CB_SIGNER_JWT: ${CB_JWT_DA_COMMIT} line within its environment block will set the JWT that it should use to authenticate with the Signer service.

Configuration File Volume

As with the PBS-only example, the configuration file is placed into a read-only volume binding for all three images to reference. The same rules apply, so please read the section in the PBS example for details on how this works.

Networking

The same networking rules as the PBS-only example apply to both services; the Signer's API port (default 20000) is exposed to 127.0.0.1 alongside PBS's 18550. To open them to your network, add host = "0.0.0.0" to both the [pbs] and [signer] sections, or remove the ports entries from the compose file to keep them Docker-internal.

The signer's API is authenticated, but it serves signing requests for your validator keys over plain HTTP by default. The PBS port has no authentication. Open either port beyond localhost only behind a firewall, and the signer's only with TLS enabled.

Docker

Init​

Start​

Logs​

Stop​

Example with PBS Only​

Commit-Boost Init Output​

Configuration File Volume​

Networking​

Without commit-boost init​

Example with PBS, Signer, and a Commit Module​

Commit-Boost Init Output​

Configuration File Volume​

Networking​

Init

Start

Logs

Stop

Example with PBS Only

Commit-Boost Init Output

Configuration File Volume

Networking

Without `commit-boost init`

Example with PBS, Signer, and a Commit Module

Commit-Boost Init Output

Configuration File Volume

Networking