Skip to main content

Node Configuration Methods

Waku nodes can be configured using a combination of the following methods:

  1. Command line options and flags
  2. Environment variables
  3. TOML configuration files (currently the only supported format)
  4. Default values

Take note of the precedence order: Each configuration method overrides the one below it (e.g., command line options override environment variables and configuration files).

Command line options

Node configuration is primarily done using command line options, which override other methods. Specify configuration options by providing them in this format after the binary name:

./build/wakunode2 --tcp-port=65000

When running your node with Docker, provide the command line options after the image name in this format:

docker run statusteam/nim-waku --tcp-port=65000

Environment variables

Nodes can be configured using environment variables by prefixing the variable name with WAKUNODE2_ and using the configuration option in SCREAMING_SNAKE_CASE format.

To set the tcp-port configuration, the wakunode2 binary should be called in this format:

WAKUNODE2_TCP_PORT=65000 ./build/wakunode2

When running your node with Docker, start the node using the -e command option:

docker run -e "WAKUNODE2_TCP_PORT=65000" statusteam/nim-waku

This is the second configuration method in order of precedence. Command Line Options override environment variables.

Configuration files

Nodes can be configured using a configuration file following the TOML format:

TOML Config File
log-level = "DEBUG"
tcp-port = 65000
topic = ["/waku/2/default-waku/proto"]
metrics-logging = false

The config-file configuration option lets you specify the configuration file path:

./build/wakunode2 --config-file=[TOML CONFIGURATION FILE]

You can also specify the configuration file via environment variables:

# Using environment variables

# Using environment variables with Docker
docker run -e "WAKUNODE2_CONFIG_FILE=[TOML CONFIGURATION FILE]" statusteam/nim-waku

This is the third configuration method in order of precedence. Command Line Options and Environment Variables override configuration files.

Default configuration values

The default configuration is used when no other options are specified. By default, a nwaku node does the following:

  • Generate a new Node Key and PeerID.
  • Listen for incoming libp2p connections on the default TCP port (60000).
  • Subscribe to the default Pub/Sub topic (/waku/2/default-waku/proto).
  • Enable the Relay protocol for relaying messages.
  • Enable the Store protocol as a client, allowing it to query peers for historical messages but not store any message itself.

To see the default values of all configuration options, run wakunode2 --help:

./build/wakunode2 --help

To explore the available node configuration options, have a look at the Node Configuration Options guide.