Skip to content

Commit 7d8968c

Browse files
jclapisjclapis
committed
Added example configs and corresponding Docker compose files to the docs
1 parent 34723b9 commit 7d8968c

File tree

1 file changed

+257
-1
lines changed

1 file changed

+257
-1
lines changed

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

Lines changed: 257 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,4 +40,260 @@ 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 = "flashbots"
64+
url = "https://0xafa4c6985aa049fb79dd37010438cfebeb0f2bd42b115b89dd678dab0670c1de38da0c4e9138c9290a398ecd9a0b3110@boost-relay-hoodi.flashbots.net"
65+
66+
[[relays]]
67+
id = "titan"
68+
url = "https://0xaa58208899c6105603b74396734a6263cc7d947f444f396a90f7b7d3e65d102aec7e5e5291b27e08d02c50a050825c2f@hoodi.titanrelay.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+
74+
### Commit-Boost CLI Output
75+
76+
Run `commit-boost-cli init --config cb-config.toml` with the above configuration, the CLI will produce the following Docker Compose file:
77+
78+
```
79+
services:
80+
cb_pbs:
81+
healthcheck:
82+
test: curl -f http://localhost:18550/eth/v1/builder/status
83+
interval: 30s
84+
timeout: 5s
85+
retries: 3
86+
start_period: 5s
87+
image: ghcr.io/commit-boost/pbs:v0.8.0
88+
container_name: cb_pbs
89+
ports:
90+
- 127.0.0.1:18550:18550
91+
environment:
92+
CB_CONFIG: /cb-config.toml
93+
CB_PBS_ENDPOINT: 0.0.0.0:18550
94+
volumes:
95+
- ./cb-config.toml:/cb-config.toml:ro
96+
```
97+
98+
This will run the PBS service in a container named `cb_pbs`.
99+
100+
101+
### Configuration File Volume
102+
103+
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.
104+
105+
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.
106+
107+
108+
### Networking
109+
110+
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:
111+
112+
```
113+
host = "0.0.0.0"
114+
```
115+
116+
to the `[pbs]` section in the configuration. This will cause the resulting `ports` entry in the Docker compose file to become:
117+
118+
```
119+
ports:
120+
- 0.0.0.0:18550:18550
121+
```
122+
123+
though you will need to add an entry to your local machine's firewall software (if applicable) for other machines to access it.
124+
125+
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:
126+
127+
```
128+
ports: []
129+
```
130+
131+
132+
## Example with PBS, Signer, and a Signer Module
133+
134+
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.
135+
136+
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.
137+
138+
Below is a simple configuration for running only the three modules on the Hoodi network with two relays, extended from the prior scenario above:
139+
140+
```
141+
chain = "Hoodi"
142+
143+
[pbs]
144+
docker_image = "ghcr.io/commit-boost/pbs:v0.8.0"
145+
relay_check = true
146+
wait_all_registrations = true
147+
148+
[[relays]]
149+
id = "flashbots"
150+
url = "https://0xafa4c6985aa049fb79dd37010438cfebeb0f2bd42b115b89dd678dab0670c1de38da0c4e9138c9290a398ecd9a0b3110@boost-relay-hoodi.flashbots.net"
151+
152+
[[relays]]
153+
id = "titan"
154+
url = "https://0xaa58208899c6105603b74396734a6263cc7d947f444f396a90f7b7d3e65d102aec7e5e5291b27e08d02c50a050825c2f@hoodi.titanrelay.xyz"
155+
156+
[signer]
157+
port = 20000
158+
159+
[signer.local.loader]
160+
format = "lighthouse"
161+
keys_path = "./keys"
162+
secrets_path = "./secrets"
163+
164+
[[modules]]
165+
id = "DA_COMMIT"
166+
type = "commit"
167+
docker_image = "test_da_commit"
168+
sleep_secs = 5
169+
```
170+
171+
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).
172+
173+
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.
174+
175+
176+
### Commit-Boost CLI Output
177+
178+
Run `commit-boost-cli init --config cb-config.toml` with the above configuration, the CLI will produce two files:
179+
180+
- `cb.docker-compose.yml`
181+
- `.cb.env`
182+
183+
The Docker compose file will have these contents:
184+
185+
```
186+
services:
187+
cb_da_commit:
188+
image: test_da_commit
189+
container_name: cb_da_commit
190+
environment:
191+
CB_MODULE_ID: DA_COMMIT
192+
CB_CONFIG: /cb-config.toml
193+
CB_SIGNER_JWT: ${CB_JWT_DA_COMMIT}
194+
CB_SIGNER_URL: http://cb_signer:20000
195+
volumes:
196+
- ./cb-config.toml:/cb-config.toml:ro
197+
networks:
198+
- signer_network
199+
depends_on:
200+
cb_signer:
201+
condition: service_healthy
202+
cb_pbs:
203+
healthcheck:
204+
test: curl -f http://localhost:18550/eth/v1/builder/status
205+
interval: 30s
206+
timeout: 5s
207+
retries: 3
208+
start_period: 5s
209+
image: ghcr.io/commit-boost/pbs:latest
210+
container_name: cb_pbs
211+
ports:
212+
- 127.0.0.1:18550:18550
213+
environment:
214+
CB_CONFIG: /cb-config.toml
215+
CB_PBS_ENDPOINT: 0.0.0.0:18550
216+
volumes:
217+
- ./cb-config.toml:/cb-config.toml:ro
218+
cb_signer:
219+
healthcheck:
220+
test: curl -f http://localhost:20000/status
221+
interval: 30s
222+
timeout: 5s
223+
retries: 3
224+
start_period: 5s
225+
image: ghcr.io/commit-boost/signer:latest
226+
container_name: cb_signer
227+
ports:
228+
- 127.0.0.1:20000:20000
229+
environment:
230+
CB_CONFIG: /cb-config.toml
231+
CB_JWTS: ${CB_JWTS}
232+
CB_SIGNER_ENDPOINT: 0.0.0.0:20000
233+
CB_SIGNER_LOADER_KEYS_DIR: /keys
234+
CB_SIGNER_LOADER_SECRETS_DIR: /secrets
235+
volumes:
236+
- ./cb-config.toml:/cb-config.toml:ro
237+
- ./keys:/keys:ro
238+
- ./secrets:/secrets:ro
239+
networks:
240+
- signer_network
241+
networks:
242+
signer_network:
243+
driver: bridge
244+
245+
```
246+
247+
This will create three Docker containers when executed:
248+
249+
- `cb_pbs` for the PBS service
250+
- `cb_signer` for the Signer service
251+
- `cb_da_commit` for the example / test module that interacts with the Signer service API
252+
253+
Finally, the `.cb.env` file produced will look like this:
254+
255+
```
256+
CB_JWT_DA_COMMIT=mwDSSr7chwy9eFf7RhedBoyBtrwFUjSQ
257+
CB_JWTS=DA_COMMIT=mwDSSr7chwy9eFf7RhedBoyBtrwFUjSQ
258+
```
259+
260+
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.
261+
262+
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.
263+
264+
265+
### Configuration File Volume
266+
267+
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.
268+
269+
270+
### Networking
271+
272+
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:
273+
274+
```
275+
host = "0.0.0.0"
276+
```
277+
278+
to both the `[pbs]` and `[signer]` sections in the configuration. This will cause the resulting `ports` entries in the Docker compose file to become:
279+
280+
```
281+
cb_pbs:
282+
...
283+
ports:
284+
- 0.0.0.0:18550:18550
285+
286+
287+
cb_signer:
288+
...
289+
ports:
290+
- 0.0.0.0:20000:20000
291+
```
292+
293+
though you will need to add entries to your local machine's firewall software (if applicable) for other machines to access them.
294+
295+
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:
296+
297+
```
298+
ports: []
299+
```

0 commit comments

Comments
 (0)