|
| 1 | +# VSCode Debugger Configuration |
| 2 | + |
| 3 | +This document explains how to use the debug configuration for Assertoor in VSCode. |
| 4 | + |
| 5 | +## Requirements |
| 6 | + |
| 7 | +Before using the debugger, make sure you have installed: |
| 8 | + |
| 9 | +- **Go v1.23.0** - Required programming language |
| 10 | +- **Docker** - Container platform required by Kurtosis. Install Docker Desktop for your platform from [docker.com](https://www.docker.com/products/docker-desktop/) |
| 11 | +- **Kurtosis CLI** - Development environment orchestration tool. Install following the official guide: |
| 12 | + |
| 13 | + **macOS (Homebrew):** |
| 14 | + |
| 15 | + ```bash |
| 16 | + brew install kurtosis-tech/tap/kurtosis-cli |
| 17 | + ``` |
| 18 | + |
| 19 | + **Ubuntu (APT):** |
| 20 | + |
| 21 | + ```bash |
| 22 | + echo "deb [trusted=yes] https://apt.fury.io/kurtosis-tech/ /" | sudo tee /etc/apt/sources.list.d/kurtosis.list |
| 23 | + sudo apt update |
| 24 | + sudo apt install kurtosis-cli |
| 25 | + ``` |
| 26 | + |
| 27 | + **RHEL (YUM):** |
| 28 | + |
| 29 | + ```bash |
| 30 | + echo '[kurtosis] |
| 31 | + name=Kurtosis |
| 32 | + baseurl=https://yum.fury.io/kurtosis-tech/ |
| 33 | + enabled=1 |
| 34 | + gpgcheck=0' | sudo tee /etc/yum.repos.d/kurtosis.repo |
| 35 | + sudo yum install kurtosis-cli |
| 36 | + ``` |
| 37 | + |
| 38 | + **Other platforms:** Download from [releases page](https://github.com/kurtosis-tech/kurtosis-cli-release-artifacts/releases) |
| 39 | + |
| 40 | +- **yq** - Tool for manipulating YAML files: |
| 41 | + |
| 42 | + **macOS:** |
| 43 | + |
| 44 | + ```bash |
| 45 | + brew install yq |
| 46 | + ``` |
| 47 | + |
| 48 | + **Ubuntu/Debian:** |
| 49 | + |
| 50 | + ```bash |
| 51 | + sudo apt install yq |
| 52 | + ``` |
| 53 | + |
| 54 | + **Other platforms:** Download from [yq releases](https://github.com/mikefarah/yq/releases) |
| 55 | + |
| 56 | +- **PostgreSQL Client (psql)** - Required for database cleanup operations: |
| 57 | + |
| 58 | + **macOS:** |
| 59 | + |
| 60 | + ```bash |
| 61 | + brew install postgresql |
| 62 | + ``` |
| 63 | + |
| 64 | + **Ubuntu/Debian:** |
| 65 | + |
| 66 | + ```bash |
| 67 | + sudo apt install postgresql-client |
| 68 | + ``` |
| 69 | + |
| 70 | + **RHEL/CentOS:** |
| 71 | + |
| 72 | + ```bash |
| 73 | + sudo yum install postgresql |
| 74 | + ``` |
| 75 | + |
| 76 | +## "Debug Go assertoor" Configuration |
| 77 | + |
| 78 | +The `Debug Go assertoor` configuration in the `launch.json` file allows you to start Assertoor in debug mode directly from VSCode. |
| 79 | + |
| 80 | +### What happens when you launch the configuration |
| 81 | + |
| 82 | +1. **Pre-Launch Task**: The `devnet-setup` task is automatically executed to prepare the development environment |
| 83 | +2. **Program Launch**: The Go binary of Assertoor is launched from the workspace root |
| 84 | +3. **Configuration**: The program is started with the configuration file `.hack/devnet/generated-assertoor-config.yaml` |
| 85 | +4. **Logging**: Logs are displayed in the VSCode debug console (`showLog: true`) |
| 86 | + |
| 87 | +### Configuration Parameters |
| 88 | + |
| 89 | +- **Program**: `${workspaceFolder}` - Executes the main package from the project root |
| 90 | +- **Args**: `["--config", ".hack/devnet/generated-assertoor-config.yaml"]` - Specifies the configuration file to use |
| 91 | +- **PreLaunchTask**: `devnet-setup` - Task that runs before starting the debug session |
| 92 | +- **Mode**: `auto` - VSCode automatically determines whether to debug the binary or source code |
| 93 | + |
| 94 | +### How to use |
| 95 | + |
| 96 | +1. Open the Assertoor project in VSCode |
| 97 | +2. Go to the "Run and Debug" panel (Ctrl+Shift+D / Cmd+Shift+D) |
| 98 | +3. Select "Debug Go assertoor" from the dropdown |
| 99 | +4. Click the play button or press F5 |
| 100 | +5. The debugger will start automatically after completing the environment setup |
| 101 | + |
| 102 | +## Custom Enclave test configuration |
| 103 | + |
| 104 | +You can create a custom devnet configuration to customize the testing environment according to your needs. |
| 105 | + |
| 106 | +### How to add a custom configuration |
| 107 | + |
| 108 | +1. Create the file `.hack/devnet/custom-kurtosis.devnet.config.yaml` in your workspace |
| 109 | +2. Add your desired configuration to this file |
| 110 | +3. The devnet setup will automatically use your custom configuration if it exists |
| 111 | + |
| 112 | +## Custom Assertoor Configuration |
| 113 | + |
| 114 | +You can create a personalized Assertoor configuration that overrides or extends the automatically generated settings. |
| 115 | + |
| 116 | +### How the configuration system works |
| 117 | + |
| 118 | +When you run the devnet setup (`.hack/devnet/run.sh`), the following process occurs: |
| 119 | + |
| 120 | +1. **Kurtosis generates a base config** from the ethereum-package, including endpoints and global variables |
| 121 | +2. **The script looks for a custom file**: |
| 122 | + - First searches for `custom-assertoor.devnet.config.yaml` |
| 123 | + - If not found, uses `assertoor.devnet.config.yaml` |
| 124 | +3. **Applies environment variables** to the custom file using `envsubst` |
| 125 | +4. **Merges the configurations** using `yq eval-all` which combines: |
| 126 | + - The config generated by Kurtosis (with endpoints, database, etc.) |
| 127 | + - Your custom config that overrides/adds settings |
| 128 | + |
| 129 | +### Creating your custom Assertoor configuration |
| 130 | + |
| 131 | +To create a custom configuration: |
| 132 | + |
| 133 | +1. **Create the file `custom-assertoor.devnet.config.yaml`** in the `.hack/devnet/` directory |
| 134 | +2. **Add your custom settings** that will override or extend the generated config |
| 135 | +3. **Use environment variables** like `${DEVNET_DIR}` which are automatically substituted |
| 136 | + |
| 137 | +### Example custom configuration |
| 138 | + |
| 139 | +```yaml |
| 140 | +# Custom Assertoor configuration |
| 141 | +# This file overrides/adds settings to the automatically generated config |
| 142 | + |
| 143 | +web: |
| 144 | + server: |
| 145 | + host: "0.0.0.0" |
| 146 | + port: 8080 |
| 147 | + frontend: |
| 148 | + enabled: true |
| 149 | + debug: true |
| 150 | + |
| 151 | +# Custom external tests |
| 152 | +externalTests: |
| 153 | + - file: https://raw.githubusercontent.com/noku-team/assertoor/master/playbooks/dev/tx-pool-check-short.yaml |
| 154 | + |
| 155 | +# Custom logging configuration |
| 156 | +logging: |
| 157 | + level: "debug" |
| 158 | + colorOutput: true |
| 159 | + |
| 160 | +# Custom database settings (optional, but needed for macos, by default it uses /app folder, that is not writable) |
| 161 | +database: |
| 162 | + engine: "sqlite" |
| 163 | + sqlite: |
| 164 | + file: "${DEVNET_DIR}/sqlite.db" |
| 165 | + |
| 166 | +# database: |
| 167 | +# engine: "pgsql" |
| 168 | +# pgsql: |
| 169 | +# host: "localhost" |
| 170 | +# port: "5432" |
| 171 | +# username: "postgres" |
| 172 | +# password: "" |
| 173 | +# database: "assertoor" |
| 174 | +# max_open_conns: 50 |
| 175 | +# max_idle_conns: 10 |
| 176 | +``` |
| 177 | + |
| 178 | +### Common customizations |
| 179 | + |
| 180 | +- **Change web port**: Modify `web.server.port` |
| 181 | +- **Add custom tests**: Use `externalTests` to include your test playbooks |
| 182 | +- **Custom global variables**: Use `globalVars` for test parameters |
| 183 | +- **Custom logging**: Configure log level and format |
| 184 | +- **Different database**: Switch from PostgreSQL to SQLite or customize connection settings |
| 185 | + |
| 186 | +### Important notes |
| 187 | + |
| 188 | +- The custom config file is **always preserved** between runs |
| 189 | +- The generated config is recreated each time you run the devnet setup |
| 190 | +- Environment variables in your config (like `${DEVNET_DIR}`) are automatically substituted |
| 191 | +- Your custom settings will override any conflicting settings from the generated config |
| 192 | + |
| 193 | +### Example Configuration |
| 194 | + |
| 195 | +Here's an example of a custom configuration: |
| 196 | + |
| 197 | +```yaml |
| 198 | +participants: |
| 199 | +- el_type: erigon |
| 200 | + el_image: test/erigon:current |
| 201 | + cl_type: prysm |
| 202 | + count: 2 |
| 203 | +additional_services: |
| 204 | +- assertoor |
| 205 | +- dora |
| 206 | +assertoor_params: |
| 207 | + run_stability_check: false |
| 208 | + run_block_proposal_check: true |
| 209 | +``` |
| 210 | +
|
| 211 | +This configuration: |
| 212 | +
|
| 213 | +- Sets up 2 nodes with Erigon (execution layer) and Prysm (consensus layer) |
| 214 | +- Enables additional services (Assertoor and Dora) |
| 215 | +- Configures Assertoor with specific parameters and test playbooks |
| 216 | +- Uses custom Docker images for testing |
| 217 | +
|
| 218 | +### Notes |
| 219 | +
|
| 220 | +- Make sure all requirements are installed before launching the debugger |
| 221 | +- The `devnet-setup` task may take a few minutes the first time |
| 222 | +- You can set breakpoints in the Go code before starting the debug session |
| 223 | +- Custom configurations allow you to test different network setups and scenarios |
0 commit comments