Skip to content

Commit 9feb4d2

Browse files
jclapisjclapis
authored
feat(docs): add example configs and corresponding Docker compose files to the docs (#343)
1 parent 1458617 commit 9feb4d2

File tree

2 files changed

+262
-2
lines changed

2 files changed

+262
-2
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ name: Docs
33
on:
44
push:
55
branches:
6-
- main
6+
- stable
77
# Review gh actions docs if you want to further define triggers, paths, etc
88
# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
99

‎docs/docs/get_started/running/docker.md‎

Lines changed: 261 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,4 +40,264 @@ To stop all the services and cleanup, simply run:
4040
```bash
4141
docker compose --env-file ".cb.env" -f ".cb.docker-compose.yml" down
4242
```
43-
This will wind down all services and clear internal networks and file mounts.
43+
This will wind down all services and clear internal networks and file mounts.
44+
45+
46+
## Example with PBS Only
47+
48+
This section provides an example of a configuration where only the PBS service is run with its default configuration, and the Docker compose file produced by that configuration.
49+
50+
All of PBS's parameters are controlled via the [Commit-Boost TOML configuration file](../configuration.md); the service cannot currently be controlled with command-line arguments. Therefore it is crucial to ensure that you have a configuration file present with all of the settings you require *before* starting the service, as this file will be mounted within the Docker container as a volume in read-only mode.
51+
52+
Below is a simple configuration for running only the PBS service on the Hoodi network with two relays:
53+
54+
```
55+
chain = "Hoodi"
56+
57+
[pbs]
58+
docker_image = "ghcr.io/commit-boost/pbs:v0.8.0"
59+
relay_check = true
60+
wait_all_registrations = true
61+
62+
[[relays]]
63+
id = "abc"
64+
url = "http://0xa1cec75a3f0661e99299274182938151e8433c61a19222347ea1313d839229cb4ce4e3e5aa2bdeb71c8fcf1b084963c2@abc.xyz"
65+
66+
[[relays]]
67+
id = "def"
68+
url = "http://0xa1cec75a3f0661e99299274182938151e8433c61a19222347ea1313d839229cb4ce4e3e5aa2bdeb71c8fcf1b084963c2@def.xyz"
69+
```
70+
71+
Note that there are many more parameters that Commit-Boost supports, but they are all omitted 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](../../../../config.example.toml).
72+
73+
The relays here are placeholder for the sake of the example; for a list of actual relays, visit [the EthStaker relay list](https://github.com/eth-educators/ethstaker-guides/blob/main/MEV-relay-list.md).
74+
75+
76+
### Commit-Boost CLI Output
77+
78+
Run `commit-boost-cli init --config cb-config.toml` with the above configuration, the CLI will produce the following Docker Compose file:
79+
80+
```
81+
services:
82+
cb_pbs:
83+
healthcheck:
84+
test: curl -f http://localhost:18550/eth/v1/builder/status
85+
interval: 30s
86+
timeout: 5s
87+
retries: 3
88+
start_period: 5s
89+
image: ghcr.io/commit-boost/pbs:v0.8.0
90+
container_name: cb_pbs
91+
ports:
92+
- 127.0.0.1:18550:18550
93+
environment:
94+
CB_CONFIG: /cb-config.toml
95+
CB_PBS_ENDPOINT: 0.0.0.0:18550
96+
volumes:
97+
- ./cb-config.toml:/cb-config.toml:ro
98+
```
99+
100+
This will run the PBS service in a container named `cb_pbs`.
101+
102+
103+
### Configuration File Volume
104+
105+
The CLI 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 CLI. 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.
106+
107+
Since this is a volume, the PBS service container will reload the file from disk any time it's restarted. 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 fail to start unless you manually adjust the volume's source location.
108+
109+
110+
### Networking
111+
112+
The CLI 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:
113+
114+
```
115+
host = "0.0.0.0"
116+
```
117+
118+
to the `[pbs]` section in the configuration. This will cause the resulting `ports` entry in the Docker compose file to become:
119+
120+
```
121+
ports:
122+
- 0.0.0.0:18550:18550
123+
```
124+
125+
though you will need to add an entry to your local machine's firewall software (if applicable) for other machines to access it.
126+
127+
Currently, the CLI 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:
128+
129+
```
130+
ports: []
131+
```
132+
133+
134+
## Example with PBS, Signer, and a Signer Module
135+
136+
In this scenario we will be running the PBS service, the Signer service, and a module (`DA_COMMIT`) that interacts with the Signer service's API.
137+
138+
All of both PBS's and the Signer's parameters are controlled via the [Commit-Boost TOML configuration file](../configuration.md); the services cannot currently be controlled with command-line arguments. Therefore it is crucial to ensure that you have a configuration file present with all of the settings you require *before* starting the services, as this file will be mounted within the Docker containers as a volume in read-only mode.
139+
140+
Below is a simple configuration for running only the three modules on the Hoodi network with two relays, extended from the prior scenario above:
141+
142+
```
143+
chain = "Hoodi"
144+
145+
[pbs]
146+
docker_image = "ghcr.io/commit-boost/pbs:v0.8.0"
147+
relay_check = true
148+
wait_all_registrations = true
149+
150+
[[relays]]
151+
id = "abc"
152+
url = "http://0xa1cec75a3f0661e99299274182938151e8433c61a19222347ea1313d839229cb4ce4e3e5aa2bdeb71c8fcf1b084963c2@abc.xyz"
153+
154+
[[relays]]
155+
id = "def"
156+
url = "http://0xa1cec75a3f0661e99299274182938151e8433c61a19222347ea1313d839229cb4ce4e3e5aa2bdeb71c8fcf1b084963c2@def.xyz"
157+
158+
[signer]
159+
port = 20000
160+
161+
[signer.local.loader]
162+
format = "lighthouse"
163+
keys_path = "./keys"
164+
secrets_path = "./secrets"
165+
166+
[[modules]]
167+
id = "DA_COMMIT"
168+
type = "commit"
169+
docker_image = "test_da_commit"
170+
sleep_secs = 5
171+
```
172+
173+
Note that there are many more parameters that Commit-Boost supports, but they are all omitted 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](../../../../config.example.toml).
174+
175+
The relays here are placeholder for the sake of the example; for a list of actual relays, visit [the EthStaker relay list](https://github.com/eth-educators/ethstaker-guides/blob/main/MEV-relay-list.md).
176+
177+
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](../configuration.md#local-signer) and secrets in Lighthouse format. For your own keys, adjust the `format` parameter within the configuration and directory paths accordingly.
178+
179+
180+
### Commit-Boost CLI Output
181+
182+
Run `commit-boost-cli init --config cb-config.toml` with the above configuration, the CLI will produce two files:
183+
184+
- `cb.docker-compose.yml`
185+
- `.cb.env`
186+
187+
The Docker compose file will have these contents:
188+
189+
```
190+
services:
191+
cb_da_commit:
192+
image: test_da_commit
193+
container_name: cb_da_commit
194+
environment:
195+
CB_MODULE_ID: DA_COMMIT
196+
CB_CONFIG: /cb-config.toml
197+
CB_SIGNER_JWT: ${CB_JWT_DA_COMMIT}
198+
CB_SIGNER_URL: http://cb_signer:20000
199+
volumes:
200+
- ./cb-config.toml:/cb-config.toml:ro
201+
networks:
202+
- signer_network
203+
depends_on:
204+
cb_signer:
205+
condition: service_healthy
206+
cb_pbs:
207+
healthcheck:
208+
test: curl -f http://localhost:18550/eth/v1/builder/status
209+
interval: 30s
210+
timeout: 5s
211+
retries: 3
212+
start_period: 5s
213+
image: ghcr.io/commit-boost/pbs:latest
214+
container_name: cb_pbs
215+
ports:
216+
- 127.0.0.1:18550:18550
217+
environment:
218+
CB_CONFIG: /cb-config.toml
219+
CB_PBS_ENDPOINT: 0.0.0.0:18550
220+
volumes:
221+
- ./cb-config.toml:/cb-config.toml:ro
222+
cb_signer:
223+
healthcheck:
224+
test: curl -f http://localhost:20000/status
225+
interval: 30s
226+
timeout: 5s
227+
retries: 3
228+
start_period: 5s
229+
image: ghcr.io/commit-boost/signer:latest
230+
container_name: cb_signer
231+
ports:
232+
- 127.0.0.1:20000:20000
233+
environment:
234+
CB_CONFIG: /cb-config.toml
235+
CB_JWTS: ${CB_JWTS}
236+
CB_SIGNER_ENDPOINT: 0.0.0.0:20000
237+
CB_SIGNER_LOADER_KEYS_DIR: /keys
238+
CB_SIGNER_LOADER_SECRETS_DIR: /secrets
239+
volumes:
240+
- ./cb-config.toml:/cb-config.toml:ro
241+
- ./keys:/keys:ro
242+
- ./secrets:/secrets:ro
243+
networks:
244+
- signer_network
245+
networks:
246+
signer_network:
247+
driver: bridge
248+
249+
```
250+
251+
This will create three Docker containers when executed:
252+
253+
- `cb_pbs` for the PBS service
254+
- `cb_signer` for the Signer service
255+
- `cb_da_commit` for the example / test module that interacts with the Signer service API
256+
257+
Finally, the `.cb.env` file produced will look like this:
258+
259+
```
260+
CB_JWT_DA_COMMIT=mwDSSr7chwy9eFf7RhedBoyBtrwFUjSQ
261+
CB_JWTS=DA_COMMIT=mwDSSr7chwy9eFf7RhedBoyBtrwFUjSQ
262+
```
263+
264+
The Signer service needs JWT authentication from each of its modules. The CLI creates these and embeds them into the containers via environment variables automatically for convenience. This is demonstrated for the Signer module within the `environment` compose block: the `CB_JWTS: ${CB_JWTS}` forwards the `CB_JWTS` environment variable that's present when running Docker compose. The CLI 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 CLI's JWT output into this environment variable.
265+
266+
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.
267+
268+
269+
### Configuration File Volume
270+
271+
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](#configuration-file-volume) for details on how this works.
272+
273+
274+
### Networking
275+
276+
The CLI will force both the PBS and Signer API endpoints to bind to `0.0.0.0` within Docker's internal network so other Docker containers can access them, but it will only expose the API port (default `18550` for PBS and `20000` for the Signer) to `127.0.0.1` on your host machine. That way any processes running on the same machine can access them on their respective ports. If you want to open the ports for access across your entire network, not just your local machine, you can add the line:
277+
278+
```
279+
host = "0.0.0.0"
280+
```
281+
282+
to both the `[pbs]` and `[signer]` sections in the configuration. This will cause the resulting `ports` entries in the Docker compose file to become:
283+
284+
```
285+
cb_pbs:
286+
...
287+
ports:
288+
- 0.0.0.0:18550:18550
289+
290+
291+
cb_signer:
292+
...
293+
ports:
294+
- 0.0.0.0:20000:20000
295+
```
296+
297+
though you will need to add entries to your local machine's firewall software (if applicable) for other machines to access them.
298+
299+
Currently, the CLI will always export the PBS and Signer services' API ports in one of these two ways. If you don't want to expose them at all, so they can only be accessed by other Docker containers running within Docker's internal network, you will need to manually remove the `ports` entries from the Docker compose files after they've been created:
300+
301+
```
302+
ports: []
303+
```

0 commit comments

Comments
 (0)