nwaku/docs/operators/how-to/configure.md

137 lines
4.8 KiB
Markdown
Raw Normal View History

2022-05-20 12:48:34 +00:00
# Configure a nwaku node
Nwaku can be configured to serve the adaptive needs of different operators.
> :bulb: **Tip:** The recommended configuration method is through environment variables.
## Node configuration methods
One node can be configured using a combination of the following methods:
1. Command line options and flags
2. Environment variables
3. Configuration file (currently, only TOML format is supported)
4. Default value
Note the precedence order, each configuration mechanism overrides the configuration set by one below (e.g., _command line options_ override the configuration set by the _environment variables_ and by the _configuration file_).
### Command line options/flags
The main mechanism to configure the node is via command line options. Any configuration option provided via the command line will override any other configuration mechanism.
> :warning: nwaku is under heavy development. It is likely that configuration will change from one version to another.
>
> If after an upgrade, the node refuses to start, check if any of the command line configuration options provided to the node have been changed or removed.
>
> To overcome this issue, we recommend to configure the node via environment variables.
The configuration options should be provided after the binary name as follows:
```shell
wakunode2 --tcp-port=65000
```
In the case of using docker to run you node you should provide the commandline options after the image name as follows:
```shell
docker run wakuorg/nwaku --tcp-port=65000
```
Run `wakunode2 --help` to get a comprehensive list of configuration options (and its default values):
```shell
$ wakunode2 --help
Usage:
wakunode2 [OPTIONS]...
The following options are available:
--config-file Loads configuration from a TOML file (cmd-line parameters take precedence).
--log-level Sets the log level. [=LogLevel.INFO].
--version prints the version [=false].
<...>
```
Check the configuration tutorials for specific configuration use cases.
### Environment variables
The node can also be configured via environment variables.
> :information_source: Support for configuring the node via environment variables was added in v0.13.0
The environment variable name should be prefixed by the app's name, in this case `WAKUNODE2_` followed by the commandline option in [screaming snake case](https://en.wiktionary.org/wiki/screaming_snake_case).
For example, to set the `--tcp-port` configuration we should call `wakunode2` binary as follows:
```shell
WAKUNODE2_TCP_PORT=65000 wakunode2
```
In the case of using docker to run you node you should start the node using the `-e` command options:
```shell
docker run -e "WAKUNODE2_TCP_PORT=65000" wakuorg/nwaku
```
This is the second configuration method in order of precedence. Any command line configuration option will override the configuration
provided via environment variables.
### Configuration file
The third configuration mechanism in order of precedence is the configuration via a TOML file. The previous mechanims take precedence over this mechanism as explained above.
The configuration file follows the [TOML](https://toml.io/en/) format:
```toml
log-level = "DEBUG"
tcp-port = 65000
```
The path to the TOML file can be specified usin one of the previous configuration mechanisms:
* By passing the `--config-file` command line option:
```shell
wakunode2 --config-file=<path-to-toml-config-file>
```
* By passing the path via environment variables:
```shell
WAKUNODE2_CONFIG_FILE=<path-to-toml-config-file> wakunode2
```
### Configuration default values
As usual, if no configuration option is specified by any of the previous mechanisms, the default configuration will be used.
The default configuration value is listed in the `wakunode2 --help` output:
```shell
$ wakunode2 --help
Usage:
wakunode2 [OPTIONS]...
The following options are available:
--config-file Loads configuration from a TOML file (cmd-line parameters take precedence).
--log-level Sets the log level. [=LogLevel.INFO].
--version prints the version [=false].--tcp-port TCP listening port. [=60000].
--websocket-port WebSocket listening port. [=8000].
<...>
```
## Configuration use cases
This is an index of tutorials explaining how to configure your nwaku node for different use cases.
2022-05-20 12:48:34 +00:00
1. [Connect to other peers](./connect.md)
2. [Configure a domain name](./configure-domain.md)
3. [Use DNS discovery to connect to existing nodes](./configure-dns-disc.md)
4. [Configure store protocol and message store](./configure-store.md)
5. [Generate and configure a node key](./configure-key.md)
6. [Configure websocket transport](./configure-websocket.md)
7. [Run nwaku with rate limiting enabled](./run-with-rln.md)
8. [Configure a REST API node](./configure-rest-api.md)