From 4ebba998dd629e2f74f3b6db3a300890ba8ca25c Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Tue, 30 Jun 2026 22:33:39 +0000 Subject: [PATCH] docs: add beacon configuration file (rcConfig) reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a dedicated docs page covering the global --rcConfig flag: accepted formats (YAML/JSON), how each key maps to a CLI flag, the dotted-key representation required for nested options (e.g. rest.address), command line precedence over file values, and a full beacon node example. Links the new page from the sidebar and the Starting a Node guide so the config file option is discoverable. 🤖 Generated with AI assistance Co-Authored-By: Claude Opus 4.8 --- .../beacon-management/configuration-file.md | 76 +++++++++++++++++++ .../run/beacon-management/starting-a-node.md | 2 +- docs/sidebars.ts | 1 + 3 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 docs/pages/run/beacon-management/configuration-file.md diff --git a/docs/pages/run/beacon-management/configuration-file.md b/docs/pages/run/beacon-management/configuration-file.md new file mode 100644 index 000000000000..81175690d4b2 --- /dev/null +++ b/docs/pages/run/beacon-management/configuration-file.md @@ -0,0 +1,76 @@ +--- +title: Configuration File +--- + +# Configuration File + +Lodestar can read any command line option from a configuration file using the global `--rcConfig` flag. This is useful for managing larger setups, keeping your configuration under version control, or avoiding long commands with many flags. + +`--rcConfig` is available for all commands (`beacon`, `validator`, `bootnode`, etc.). The accepted file formats are YAML (`.yml`, `.yaml`) and JSON (`.json`). + +## File Format + +Each key maps to a CLI flag, written without the leading `--`, and the value uses the same type as the flag (string, number, boolean, or array). Nested options such as `--rest.address` are written as dotted keys (`rest.address`), not as nested maps. + +For the full list of available options, see the [`beacon`](./beacon-cli.md), [`validator`](../validator-management/validator-cli.md), and [`bootnode`](../bootnode/bootnode-cli.md) CLI references. + +```yaml +# beacon.config.yaml +network: "hoodi" +dataDir: "/data/lodestar" +logFile: "/data/lodestar/beacon.log" +jwtSecret: "/data/jwtsecret.hex" + +# Networking +listenAddress: "0.0.0.0" +port: 9000 + +# Beacon REST API +rest: true +rest.address: "0.0.0.0" +rest.port: 9596 + +# Execution client +execution.urls: + - "http://localhost:8551" + +# Metrics +metrics: true +metrics.port: 8008 +``` + +The same configuration in JSON: + +```json +{ + "network": "hoodi", + "dataDir": "/data/lodestar", + "logFile": "/data/lodestar/beacon.log", + "jwtSecret": "/data/jwtsecret.hex", + "listenAddress": "0.0.0.0", + "port": 9000, + "rest": true, + "rest.address": "0.0.0.0", + "rest.port": 9596, + "execution.urls": ["http://localhost:8551"], + "metrics": true, + "metrics.port": 8008 +} +``` + +## Running with a Configuration File + +Pass the file path to `--rcConfig` when starting the node: + +```bash +./lodestar beacon --rcConfig /data/beacon.config.yaml +``` + +## Overriding Options + +Options passed directly on the command line take precedence over the values in the configuration file. This lets you keep a shared base configuration and override individual values per run: + +```bash +# Use everything from the file, but connect to mainnet instead of hoodi +./lodestar beacon --rcConfig /data/beacon.config.yaml --network mainnet +``` diff --git a/docs/pages/run/beacon-management/starting-a-node.md b/docs/pages/run/beacon-management/starting-a-node.md index 7aa0799b6e83..89151bf413c7 100644 --- a/docs/pages/run/beacon-management/starting-a-node.md +++ b/docs/pages/run/beacon-management/starting-a-node.md @@ -16,7 +16,7 @@ Make sure Lodestar is installed in your local environment, following the chosen For a complete list of beacon node CLI commands and options, see the [`beacon` CLI Command](../beacon-management/beacon-cli.md) section. -To select a known testnet or mainnet, use the `--network` flag. The option `mainnet` is selected by default, and a list of available networks is listed with the `--help` flag. Setting the `--network` flag will conveniently configure the beacon node for the selected network. For power users, any configuration option should be able to be overridden. +To select a known testnet or mainnet, use the `--network` flag. The option `mainnet` is selected by default, and a list of available networks is listed with the `--help` flag. Setting the `--network` flag will conveniently configure the beacon node for the selected network. For power users, any configuration option should be able to be overridden. You can also supply options through a [configuration file](./configuration-file.md) instead of passing them as command line flags. ## Configure the Lodestar JWT Authentication Token diff --git a/docs/sidebars.ts b/docs/sidebars.ts index ad28406c1a70..0335d76b8332 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -24,6 +24,7 @@ const sidebars: SidebarsConfig = { label: "Beacon Node", items: [ "run/beacon-management/starting-a-node", + "run/beacon-management/configuration-file", "run/beacon-management/beacon-cli", "run/beacon-management/data-retention", "run/beacon-management/fast-confirmation",