fix: improve docs (#125)

Author: ltitanb

docs/docs/get_started/configuration.md

@@ -4,7 +4,7 @@ description: Configure Commit-Boost
 
 # Configuration
 
-After the Commit-Boost CLI and the modules are setup as detailed in the previous section, you will need to create a `cb-config.toml` file, detailing all the services that you want to run. 
+Commit-Boost needs a configuration file detailing all the services that you want to run. Create a `cb-config.toml` and adjust it depending on which modules you plan to run.
 
 For a full explanation of all the fields, check out [here](https://github.com/Commit-Boost/commit-boost-client/blob/main/config.example.toml).
 
@@ -25,10 +25,12 @@ prometheus_config = "./docker/prometheus.yml"
 ```
 
 You can find a list of MEV-Boost Holesky relays [here](https://www.coincashew.com/coins/overview-eth/mev-boost/mev-relay-list#holesky-testnet-relays).
+After the sidecar is started, it will expose a port (`18550` in this example), that you need to point your CL to. This may be different depending on which CL you're running, check out [here](https://docs.flashbots.net/flashbots-mev-boost/getting-started/system-requirements#consensus-client-configuration-guides) for a list of configuration guides.
+
 Note that in this setup, the signer module will not be started.
 
 ## Custom module
-We currently provide a test module that needs to be built as a Docker image. To build the module run:
+We currently provide a test module that needs to be built locally. To build the module run:
 ```bash
 bash scripts/build_local_modules.sh
 ```

docs/docs/get_started/overview.md

@@ -8,19 +8,18 @@ description: Initial setup
 Commit-Boost is currently in alpha development and **NOT** ready for production use. Please use caution
 :::
 
+Commit-Boost is primarily based on [Docker](https://www.docker.com/) to enable modularity, sandboxing and cross-platform compatibility. It is also possible to run Commit-Boost [natively](/get_started/running/binary) without Docker.
 
-Commit-Boost currently uses [Docker](https://www.docker.com/) to enable modularity, sandboxing and cross-platform compatibility. We're also exploring [alternative](https://github.com/Commit-Boost/commit-boost-client/issues/18) approaches.
-
-In the current setup, each component roughly maps to a container: from a single `.toml` config file, the node operator can specify which modules they want to run, and Commit-Boost takes care of spinning up the services and creating links between them.
+Each component roughly maps to a container: from a single `.toml` config file, the node operator can specify which modules they want to run, and Commit-Boost takes care of spinning up the services and creating links between them.
 Commit-Boost ships with two core modules:
 - a PBS module which implements implements the [BuilderAPI](https://ethereum.github.io/builder-specs/) for [MEV Boost](https://docs.flashbots.net/flashbots-mev-boost/architecture-overview/specifications)
 - a signer module, which implements the [Signer API](/api) and provides the interface for modules to request proposer commitments
 
 ## Setup
 
-The Commit-Boost CLI creates a dynamic `docker-compose` file, with services and ports already set up. Alternatively, you can also run each module natively without using Docker.
+The Commit-Boost CLI creates a dynamic `docker-compose` file, with services and ports already set up.
 
-Either way, you can compile from source from our repo, or download binaries and fetch docker images from the official releases.
+Whether you're using Docker or running the binaries natively, you can compile from source directly from the repo, or download binaries and fetch docker images from the official releases.
 
 ### Binaries and images
 Find the latest releases at https://github.com/Commit-Boost/commit-boost-client/releases.
@@ -44,11 +43,11 @@ git checkout stable
 ```
 
 :::note
-If you get an `openssl` related error try running: `apt-get update && apt-get install -y openssl ca-certificates libssl3 libssl-dev`
+If you get an `openssl` related error try running: `apt-get update && apt-get install -y openssl ca-certificates libssl3 libssl-dev build-essential pkg-config`
 :::
 
 #### Docker
-You can now build the CLI:
+You will need to build the CLI to create the `docker-compose` file:
 
 ```bash
 # Build the CLI
@@ -71,13 +70,13 @@ This will create two local images called `commitboost_pbs_default` and `commitbo
 
 #### Binaries
 
-Alternatively, you can also build the modules from source and run them without Docker, in which case you wouldn't need the CLI:
+Alternatively, you can also build the modules from source and run them without Docker, in which case you can skip the CLI and only compile the modules:
 
 ```bash
-# Build the PBS module
+# Build the PBS module, this corresponds to commit-boost-pbs in the releases
 cargo build --release --bin default-pbs
 
-# Build the Signer module
+# Build the Signer module, this corresponds to commit-boost-signer in the releases
 cargo build --release --bin signer-module
 ```
 

docs/docs/get_started/running/binary.md

@@ -3,7 +3,6 @@ description: Run Commit-Boost modules natively
 ---
 
 # Binary
-It is also possible to run the native modules without using docker.
 
 :::warning
 Running the modules natively means you opt out of the security guarantees made by Docker and it's up to you how to setup and ensure the modules run safely
@@ -13,7 +12,7 @@ Running the modules natively means you opt out of the security guarantees made b
 ## Setup
 Get the binary of the module either by compiling from source or by downloading a [published release](https://github.com/Commit-Boost/commit-boost-client/releases).
 
-Modules need some environment variables to work correctly. Here is the complete list
+Modules need some environment variables to work correctly.
 
 ### Common
 - `CB_CONFIG`: required, path to the `toml` config file
@@ -45,7 +44,7 @@ Modules might also have additional envs required, which should be detailed by th
 
 ## Start
 
-After creating the `cb-config.toml` file, you need to setup the required envs and run the binary. For example:
+After creating the `cb-config.toml` file, setup the required envs and run the binary. For example:
 
 ```bash
 CB_CONFIG=./cb-config.toml commit-boost-pbs

docs/docs/get_started/running/docker.md

@@ -3,11 +3,11 @@ description: Run Commit-Boost with Docker
 ---
 
 # Docker
-The `commit-boost` cli will generate a dynamic `docker-compose.yml` file using the provided `toml` config file. This is the recommended approach as Docker provides sandboxing of the containers from the rest of your system.
+The Commit-Boost CLI will generate a dynamic `docker-compose.yml` file using the provided `toml` config file. This is the recommended approach as Docker provides sandboxing of the containers from the rest of your system.
 
 ## Init
 
-After creating the `cb-config.toml` file, you can now run the Commit-Boost sidecar. First run:
+First run:
 ```bash
 commit-boost init --config cb-config.toml
 ```
@@ -23,11 +23,11 @@ To start Commit-Boost run:
 commit-boost start --docker cb.docker-compose.yml [--env .cb.env]
 ```
 
-This will start up the services including PBS, commit modules (if any), and metrics collection (if enabled).
+This will run `docker compose up` with the correct envs, and start up the services including PBS, commit modules (if any), and metrics collection (if enabled).
 
 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.
 
-If enabled, this will also start a Prometheus server on port `9090` and a Grafana instance on port `3000`. In Grafana, you will also find some preset dabhboards already connected.
+If enabled, this will also start a Prometheus server on port `9090` and a Grafana instance on port `3000`. In Grafana, you will also find some preset dashboards already connected.
 
 
 ## Logs

docs/docs/get_started/troubleshooting.md

@@ -3,4 +3,66 @@ description: Common issues
 ---
 
 # Troubleshooting
-Commit-Boost is currently in alpha development so it's likely there are bugs, if you find any or have any question, please reach out on [Twitter](https://x.com/Commit_Boost) or [Telegram](https://t.me/+Pcs9bykxK3BiMzk5).
+
+Commit-Boost is currently in alpha development so it's likely there are bugs, if you find any or have any question, please reach out on [Twitter](https://x.com/Commit_Boost) or [Telegram](https://t.me/+Pcs9bykxK3BiMzk5).
+
+
+If you started the modules correctly you should see the following logs.
+
+## PBS
+After the module started correctly you should see:
+```bash
+2024-09-16T19:27:16.004643Z  INFO Starting PBS service address=0.0.0.0:18550 events_subs=0
+```
+
+To check that the setup is correct and you are connected to relays, you can trigger manually the `/status` endpoint, by running:
+
+```bash
+curl http://0.0.0.0:18550/eth/v1/builder/status -vvv
+
+*   Trying 0.0.0.0:18550...
+* Connected to 0.0.0.0 (127.0.0.1) port 18550 (#0)
+> GET /eth/v1/builder/status HTTP/1.1
+> Host: 0.0.0.0:18550
+> User-Agent: curl/7.81.0
+> Accept: */*
+>
+* Mark bundle as not supporting multiuse
+< HTTP/1.1 200 OK
+< content-length: 0
+< date: Mon, 16 Sep 2024 19:32:07 GMT
+<
+* Connection #0 to host 0.0.0.0 left intact
+```
+
+if now you check the logs, you should see:
+
+```bash
+2024-09-16T19:32:07.634966Z  INFO status{req_id=62f1c0db-f277-49fa-91e7-a9a1c2b2a6d3}: ua="curl/7.81.0" relay_check=true
+2024-09-16T19:32:07.642992Z  INFO status{req_id=62f1c0db-f277-49fa-91e7-a9a1c2b2a6d3}: relay check successful
+```
+
+If the sidecar is setup correctly, it will receive and process calls from the CL:
+#### Register validator
+This should happen periodically, depending on your validator setup.
+
+```bash
+2024-09-16T19:28:37.976534Z  INFO register_validators{req_id=296f662f-0e7a-4f15-be75-55b8ca19ffc0}: ua="Lighthouse/v5.2.1-9e12c21" num_registrations=500
+2024-09-16T19:28:38.819591Z  INFO register_validators{req_id=296f662f-0e7a-4f15-be75-55b8ca19ffc0}: register validator successful
+```
+
+#### Get header
+This will only happen if some of your validators have a proposal slot coming up.
+
+```bash
+2024-09-16T19:30:24.135376Z  INFO get_header{req_id=74126c5f-69e6-4961-86a6-6c2597bf15f5 slot=2551052}: ua="Lighthouse/v5.2.1-9e12c21" parent_hash=0x641c99d6e4f14bf6d268eb2a8c0dc51c7030ab24e384c0e679f2a6b438d298ea validator_pubkey=0x84fc20b09496341f24abfcb6f407e916ecc317497c5b1bba4970e50e96cf5e731b88e51753064c30cb221453bd71aebf ms_into_slot=135
+2024-09-16T19:30:25.089477Z  INFO get_header{req_id=74126c5f-69e6-4961-86a6-6c2597bf15f5 slot=2551052}: received header block_hash=0x0139686e8d251f010153875270256fce6f298d7b3f3f9129179fb86297dffad3 value_eth="0.001399518501462470"
+```
+
+#### Submit block
+This will only happen if you received a header in the previous call, and if the header is higher than the locally built block.
+
+```bash
+2024-09-16T14:38:01.409075Z  INFO submit_blinded_block{req_id=6eb9a04d-6f79-4295-823f-c054582b3599 slot=2549590}: ua="Lighthouse/v5.2.1-9e12c21" slot_uuid=16186e06-0cd0-47bc-9758-daa1b66eff5c ms_into_slot=1409 block_hash=0xfa135ae6f2bfb32b0a47368f93d69e0a2b3f8b855d917ec61d78e78779edaae6
+2024-09-16T14:38:02.910974Z  INFO submit_blinded_block{req_id=6eb9a04d-6f79-4295-823f-c054582b3599 slot=2549590}: received unblinded block
+```