fixes 1611: adds page for boilerplate config and clarifies profiles

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.
 

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):

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.
 

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).
 
 :::
 

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.

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 \

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>
 

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"

docs/public-networks/how-to/configure-besu/index.md

@@ -0,0 +1,117 @@
+---
+title: Configure Besu
+description: Specify options in the Besu configuration file.
+tags:
+  - public networks
+  - private networks
+---
+
+Besu is [highly-configurable](index.md#configuration-order-of-precedence), yet its [default configurations](#besu-defaults) provide a viable boilerplate.
+
+A TOML configuration file is used to simplify overriding the default configuration settings and reuse of configurations across node startups.
+
+Specify the configuration file using the [`--config-file`](../../reference/cli/options.md#config-file) CLI option. Both the default configuration and configuration files may be [used alongside a pre-configured profile](profile.md) for some common use cases.
+
+:::note
+
+The configuration file is used for node-level settings. You can specify network-wide settings in the [genesis file](../../concepts/genesis-file.md).
+
+:::
+
+## 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 specification
+
+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 <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
+```
+## Besu defaults
+
+Presented below is a high level overview of the opinionated default configurations of vanilla Besu. By applying the defaults, a node is optimized for staking. These defaults may be extended with a [pre-configured profile](profile.md) to support common use cases.
+
+For example, using the [Staker profile](profile.md#staker-profile) with the boilerplate config directs Besu to use Mainnet, creating a staking-optimized node ready to run with a [validator](https://ethereum.org/en/developers/docs/nodes-and-clients/node-architecture/#validators) and [consensus client](https://ethereum.org/en/developers/docs/nodes-and-clients/node-architecture/#consensus-client).
+
+### Configuration
+
+|Command|Default|Notes|
+|---------------------------|--------------------|------------------------------------------|
+|[`config-file`](../../reference/cli/options.md#config-file)|None|Vanilla Besu assumes no configuration file|
+
+
+### Peering
+
+|Command|Default|Notes|
+|---------------------------|--------------------|------------------------------------------|
+|[`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
+
+|Command|Default|Notes|
+|---------------------------|--------------------|------------------------------------------|
+|[`data-storage-format`](../../reference/cli/options.md#data-storage-format)|BONSAI|Besu applies the most space-efficient storage method|
+
+### Sync
+
+|Command|Default|Notes|
+|---------------------------|--------------------|------------------------------------------|
+|[`sync-mode`](../../reference/cli/options.md#sync-mode)|SNAP|Besu applies the [snap sync mode](../../get-started/connect/sync-node.md#snap-synchronization) as the most time-efficient sync method|
+
+:::note
+For a comprehensive understanding, all defaults are provided in the [reference](../../reference/cli/options.md).
+:::

docs/public-networks/how-to/configure-besu/profile.md

@@ -0,0 +1,79 @@
+---
+title: Use a profile 
+sidebar_position: 1
+tags:
+  - public networks
+  - private networks
+---
+
+# Use a profile 
+
+Load a profile using the [`--profile` CLI option](../../reference/cli/options.md#profile).
+
+:::note
+Run `./besu --help` to view all available profiles.
+:::
+
+You can optionally use profiles to extend Besu's configuration. Combined with the 
+[boilerplate configuration](index.md#besu-defaults), profiles simplify the process of applying 
+viable defaults. Besu's pre-configured profiles optimize for the following use cases:
+
+- [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
+
+A configuration explicitly set in the configuration file or command line will 
+[override the same option/s](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.
+
+
+To use the enterprise/private profile, run Besu with
+[`--profile`](../../reference/cli/options.md#profile) set to `--profile=PRIVATE` or `--profile=ENTERPRISE`, 
+and use [`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.
+:::
+