fixes 1611: adds page for boilerplate config and clarifies profiles (#…

…1644) * fixes 1611: adds page for boilerplate config and clarifies profiles Signed-off-by: m4sterbunny <[email protected]> * proofs 1611 Signed-off-by: m4sterbunny <[email protected]> * proofs 1611: instruction to caps vars Signed-off-by: m4sterbunny <[email protected]> * Update sync and storage Add sync and storage Signed-off-by: Joan E <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * update to include storage Signed-off-by: Joan E <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * add links Signed-off-by: Joan E <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * adding in some details re the peering process (#1643) * adding in some details re the peering process Signed-off-by: Joshua Fernandes <[email protected]> * edit p2p discovery process and tutorials Signed-off-by: Alexandra Tran <[email protected]> * Update docs/public-networks/how-to/connect/manage-peers.md Signed-off-by: Alexandra Carrillo <[email protected]> --------- Signed-off-by: Joshua Fernandes <[email protected]> Signed-off-by: Alexandra Tran <[email protected]> Signed-off-by: Alexandra Carrillo <[email protected]> Co-authored-by: Alexandra Tran <[email protected]> Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * remove note Signed-off-by: Joan E <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/use-configuration-file/defaults.md proof Co-authored-by: Simon Dudley <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * improves GH links Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/use-configuration-file/defaults.md proof Co-authored-by: Simon Dudley <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * 6612: Remove remaining references to X_SNAP and X_CHECKPOINT from unv… (#1651) * 6612: Remove remaining references to X_SNAP and X_CHECKPOINT from unversioned docs Signed-off-by: Matilda Clerke <[email protected]> * Update docs/public-networks/how-to/bonsai-limit-trie-logs.md Co-authored-by: Sally MacFarlane <[email protected]> Signed-off-by: Joan E <[email protected]> --------- Signed-off-by: Matilda Clerke <[email protected]> Signed-off-by: Joan E <[email protected]> Co-authored-by: Joan E <[email protected]> Co-authored-by: Sally MacFarlane <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Add Lukso to command line table (#1647) * Add Lukso to command line table Signed-off-by: Joan E <[email protected]> * Add links to table to help users access aux docs Signed-off-by: Joan E <[email protected]> --------- Signed-off-by: Joan E <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Version update automation (#1654) Deleted the workflow added incorrectly to the .github folder. Added new workflow file to perform the version update steps when a new release is created Signed-off-by: Chaminda Divitotawela <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Allow version update with workflow dispatch (#1655) * Allow version update with workflow dispatch Was looking to trigger the version update workflow by re-creating the release 24.7.0. However when a release it re-created from the same commit which has been created a release, it does not seems to trigger the even type released. Added workflow_dispatch also to the same workflow so that users can manually trigger the version update if necessary. Signed-off-by: Chaminda Divitotawela <[email protected]> * Actionlint fixes Signed-off-by: Chaminda Divitotawela <[email protected]> --------- Signed-off-by: Chaminda Divitotawela <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update version 24.7.0 (#1657) Signed-off-by: Besu Bot <[email protected]> Co-authored-by: Besu Bot <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update table to include SNAP (#1658) * Update table to include SNAP Signed-off-by: Joan E <[email protected]> * Update docs/public-networks/reference/cli/options.md Co-authored-by: Sally MacFarlane <[email protected]> Signed-off-by: Joan E <[email protected]> --------- Signed-off-by: Joan E <[email protected]> Co-authored-by: Sally MacFarlane <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * adds default sync Signed-off-by: m4sterbunny <[email protected]> * fixes: copy/pasta Signed-off-by: m4sterbunny <[email protected]> * adds defaults to sidebar Signed-off-by: m4sterbunny <[email protected]> * update relative link Signed-off-by: Joan E <[email protected]> * renames index to accomodate defaults also and updates links/adds redirects Signed-off-by: m4sterbunny <[email protected]> * renames index to accomodate defaults also and updates links/adds redirects Signed-off-by: m4sterbunny <[email protected]> * responds to link issues https://github.com/hyperledger/besu-docs/actions/runs/10095001531/job/27914102000\?pr\=1644 Signed-off-by: m4sterbunny <[email protected]> * responds to link issues https://github.com/hyperledger/besu-docs/actions/runs/10095001531/job/27914102000\?pr\=1644 Signed-off-by: m4sterbunny <[email protected]> * responds to link issues https://github.com/hyperledger/besu-docs/actions/runs/10095001531/job/27914102000\?pr\=1644 Signed-off-by: m4sterbunny <[email protected]> * responds to link issues https://github.com/hyperledger/besu-docs/actions/runs/10095001531/job/27914102000\?pr\=1644 Signed-off-by: m4sterbunny <[email protected]> * responds to link issues https://github.com/hyperledger/besu-docs/actions/runs/10095001531/job/27914102000\?pr\=1644 Signed-off-by: m4sterbunny <[email protected]> * temp fix for redirect Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/configure-besu/index.md proof Co-authored-by: Simon Dudley <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update profile.md adds tags to new page Signed-off-by: m4sterbunny <[email protected]> * check link Signed-off-by: Joan E <[email protected]> * add back link Signed-off-by: Joan E <[email protected]> * Update docs/public-networks/how-to/configure-besu/index.md proof Co-authored-by: Joan E <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/configure-besu/index.md proof Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/configure-besu/index.md reframing Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/configure-besu/index.md proof Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/configure-besu/index.md proof Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/configure-besu/index.md proof Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/configure-besu/profile.md proof Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/configure-besu/profile.md proof Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/configure-besu/profile.md proof Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/configure-besu/profile.md proof Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/configure-besu/profile.md proof Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/configure-besu/index.md proof Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/configure-besu/index.md proof Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * Update docs/public-networks/how-to/configure-besu/index.md proof Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: m4sterbunny <[email protected]> * aligns index with additional function custom profiles Signed-off-by: m4sterbunny <[email protected]> --------- Signed-off-by: m4sterbunny <[email protected]> Signed-off-by: Joan E <[email protected]> Signed-off-by: Joshua Fernandes <[email protected]> Signed-off-by: Alexandra Tran <[email protected]> Signed-off-by: Alexandra Carrillo <[email protected]> Signed-off-by: Matilda Clerke <[email protected]> Signed-off-by: Chaminda Divitotawela <[email protected]> Signed-off-by: Besu Bot <[email protected]> Co-authored-by: Joan E <[email protected]> Co-authored-by: Joshua Fernandes <[email protected]> Co-authored-by: Alexandra Tran <[email protected]> Co-authored-by: Alexandra Carrillo <[email protected]> Co-authored-by: Simon Dudley <[email protected]> Co-authored-by: Matilda-Clerke <[email protected]> Co-authored-by: Sally MacFarlane <[email protected]> Co-authored-by: Chaminda Divitotawela <[email protected]> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Besu Bot <[email protected]> Signed-off-by: Joan E <[email protected]>
hyperledger · Sep 19, 2024 · 9cdd346 · 9cdd346
1 parent 6f0e4b3
commit 9cdd346
Show file tree

Hide file tree

Showing 17 changed files with 235 additions and 232 deletions.
diff --git a/docs/private-networks/get-started/start-node.md b/docs/private-networks/get-started/start-node.md
@@ -66,7 +66,7 @@ To run a node that mines blocks at a rate suitable for testing purposes:
 besu --network=dev --miner-enabled --miner-coinbase=0xfe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-http-cors-origins="all" --host-allowlist="*" --rpc-ws-enabled --rpc-http-enabled --data-path=/tmp/tmpDatdir
 ```
 
-You can also use the following [configuration file](../../public-networks/how-to/use-configuration-file/index.md) on the command line to start a node with the same options as above:
+You can also use the following [configuration file](../../public-networks/how-to/configure-besu/index.md) on the command line to start a node with the same options as above:
 
 ```toml
 network="dev"
@@ -107,7 +107,7 @@ You might need to set [`--tx-pool-limit-by-account-percentage`](../../public-net
 
 :::note Sync nodes for BFT
 
-If you're running a node on a [QBFT](../how-to/configure/consensus/qbft.md) or [IBFT 2.0](../how-to/configure/consensus/ibft.md) network, your node must use [fast sync](../../public-networks/get-started/connect/sync-node#fast-synchronization) or [full sync](../../public-networks/get-started/connect/sync-node#run-an-archive-node). 
+If you're running a node on a [QBFT](../how-to/configure/consensus/qbft.md) or [IBFT 2.0](../how-to/configure/consensus/ibft.md) network, your node must use [fast sync](../../public-networks/get-started/connect/sync-node.md#fast-synchronization) or [full sync](../../public-networks/get-started/connect/sync-node.md#run-an-archive-node). 
 
 Full sync is set by default.
 

diff --git a/docs/private-networks/how-to/index.md b/docs/private-networks/how-to/index.md
@@ -11,7 +11,7 @@ This section provides instructional content for private network features.
 The following features are shared with [public networks](../../public-networks/index.md) and the content can be found in the public networks section:
 
 - Configure and manage:
-  - [Use a configuration file](../../public-networks/how-to/use-configuration-file/index.md)
+  - [Use a configuration file](../../public-networks/how-to/configure-besu/index.md)
   - [Configure high availability](../../public-networks/how-to/configure-ha/index.md)
   - [Configure mining](../../public-networks/how-to/use-pow/mining.md)
 - [Use the Besu API](../../public-networks/how-to/use-besu-api/index.md):

diff --git a/docs/private-networks/reference/cli/options.md b/docs/private-networks/reference/cli/options.md
@@ -37,7 +37,7 @@ You can specify Besu options:
 
   For example, set `--miner-coinbase` using the `BESU_MINER_COINBASE` environment variable.
 
-- In a [configuration file](../../../public-networks/how-to/use-configuration-file/index.md).
+- In a [configuration file](../../../public-networks/how-to/configure-besu/index.md).
 
 If you specify an option in more than one place, the order of priority is command line, environment variable, configuration file.
 

diff --git a/docs/public-networks/concepts/genesis-file.md b/docs/public-networks/concepts/genesis-file.md
@@ -19,7 +19,7 @@ The genesis file specifies the [network-wide settings](../reference/genesis-item
 
 :::note
 
-You can specify node-level settings on the command line or in the [node configuration file](../how-to/use-configuration-file/index.md).
+You can specify node-level settings on the command line or in the [node configuration file](../how-to/configure-besu/index.md).
 
 :::
 

diff --git a/docs/public-networks/concepts/transactions/pool.md b/docs/public-networks/concepts/transactions/pool.md
@@ -61,7 +61,7 @@ consistent and transparent transaction order, which is often useful in private b
 
 You can select the sequenced transaction pool by setting [`--tx-pool=sequenced`](../../reference/cli/options.md#tx-pool).
 
-If you set the enterprise configuration profile using [`--profile=enterprise`](../../how-to/use-configuration-file/profile.md#enterpriseprivate-profile) or [`--profile=private`](../../how-to/use-configuration-file/profile.md#enterpriseprivate-profile), the `sequenced` transaction pool is set by default.
+If you set the enterprise configuration profile using [`--profile=enterprise`](../../how-to/configure-besu/profile.md#enterpriseprivate-profile) or [`--profile=private`](../../how-to/configure-besu/profile.md#enterpriseprivate-profile), the `sequenced` transaction pool is set by default.
 
 The sequenced transaction pool suits enterprise environments because it functions like a first-in-first-out (FIFO) queue and processes transactions in the order of submission, regardless of the sender. 
 When the pool reaches capacity, the newer transactions are evicted first, reducing the likelihood of a nonce gap and avoiding the need to resubmit older transactions.

diff --git a/docs/public-networks/get-started/connect/mainnet.md b/docs/public-networks/get-started/connect/mainnet.md
@@ -54,7 +54,7 @@ Save the password you use to generate each key pair in a `.txt` file. You should
 
 ### 3. Start Besu
 
-Run the following command or specify the options in a [configuration file](../../how-to/use-configuration-file/index.md):
+Run the following command or specify the options in a [configuration file](../../how-to/configure-besu/index.md):
 
 ```bash
 besu \

diff --git a/docs/public-networks/get-started/connect/testnet.md b/docs/public-networks/get-started/connect/testnet.md
@@ -46,7 +46,7 @@ If you're also running the consensus client as a validator client, create a test
 
 :::note
 
-If you can't get ETH using the faucet, you can ask for help on the [EthStaker Discord](https://discord.io/ethstaker).
+If you can't get testnet ETH using the faucet, you can ask for help on the [EthStaker Discord](https://discord.gg/ethstaker).
 
 :::
 
@@ -60,7 +60,7 @@ Save the password you use to generate each key pair in a `.txt` file. You should
 
 ### 3. Start Besu
 
-Run the following command or specify the options in a [configuration file](../../how-to/use-configuration-file/index.md):
+Run the following command or specify the options in a [configuration file](../../how-to/configure-besu/index.md):
 
 <Tabs>
 

diff --git a/docs/public-networks/get-started/start-node.md b/docs/public-networks/get-started/start-node.md
@@ -57,7 +57,7 @@ To run a node that mines blocks at a rate suitable for testing purposes:
 besu --network=dev --miner-enabled --miner-coinbase=0xfe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-http-cors-origins="all" --host-allowlist="*" --rpc-ws-enabled --rpc-http-enabled --data-path=/tmp/tmpDatdir
 ```
 
-You can also use the following [configuration file](../how-to/use-configuration-file/index.md) on the command line to start a node with the same options as above:
+You can also use the following [configuration file](../how-to/configure-besu/index.md) on the command line to start a node with the same options as above:
 
 ```toml
 network="dev"

diff --git a/docs/public-networks/how-to/configure-besu/index.md b/docs/public-networks/how-to/configure-besu/index.md
@@ -0,0 +1,113 @@
+---
+title: Configure Besu
+description: Specify options in the Besu configuration file.
+sidebar_position: 1
+tags:
+  - public networks
+  - private networks
+---
+
+# Configure Besu
+
+Besu comes with a [default configuration](#default-configuration) that is suitable for staking.
+
+You can override the default values by specifying [configuration options](../../reference/cli/options.md) on the command line, as environment variables, or in a [TOML configuration file](#toml-configuration-file) that can be reused across node startups.
+
+You can also use a [pre-configured profile](profile.md) for some common use cases or create and apply a [custom profile](profile.md#load-external-profiles).
+
+## Configuration order of precedence
+
+For options specified in multiple places, the order of precedence is as follows:
+
+1. Command line
+2. Environment variable
+3. Configuration file specified by `--config-file`
+4. [Pre-configured profile](profile.md) specified by `--profile`
+5. Default values (used if no other configuration source is available)
+
+For example, if you specify a `config.toml` configuration file and `staker` profile, and an option
+is not found in the environment variables, Besu looks for it in `config.toml`.
+If the option is not found in `config.toml`, Besu looks for it in `staker.toml`.
+If the option is not found in `staker.toml`, Besu uses the default value for that option.
+
+## TOML configuration file
+
+:::note
+The configuration file is used for node-level settings. You can specify network-wide settings in the [genesis file](../../concepts/genesis-file.md).
+:::
+
+Specify the configuration file using the [`--config-file`](../../reference/cli/options.md#config-file) option.
+The configuration file must be a valid TOML file composed of key/value pairs. Each key is the same as the corresponding command line option name without the leading dashes (`--`).
+
+Values must conform to TOML specifications for string, numbers, arrays, and booleans. Specific differences between the command line and the TOML file format are:
+
+- Comma-separated lists on the command line are string arrays in the TOML file.
+- Enclose file paths, hexadecimal numbers, URLs, and &lt;host:port> values in quotes.
+
+Table headings are ignored in TOML files. If you specify a valid Besu option under a table heading in the configuration file, Besu ignores the table heading and reads the option in the same way it does for options not under table headings.
+
+:::tip
+
+The [command line reference](../../reference/cli/options.md) includes configuration file examples for each option.
+
+:::
+
+```toml title="Sample TOML configuration file"
+# Valid TOML config file
+data-path="~/besudata" # Path
+
+# Network
+bootnodes=["enode://001@123:4567", "enode://002@123:4567", "enode://003@123:4567"]
+
+p2p-host="1.2.3.4"
+p2p-port=1234
+max-peers=42
+
+rpc-http-host="5.6.7.8"
+rpc-http-port=5678
+
+rpc-ws-host="9.10.11.12"
+rpc-ws-port=9101
+
+# Chain
+genesis-file="~/genesis.json" # Path to the custom genesis file
+
+# Mining
+miner-enabled=true
+miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"
+```
+
+```bash title="Starting Besu with a configuration file"
+besu --config-file=/home/me/me_node/config.toml
+```
+## Default configuration
+
+The following tables describe important default values of Besu's configuration.
+When using the default configuration, Besu is optimized for staking.
+You can extend these defaults using a [profile](profile.md).
+
+For example, extending the default configuration using the [staker profile](profile.md#staker-profile) directs Besu to use Mainnet, creating a staking-optimized node ready to run with a [validator and consensus client](../../concepts/node-clients.md#consensus-clients).
+
+### Peering
+
+|Configuration option|Default|Description|
+|---------------------------|--------------------|------------------------------------------|
+|[`discovery-enabled`](../../reference/cli/options.md#discovery-enabled)|`true`|Besu assumes the node will automatically discover other Ethereum nodes using P2P.|
+|[`p2p-enabled`](../../reference/cli/options.md#p2p-enabled)|`true`|Besu assumes the node will connect P2P.|
+|[`engine-rpc-enabled`](../../reference/cli/options.md#engine-rpc-enabled)|`true`|Besu assumes the Engine API will be required to communicate with the consensus layer.|
+
+### Storage
+
+|Configuration option|Default|Description|
+|---------------------------|--------------------|------------------------------------------|
+|[`data-storage-format`](../../reference/cli/options.md#data-storage-format)|`BONSAI`|Besu uses [Bonsai Tries](../../concepts/data-storage-formats.md#bonsai-tries), the most space-efficient data storage format.|
+
+### Sync
+
+|Configuration option|Default|Description|
+|---------------------------|--------------------|------------------------------------------|
+|[`sync-mode`](../../reference/cli/options.md#sync-mode)|`SNAP`|Besu syncs using [snap sync](../../get-started/connect/sync-node.md#snap-synchronization), the most time-efficient sync method.|
+
+:::note
+You can see all default configuration values in the [configuration options reference](../../reference/cli/options.md).
+:::
diff --git a/docs/public-networks/how-to/configure-besu/profile.md b/docs/public-networks/how-to/configure-besu/profile.md
@@ -0,0 +1,74 @@
+---
+title: Use a profile 
+sidebar_position: 1
+tags:
+  - public networks
+  - private networks
+---
+
+# Use a profile 
+
+You can load a profile to extend Besu's [default configuration](index.md#default-configuration), using the [`--profile`](../../reference/cli/options.md#profile) option.
+
+Profiles simplify the process of configuring Besu for common use cases. Besu provides the following pre-configured profiles:
+
+- [Minimalist staker profile](#minimalist-staker-profile)
+- [Staker profile](#staker-profile)
+- [Enterprise/Private profile](#enterpriseprivate-profile)
+
+Alternatively, you can customize and [load external profiles](#load-external-profiles).
+
+:::note
+Run `./besu --help` to view all available profiles.
+:::
+
+:::note
+
+A configuration option specified in the configuration file or on the command line 
+[overrides the same option](index.md#configuration-order-of-precedence) set in the profile.
+
+:::
+
+## Minimalist staker profile
+
+[`--profile=MINIMALIST_STAKER`](../../reference/cli/options.md#profile) is optimized for stakers who 
+want to maximize their hardware value but don't want to serve full sets of data to their peers, See the
+[minimalist staker profile on GitHub](https://github.com/hyperledger/besu/blob/main/config/src/main/resources/profiles/minimalist-staker.toml)
+for the custom settings.
+
+## Staker profile
+
+[`--profile=STAKER`](../../reference/cli/options.md#profile) is optimized for stakers who want to 
+maximize their hardware value while also serving full sets of data to their peers. See the
+[staker profile on GitHub](https://github.com/hyperledger/besu/blob/main/config/src/main/resources/profiles/staker.toml)
+for the custom settings.
+
+## Enterprise/Private profile
+
+`ENTERPRISE` and `PRIVATE` are aliases for the same profile. [`--profile=PRIVATE` / `--profile=ENTERPRISE`](../../reference/cli/options.md#profile) 
+supports private network operators and enterprises by handling specific use cases that apply to 
+private network operators. See the [enterprise/private profile on 
+GitHub](https://github.com/hyperledger/besu/blob/main/config/src/main/resources/profiles/enterprise-private.toml)
+for the custom settings.
+
+When using this profile, set [`--sync-mode=FULL`](../../reference/cli/options.md#sync-mode) 
+and [`--data-storage-format=FOREST`](../../reference/cli/options.md#data-storage-format).
+
+## Load external profiles
+
+You can use external profiles to create custom Besu bundles with various plugins and their default options.
+
+Add external profiles to a `profiles` directory under the root Besu directory.
+Run Besu with [`--profile`](../../reference/cli/options.md#profile) set to the external profile
+file name, without the `.toml` extension.
+For example, to load the `profiles/custom_profile.toml` profile, run:
+
+```bash
+besu --profile=custom_profile
+```
+
+:::note
+You can overwrite the directory in which to place external profiles using the `besu.profiles.dir`
+system property.
+:::
+
diff --git a/docs/public-networks/how-to/use-configuration-file/index.md b/docs/public-networks/how-to/use-configuration-file/index.md