Document profile files (#1514)

* Document profile files Signed-off-by: Alexandra Tran <[email protected]> * typo Signed-off-by: Alexandra Tran <[email protected]> * add "stakers" to project-words.txt Signed-off-by: Alexandra Tran <[email protected]> * (temp) remove redirect Signed-off-by: Alexandra Tran <[email protected]> * minor fix Signed-off-by: Alexandra Tran <[email protected]> * config file -> profile file Signed-off-by: Alexandra Tran <[email protected]> * update profile files intro Signed-off-by: Alexandra Tran <[email protected]> * address @macfarla feedback Signed-off-by: Alexandra Tran <[email protected]> --------- Signed-off-by: Alexandra Tran <[email protected]>
hyperledger · Feb 17, 2024 · d47de7b · d47de7b
1 parent 093e69e
commit d47de7b
Show file tree

Hide file tree

Showing 16 changed files with 168 additions and 24 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/configuration-file.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/use-configuration-file/index.md) on the command line to start a node with the same options as above:
 
 ```toml
 network="dev"

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/configuration-file.md)
+  - [Use a configuration file](../../public-networks/how-to/use-configuration-file/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/configuration-file.md).
+- In a [configuration file](../../../public-networks/how-to/use-configuration-file/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/configuration-file.md).
+You can specify node-level settings on the command line or in the [node configuration file](../how-to/use-configuration-file/index.md).
 
 :::
 

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/configuration-file.md):
+Run the following command or specify the options in a [configuration file](../../how-to/use-configuration-file/index.md):
 
 ```bash
 besu \

diff --git a/docs/public-networks/get-started/connect/testnet.md b/docs/public-networks/get-started/connect/testnet.md
@@ -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/configuration-file.md):
+Run the following command or specify the options in a [configuration file](../../how-to/use-configuration-file/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/configuration-file.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/use-configuration-file/index.md) on the command line to start a node with the same options as above:
 
 ```toml
 network="dev"

diff --git a/...lic-networks/how-to/configuration-file.md → ...ks/how-to/use-configuration-file/index.md b/...lic-networks/how-to/configuration-file.md → ...ks/how-to/use-configuration-file/index.md
@@ -7,20 +7,35 @@ tags:
   - private networks
 ---
 
-# Use the Hyperledger Besu configuration file
+# Use a configuration file
 
-To specify command line options in a file, use a TOML configuration file.
+You can specify command line options in a TOML configuration file.
+Save the configuration file and reuse it across node startups.
+Specify the configuration file using the [`--config-file`](../../reference/cli/options.md#config-file) CLI option.
 
-Save the configuration file and reuse it across node startups. To specify the configuration file, use the [`--config-file`](../reference/cli/options.md#config-file) option.
-
-To override an option specified in the configuration file, either specify the same option on the command line or as an [environment variable](../reference/cli/options.md#specify-options). For options specified in more than one place, the order of precedence is command line, environment variable, configuration file.
+You can also [use 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).
+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 (`--`).
@@ -34,7 +49,7 @@ Table headings are ignored in TOML files. If you specify a valid Besu option und
 
 :::tip
 
-The [command line reference](../reference/cli/options.md) includes configuration file examples for each option.
+The [command line reference](../../reference/cli/options.md) includes configuration file examples for each option.
 
 :::
 

diff --git a/docs/public-networks/how-to/use-configuration-file/profile.md b/docs/public-networks/how-to/use-configuration-file/profile.md
@@ -0,0 +1,82 @@
+---
+sidebar_position: 1
+---
+
+# Use a profile
+
+To help you get started quickly, Besu provides pre-configured profiles containing custom settings
+for some common use cases.
+You can load these profiles using the [`--profile`](../../reference/cli/options.md#profile) CLI option.
+For example:
+
+```bash
+besu --config-file=config.toml --profile=staker
+```
+
+In this example, `config.toml` is the user-provided [configuration file](index.md), and `staker` is
+the pre-configured profile containing custom settings.
+
+Any configuration options explicitly set in the configuration file or command line will overwrite
+the same options set in the profile.
+See the [configuration order of precedence](index.md#configuration-order-of-precedence) for more information.
+
+You can use the following profiles:
+
+- [Minimalist staker profile](#minimalist-staker-profile)
+- [Staker profile](#staker-profile)
+- [Enterprise/Private profile](#enterpriseprivate-profile)
+
+## Minimalist staker profile
+
+For stakers who want to maximize their hardware value but don't want to serve full sets of data to
+their peers, Besu provides a minimalist staker profile.
+See the
+[minimalist staker profile on GitHub](https://github.com/hyperledger/besu/blob/8b64023a121ea996ef60e4b7e2299c5807683f90/config/src/main/resources/profiles/minimalist-staker.toml)
+for the custom settings.
+
+To use the minimalist staker profile, run Besu with
+[`--profile`](../../reference/cli/options.md#profile) set to `minimalist_staker`:
+
+```bash
+besu --profile=minimalist_staker
+```
+
+## Staker profile
+
+For stakers who want to maximize their hardware value and also want to serve full sets of data to
+their peers, Besu providers a staker profile.
+See the
+[staker profile on GitHub](https://github.com/hyperledger/besu/blob/8b64023a121ea996ef60e4b7e2299c5807683f90/config/src/main/resources/profiles/staker.toml)
+for the custom settings.
+
+To use the staker profile, run Besu with [`--profile`](../../reference/cli/options.md#profile) set to `staker`:
+
+```bash
+besu --profile=staker
+```
+
+## Enterprise/Private profile
+
+For private network operators who want to minimize confusion by setting sensible defaults, Besu
+provides an enterprise/private profile.
+This profile is designed to handle specific use cases for private network operators.
+See the
+[enterprise/private profile on GitHub](https://github.com/hyperledger/besu/blob/8b64023a121ea996ef60e4b7e2299c5807683f90/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 `enterprise` or `private`:
+
+```bash
+besu --profile=enterprise
+```
+
+or
+
+```bash
+besu --profile=private
+```
+
+:::note
+`enterprise` and `private` are aliases for the same profile.
+:::
diff --git a/docs/public-networks/reference/cli/options.md b/docs/public-networks/reference/cli/options.md
@@ -38,7 +38,7 @@ You can specify Besu options:
 
   For example, set `--miner-coinbase` using the `BESU_MINER_COINBASE` environment variable.
 
-- In a [configuration file](../../how-to/configuration-file.md).
+- In a [configuration file](../../how-to/use-configuration-file/index.md).
 
 If you specify an option in more than one place, the order of priority is command line, environment variable, configuration file.
 
@@ -476,7 +476,7 @@ BESU_CONFIG_FILE=/home/me/me_node/config.toml
 
 </Tabs>
 
-The path to the [TOML configuration file](../../how-to/configuration-file.md). The default is `none`.
+The path to the [TOML configuration file](../../how-to/use-configuration-file/index.md). The default is `none`.
 
 ### `data-path`
 
@@ -2672,6 +2672,46 @@ p2p-port="1789"
 
 The P2P listening ports (UDP and TCP). The default is `30303`. You must [expose ports appropriately](../../how-to/connect/configure-ports.md).
 
+### `profile`
+
+<Tabs>
+<TabItem value="Syntax">
+
+```bash
+--profile=<PROFILE>
+```
+
+</TabItem>
+<TabItem value="Example">
+
+```bash
+--profile=staker
+```
+
+</TabItem>
+<TabItem value="Environment variable">
+
+```bash
+BESU_PROFILE=staker
+```
+
+</TabItem>
+<TabItem value="Configuration file">
+
+```bash
+profile="staker"
+```
+
+</TabItem>
+</Tabs>
+
+Loads a pre-configured TOML file containing custom settings for a specific user profile.
+Possible values are:
+
+- [`minimalist_staker`](../../how-to/use-configuration-file/profile.md#minimalist-staker-profile)
+- [`staker`](../../how-to/use-configuration-file/profile.md#staker-profile)
+- [`enterprise` or `private`](../../how-to/use-configuration-file/profile.md#enterpriseprivate-profile) (aliases for the same profile)
+
 ### `pruning-block-confirmations`
 
 <Tabs>

diff --git a/docs/public-networks/reference/cli/subcommands.md b/docs/public-networks/reference/cli/subcommands.md
@@ -306,7 +306,7 @@ besu storage revert-variables --config-file ../besu-local-nodes/config/besu/besu
 
 Reverts the modifications made by the [variables storage feature](https://github.com/hyperledger/besu/pull/5471).
 If you need to downgrade Besu, first run this subcommand specifying the path to
-the [configuration file](../../how-to/configuration-file.md) normally used to
+the [configuration file](../../how-to/use-configuration-file/index.md) normally used to
 start Besu.
 
 ## `validate-config`
@@ -331,4 +331,4 @@ besu validate-config --config-file ../besu-local-nodes/config/besu/besu1.conf
 
 </Tabs>
 
-Performs basic syntax validation of the specified [configuration file](../../how-to/configuration-file.md). Checks TOML syntax (for example, valid format and unmatched quotes) and flags unknown options. Doesn't check data types, and doesn't check dependencies between options (this is done at Besu startup).
+Performs basic syntax validation of the specified [configuration file](../../how-to/use-configuration-file/index.md). Checks TOML syntax (for example, valid format and unmatched quotes) and flags unknown options. Doesn't check data types, and doesn't check dependencies between options (this is done at Besu startup).
diff --git a/docs/public-networks/tutorials/besu-teku-mainnet.md b/docs/public-networks/tutorials/besu-teku-mainnet.md
@@ -49,7 +49,7 @@ You should also have a `.json` file for each validator key pair.
 
 ## 4. Start Besu
 
-Run the following command or specify the options in a [configuration file](../how-to/configuration-file.md):
+Run the following command or specify the options in a [configuration file](../how-to/use-configuration-file/index.md):
 
 ```bash
 besu \

diff --git a/docs/public-networks/tutorials/besu-teku-testnet.md b/docs/public-networks/tutorials/besu-teku-testnet.md
@@ -59,7 +59,7 @@ Save the password you use to generate each key pair in a `.txt` file. You should
 
 ## 4. Start Besu
 
-Run the following command or specify the options in a [configuration file](../how-to/configuration-file.md):
+Run the following command or specify the options in a [configuration file](../how-to/use-configuration-file/index.md):
 
 <Tabs>
 

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -293,6 +293,12 @@ const config = {
             from: "/private-networks/tutorials/permissioning/upgrade-contracts",
             to: "/private-networks/how-to/use-permissioning/onchain",
           },
+          /*
+          {
+            from: "/public-networks/how-to/configuration-file",
+            to: "/public-networks/how-to/use-configuration-file",
+          },
+          */
         ],
       },
     ],

diff --git a/project-words.txt b/project-words.txt
@@ -577,6 +577,7 @@ ssszzz
 stackblitz
 stackblitzrc
 staker
+stakers
 statefulset
 storepass
 storeraw

diff --git a/src/css/custom.css b/src/css/custom.css
@@ -290,20 +290,20 @@ html[data-theme="dark"] .header-dockerhub-link::before {
 }
 
 h1 {
-  font-size: 32px;
+  font-size: 34px;
   padding-top: 5px;
 }
 
 h2 {
-  font-size: 24px;
+  font-size: 28px;
 }
 
 h3 {
-  font-size: 18px;
+  font-size: 24px;
 }
 
 h4 {
-  font-size: 16px;
+  font-size: 19px;
 }
 
 .homepageContainer {
-Original file line number
+Diff line change
@@ Expand Up @@
     :::note
-    You can specify node-level settings on the command line or in the [node configuration file](../how-to/configuration-file.md).
+    You can specify node-level settings on the command line or in the [node configuration file](../how-to/use-configuration-file/index.md).
     :::
@@ Expand Down @@