Skip to content

Commit 7165f12

Browse files
jclapisjclapis
committed
Added a build guide
1 parent 699b7ec commit 7165f12

File tree

1 file changed

+185
-0
lines changed

1 file changed

+185
-0
lines changed

‎docs/docs/get_started/building.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# Building Commit-Boost from Source
2+
3+
Commit-Boost's components are all written in [Rust](https://www.rust-lang.org/). This guide will walk you through the setup required to build them from source. It assumes you are on a Debian or Debian-based system (e.g., Ubuntu, Linux Mint, Pop OS). For other systems, please adapt the steps for your system's package manager accordingly.
4+
5+
6+
## Building via the Docker Builder
7+
8+
For convenience, Commit-Boost has Dockerized the build environment for Linux `x64` and `arm64` platforms. All of the prerequisites, cross-compilation tooling, and configuration are handled by the builder image. If you would like to build the CLI, PBS module, or Signer binaries and Docker images from source, you are welcome to use the Docker builder process.
9+
10+
To use the builder, you will need to have [Docker Engine](https://docs.docker.com/engine/install/) installed on your system. Please follow the instructions to install it first.
11+
12+
:::note
13+
The build script assumes that you've added your user account to the `docker` group with the Linux [post-install steps](https://docs.docker.com/engine/install/linux-postinstall/). If you haven't, then you'll need to run the build script below as `root` or modify it so each call to `docker` within it is run as the root user (e.g., with `sudo`).
14+
:::
15+
16+
We provide a build script called `build-linux.sh` to automate the process:
17+
18+
```
19+
$ ./build-linux.sh
20+
Usage: build.sh [options] -v <version number>
21+
This script assumes it is in the commit-boost-client repository directory.
22+
Options:
23+
-a Build all of the artifacts (CLI, PBS, and Signer, along with Docker images)
24+
-c Build the Commit-Boost CLI binaries
25+
-p Build the PBS module binary and its Docker container
26+
-s Build the Signer module binary and its Docker container
27+
-o When passed with a build, upload the resulting image tags to a local Docker registry specified in $LOCAL_DOCKER_REGISTRY
28+
```
29+
30+
The script utilizes Docker's [buildx](https://docs.docker.com/reference/cli/docker/buildx/) system to both create a multiarch-capable builder and cross-compile for both Linux architectures. You are free to modify it to produce only the artifacts relevant to you if so desired.
31+
32+
The `version` provided will be used to house the output binaries in `./build/$VERSION`, and act as the version tag for the Docker images when they're added to your local system or uploaded to your local Docker repository.
33+
34+
35+
## Building Manually
36+
37+
If you don't want to use the Docker builder, you can compile the Commit-Boost artifacts locally. The following instructions assume a Debian or Debian-based system (e.g., Ubuntu, Linux Mint, Pop OS) for simplicity. For other systems, please adapt any relevant instructions to your environment accordingly.
38+
39+
40+
### Prerequisites
41+
42+
Requirements:
43+
44+
- Rust 1.83+
45+
- GCC (or another C compiler of your choice)
46+
- OpenSSL development libraries
47+
- Protobuf Compiler (`protoc`)
48+
49+
Start by installing Rust if you don't already have it. Follow [the official directions](https://www.rust-lang.org/learn/get-started) to install it and bring it up to date.
50+
51+
Install the dependencies:
52+
53+
```bash
54+
sudo apt update && sudo apt install -y openssl ca-certificates libssl3 libssl-dev build-essential pkg-config curl
55+
```
56+
57+
Install the Protobuf compiler:
58+
59+
:::note
60+
While many package repositories provide a `protobuf-compiler` package in lieu of manually installing protoc, we've found at the time of this writing that most of them use v3.21 which is quite out of date. We recommend getting the latest version manually.
61+
:::
62+
63+
```bash
64+
PROTOC_VERSION=$(curl -s "https://api.github.com/repos/protocolbuffers/protobuf/releases/latest" | grep -Po '"tag_name": "v\K[0-9.]+')
65+
MACHINE_ARCH=$(uname -m)
66+
case "${MACHINE_ARCH}" in
67+
aarch64) PROTOC_ARCH=aarch_64;;
68+
x86_64) PROTOC_ARCH=x86_64;;
69+
*) echo "${MACHINE_ARCH} is not supported."; exit 1;;
70+
esac
71+
curl -sLo protoc.zip https://github.com/protocolbuffers/protobuf/releases/latest/download/protoc-$PROTOC_VERSION-linux-$PROTOC_ARCH.zip
72+
sudo unzip -q protoc.zip bin/protoc -d /usr
73+
sudo unzip -q protoc.zip "include/google/*" -d /usr
74+
sudo chmod a+x /usr/bin/protoc
75+
rm -rf protoc.zip
76+
```
77+
78+
With the prerequisites set up, pull the repository:
79+
```bash
80+
git clone https://github.com/Commit-Boost/commit-boost-client
81+
```
82+
83+
Check out the `stable` branch which houses the latest release:
84+
```bash
85+
cd commit-boost-client && git checkout stable
86+
```
87+
88+
Finally, update the submodules:
89+
```
90+
git submodule update --init --recursive
91+
```
92+
93+
Your build environment should now be ready to use.
94+
95+
96+
### Building the CLI
97+
98+
To build the CLI, run:
99+
```
100+
cargo build --release --bin commit-boost-cli
101+
```
102+
103+
This will create a binary in `./target/release/commit-boost-cli`. Confirm that it works:
104+
```
105+
./target/release/commit-boost-cli --version
106+
```
107+
108+
You can now use this to generate the Docker Compose file to drive the other modules if desired. See the [configuration](./configuration.md) guide for more information.
109+
110+
111+
### Building the PBS Module
112+
113+
To build PBS, run:
114+
```
115+
cargo build --release --bin commit-boost-pbs
116+
```
117+
118+
This will create a binary in `./target/release/commit-boost-pbs`. To verify it works, create [a TOML configuration](./configuration.md) for the PBS module (e.g., `cb-config.toml`).
119+
120+
As a quick example, we'll use this configuration that connects to the Flashbots relay on the Hoodi network:
121+
```toml
122+
chain = "Hoodi"
123+
124+
[pbs]
125+
port = 18550
126+
with_signer = true
127+
128+
[[relays]]
129+
url = "https://0xafa4c6985aa049fb79dd37010438cfebeb0f2bd42b115b89dd678dab0670c1de38da0c4e9138c9290a398ecd9a0b3110@boost-relay-hoodi.flashbots.net"
130+
131+
[metrics]
132+
enabled = true
133+
134+
[signer]
135+
[signer.local.loader]
136+
format = "lighthouse"
137+
keys_path = "/tmp/keys"
138+
secrets_path = "/tmp/secrets"
139+
```
140+
141+
Set the path to it in the `CB_CONFIG` environment variable and run the binary:
142+
```
143+
CB_CONFIG=cb-config.toml ./target/release/commit-boost-pbs
144+
```
145+
146+
If it works, you should see output like this:
147+
```
148+
2025-05-07T21:09:17.407245Z WARN No metrics server configured
149+
2025-05-07T21:09:17.407257Z INFO starting PBS service version="0.7.0" commit_hash="58082edb1213596667afe8c3950cd997ab85f4f3" addr=127.0.0.1:18550 events_subs=0 chain=Hoodi
150+
2025-05-07T21:09:17.746855Z INFO : new request ua="" relay_check=true method=/eth/v1/builder/status req_id=5c405c33-0496-42ea-a35d-a7a01dbba356
151+
2025-05-07T21:09:17.896196Z INFO : relay check successful method=/eth/v1/builder/status req_id=5c405c33-0496-42ea-a35d-a7a01dbba356
152+
```
153+
154+
If you do, then the binary works.
155+
156+
157+
### Building the Signer Module
158+
159+
To build the Signer, run:
160+
```
161+
cargo build --release --bin commit-boost-signer
162+
```
163+
164+
This will create a binary in `./target/release/commit-boost-signer`. To verify it works, create [a TOML configuration](./configuration.md) for the Signer module (e.g., `cb-config.toml`). We'll use the example in the PBS build section above.
165+
166+
The signer needs the following environment variables set:
167+
- `CB_CONFIG` = path of your config file.
168+
- `CB_JWTS` = a dummy key-value pair of [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token) values for various services. Since we don't need them for the sake of just testing the binary, we can use something like `"test_jwts=dummy"`.
169+
- `CB_SIGNER_PORT` = the network port to listen for signer requests on. Default is `20000`.
170+
171+
Set these values, create the `keys` and `secrets` directories listed in the configuration file, and run the binary:
172+
173+
```
174+
mkdir -p /tmp/keys && mkdir -p /tmp/secrets
175+
CB_CONFIG=cb-config.toml CB_JWTS="test_jwts=dummy" CB_SIGNER_PORT=20000 ./target/release/commit-boost-signer
176+
```
177+
178+
You should see output like this:
179+
```
180+
2025-05-07T21:43:46.385535Z WARN Proxy store not configured. Proxies keys and delegations will not be persisted
181+
2025-05-07T21:43:46.393507Z INFO Starting signing service version="0.7.0" commit_hash="58082edb1213596667afe8c3950cd997ab85f4f3" modules=["test_jwts"] port=20000 loaded_consensus=0 loaded_proxies=0
182+
2025-05-07T21:43:46.393574Z WARN No metrics server configured
183+
```
184+
185+
If you do, then the binary works.

0 commit comments

Comments
 (0)