logos-messaging/docs.waku.org
1
0
Fork 0
mirror of https://github.com/logos-messaging/docs.waku.org.git synced 2026-08-26 20:11:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Split website in 4:

Browse Source 
- build
- run node
- learn
- research
This commit is contained in:
fryorcraken
2025-09-29 22:47:58 +10:00
parent 7b6b15aad5
commit cd64e332a7
29 changed files with 211 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/run-node/build-source.md
+117
View File
@@ -0,0 +1,117 @@
---
title: Build Nwaku from Source
hide_table_of_contents: true
---
This guide provides detailed steps to build a `nwaku` node from the source code to access the latest development version or a specific commit or release of `nwaku`. For your convenience, you may want to [download a pre-compiled binary](https://github.com/waku-org/nwaku/tags) instead.
:::info
- A minimum of 2GB of RAM is required to build `nwaku`.
- Nwaku is available for Linux and macOS, with experimental Windows support.
:::
## Prerequisites
To build `nwaku`, you need the standard developer tools, including a C compiler, GNU Make, Bash, Git, Rustup, and PostgreSQL client library.
```mdx-code-block
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
```
<Tabs>
<TabItem value="debian" label="Debian and Ubuntu">
```shell
sudo apt-get install build-essential git libpq5 jq
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
```
</TabItem>
<TabItem value="fedora" label="Fedora">
```shell
sudo dnf install @development-tools git libpq-devel which
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
</TabItem>
<TabItem value="arch" label="Arch Linux">
```shell
# Using your favoured AUR helper
sudo [AUR HELPER] -S base-devel git postgresql-libs
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
</TabItem>
<TabItem value="mac" label="MacOS (Homebrew)">
```shell
brew install cmake git postgresql@15 rustup-init
# Create a symbolic link to libpq.5.dylib in /usr/local/lib/
sudo mkdir -p /usr/local/lib/
sudo ln -s /opt/homebrew/opt/postgresql@15/lib/libpq.5.dylib /usr/local/lib/libpq.dylib
```
</TabItem>
</Tabs>
## Clone the repository
Get the source code from the GitHub repository. The default branch is `master`, the release candidate for major updates.
```shell
git clone https://github.com/waku-org/nwaku
cd nwaku
```
:::tip
You can use `git tag -l` to check specific version tags.
:::
## Build the binary
Build the `nwaku` binary:
```shell
make wakunode2
```
The first `make` invocation updates to all Git submodules. After each `git pull`, run `make update` to keep the submodules updated in the future.
```shell
make update
```
## Run the binary
Nwaku will create the `wakunode2` binary in the `./build/` directory.
```shell
# Run with default configuration
./build/wakunode2
# See available command line options
./build/wakunode2 --help
```
To learn more about running nwaku, have a look at these guides:
- [Run a Nwaku Node](/guides/nwaku/run-node#run-the-node)
- [Run Nwaku in a Docker Container](/guides/nwaku/run-docker)
- [Run Nwaku with Docker Compose](/guides/nwaku/run-docker-compose)
- [Node Configuration Methods](/guides/nwaku/config-methods)
## Run test suite
Run the tests for Waku:
```shell
make test
```
:::tip Congratulations!
You have successfully built the `nwaku` binary from the source code. Have a look at the [Node Configuration Examples](/guides/nwaku/configure-nwaku) guide to learn how to configure `nwaku` for different use cases.
:::
docs/run-node/config-methods.md
+100
View File
@@ -0,0 +1,100 @@
---
title: Node Configuration Methods
hide_table_of_contents: true
---
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
:::info
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](/guides/nwaku/config-options) by providing them in this format after the binary name:
```shell
./build/wakunode2 --tcp-port=65000
```
When running your node with Docker, provide the command line options after the image name in this format:
```shell
docker run wakuorg/nwaku --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](https://en.wiktionary.org/wiki/screaming_snake_case) format.
To set the `tcp-port` configuration, the `wakunode2` binary should be called in this format:
```shell
WAKUNODE2_TCP_PORT=65000 ./build/wakunode2
```
When running your node with Docker, start the node using the `-e` command option:
```shell
docker run -e "WAKUNODE2_TCP_PORT=65000" wakuorg/nwaku
```
:::info
This is the second configuration method in order of precedence. [Command Line Options](#command-line-options) override environment variables.
:::
## Configuration files
Nodes can be configured using a configuration file following the [TOML](https://toml.io/en/) format:
```toml title="TOML Config File" showLineNumbers
log-level = "DEBUG"
tcp-port = 65000
topic = ["/waku/2/default-waku/proto"]
metrics-logging = false
```
The `config-file` [configuration option](/guides/nwaku/config-options) lets you specify the configuration file path:
```shell
./build/wakunode2 --config-file=[TOML CONFIGURATION FILE]
```
You can also specify the configuration file via environment variables:
```shell
# Using environment variables
WAKUNODE2_CONFIG_FILE=[TOML CONFIGURATION FILE] ./build/wakunode2
# Using environment variables with Docker
docker run -e "WAKUNODE2_CONFIG_FILE=[TOML CONFIGURATION FILE]" wakuorg/nwaku
```
:::info
This is the third configuration method in order of precedence. [Command Line Options](#command-line-options) and [Environment Variables](#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](/guides/nwaku/config-options), run `wakunode2 --help`:
```shell
./build/wakunode2 --help
```
:::tip
To explore the available node configuration options, have a look at the [Node Configuration Options](/guides/nwaku/config-options) guide.
:::
docs/run-node/config-options.md
+177
View File
@@ -0,0 +1,177 @@
---
title: Node Configuration Options
hide_table_of_contents: true
---
Here are the available node configuration options, along with their default values and descriptions:
## Application-level config
| Name | Default Value | Description |
| ----------------- | --------------------------- | ---------------------------------------------------------------------------------------------------- |
| `config-file` | | Loads configuration from a TOML file (cmd-line parameters take precedence) |
| `protected-shard` | `newSeq[ProtectedShard](0)` | Shards and its public keys to be used for message validation, shard:pubkey. Argument may be repeated |
## Log config
| Name | Default Value | Description |
| ------------ | ------------------------ | -------------------------------------------------------------------------------------------------- |
| `log-level` | `logging.LogLevel.INFO` | Sets the log level for process. Supported levels: TRACE, DEBUG, INFO, NOTICE, WARN, ERROR or FATAL |
| `log-format` | `logging.LogFormat.TEXT` | Specifies what kind of logs should be written to stdout. Supported formats: TEXT, JSON |
## General node config
| Name | Default Value | Description |
| --------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cluster-id` | `0` | Cluster id that the node is running in. Node in a different cluster id is disconnected |
| `agent-string` | `nwaku` | Node agent string which is used as identifier in network |
| `nodekey` | | P2P node private key as 64-char hex string |
| `listen-address` | `defaultListenAddress()` | Listening address for LibP2P (and Discovery v5, if enabled) traffic |
| `tcp-port` | `60000` | TCP listening port |
| `ports-shift` | `0` | Add a shift to all port numbers |
| `nat` | any | Specify method to use for determining public address. Must be one of: any, none, upnp, pmp, extip:IP |
| `ext-multiaddr` | | External multiaddresses to advertise to the network. Argument may be repeated |
| `ext-multiaddr-only` | `false` | Only announce external multiaddresses |
| `max-connections` | `50` | Maximum allowed number of libp2p connections |
| `relay-service-ratio` | `"60:40"` | This percentage ratio represents the relay peers to service peers. For example, 60:40, tells that 60% of the max-connections will be used for relay protocol and the other 40% of max-connections will be reserved for other service protocols (e.g., filter, lightpush, store, metadata, etc.) |
| `peer-store-capacity` | | Maximum stored peers in the peerstore |
| `peer-persistence` | `false` | Enable peer persistence |
## DNS addrs config
| Name | Default Value | Description |
| ----------------------- | ------------------------ | ------------------------------------------------------------------------------------ |
| `dns-addrs` | `true` | Enable resolution of `dnsaddr`, `dns4` or `dns6` multiaddrs |
| `dns-addrs-name-server` | `["1.1.1.1", "1.0.0.1"]` | DNS name server IPs to query for DNS multiaddrs resolution. Argument may be repeated |
| `dns4-domain-name` | | The domain name resolving to the node's public IPv4 address |
## Relay config
| Name | Default Value | Description |
| -------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `relay` | `true` | Enable relay protocol: true\|false |
| `relay-peer-exchange` | `false` | Enable gossipsub peer exchange in relay protocol: true\|false |
| `rln-relay` | `false` | Enable spam protection through rln-relay: true\|false |
| `rln-relay-cred-path` | | The path for persisting rln-relay credential |
| `rln-relay-membership-index` | | The index of the onchain commitment to use |
| `rln-relay-dynamic` | `false` | Enable waku-rln-relay with on-chain dynamic group management: true\|false |
| `rln-relay-id-key` | | Rln relay identity secret key as a Hex string |
| `rln-relay-id-commitment-key` | | Rln relay identity commitment key as a Hex string |
| `rln-relay-eth-client-address` | `ws://localhost:8540/` | WebSocket address of an Ethereum testnet client e.g., `ws://localhost:8540/` |
| `rln-relay-eth-contract-address` | | Address of membership contract on an Ethereum testnet |
| `rln-relay-eth-private-key` | | Private key for broadcasting transactions |
| `execute` | `false` | Runs the registration function on-chain. By default, a dry-run will occur |
| `rln-relay-cred-password` | | Password for encrypting RLN credentials |
| `rln-relay-bandwidth-threshold` | `0 # to maintain backwards compatibility` | Message rate in bytes/sec after which verification of proofs should happen |
| `staticnode` | | Peer multiaddr to directly connect with. Argument may be repeated |
| `keep-alive` | `false` | Enable keep-alive for idle connections: true\|false |
| `pubsub-topic` | | Default pubsub topic to subscribe to. Argument may be repeated. **Deprecated!** Please use `shard` and/or `content-topic` instead |
| `shard` | | Shard to subscribe to. Argument may be repeated |
| `num-shards-in-network` | | Number of shards in the network. Used to map content topics to shards when using autosharding |
| `content-topic` | | Default content topic to subscribe to. Argument may be repeated |
| `reliability` | `false` | Enable experimental reliability protocol true\|false |
## Store and message store config
| Name | Default Value | Description |
| -------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `store` | `false` | Enable/disable waku store protocol |
| `storenode` | | Peer multiaddress to query for storage |
| `store-message-retention-policy` | `time:172800` | Message store retention policy. Time retention policy: `time:<seconds>`. Capacity retention policy: `capacity:<count>`. Size retention policy: `size:<xMB/xGB>`. Set to `none` to disable |
| `store-message-db-url` | `sqlite://store.sqlite3` | The database connection URL for persistent storage |
| `store-message-db-vacuum` | `false` | Enable database vacuuming at start. Only supported by SQLite database engine |
| `store-message-db-migration` | `true` | Enable database migration at start |
## Store Sync
| Name | Default Value | Description |
| ------------------------- | --------------- | ------------------------------------------------------------------- |
| `store-sync` | `false` | Enable/disable waku store sync protocol |
| `store-sync-interval` | `300` 5 minutes | Interval between store synchronization attempts |
| `store-sync-range` | `3600` 1 hour | Amount of time to sync |
| `store-sync-relay-jitter` | `20` seconds | Sync range offset to account for relay's message propagation jitter |
## Filter config
| Name | Default Value | Description |
| ----------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------- |
| `filter` | `false` | Enable filter protocol: true\|false |
| `filternode` | | Peer multiaddr to request content filtering of messages |
| `filter-subscription-timeout` | `300 # 5 minutes` | Timeout for filter subscription without ping or refresh it, in seconds. Only for v2 filter protocol |
| `filter-max-peers-to-serve` | `1000` | Maximum number of peers to serve at a time. Only for v2 filter protocol |
| `filter-max-criteria` | `1000` | Maximum number of pubsub and content topic combinations per peer at a time. Only for v2 filter protocol |
## Light push config
| Name | Default Value | Description |
| --------------- | ------------- | --------------------------------------------------------- | ----- |
| `lightpush` | `false` | Enable lightpush protocol: true | false |
| `lightpushnode` | | Peer multiaddr to request lightpush of published messages |
## REST HTTP config
| Name | Default Value | Description |
| --------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rest` | `false` | Enable Waku REST HTTP server: true\|false |
| `rest-address` | `127.0.0.1` | Listening address of the REST HTTP server |
| `rest-port` | `8645` | Listening port of the REST HTTP server |
| `rest-relay-cache-capacity` | `30` | Capacity of the Relay REST API message cache |
| `rest-admin` | `false` | Enable access to REST HTTP Admin API: true\|false |
| `rest-allow-origin` | | Allow cross-origin requests from the specified origin. When using the REST API in a browser, specify the origin host to get a valid response from the node REST HTTP server. This option may be repeated and can contain wildcards (?,\*) for defining URLs and ports such as `localhost:*`, `127.0.0.1:8080`, or allow any website with `*` |
## Metrics config
| Name | Default Value | Description |
| ------------------------ | ------------- | ----------------------------------------- |
| `metrics-server` | `false` | Enable the metrics server: true\|false |
| `metrics-server-address` | `127.0.0.1` | Listening address of the metrics server |
| `metrics-server-port` | `8008` | Listening HTTP port of the metrics server |
| `metrics-logging` | `true` | Enable metrics logging: true\|false |
## DNS discovery config
| Name | Default Value | Description |
| --------------------------- | ------------------------ | ------------------------------------------------------------ |
| `dns-discovery` | `false` | Enable discovering nodes via DNS |
| `dns-discovery-url` | | URL for DNS node list in format `'enrtree://<key\>@<fqdn\>'` |
| `dns-discovery-name-server` | `["1.1.1.1", "1.0.0.1"]` | DNS name server IPs to query. Argument may be repeated |
| `rendezvous` | `true` | Enable waku rendezvous discovery server |
## Discv5 config
| Name | Default Value | Description |
| ------------------------ | ------------- | -------------------------------------------------------------------------------------------------- |
| `discv5-discovery` | `false` | Enable discovering nodes via Node Discovery v5 |
| `discv5-udp-port` | `9000` | Listening UDP port for Node Discovery v5 |
| `discv5-bootstrap-node` | | Text-encoded ENR for bootstrap node. Used when connecting to the network. Argument may be repeated |
| `discv5-enr-auto-update` | `false` | Discovery can automatically update its ENR with the IP address |
| `discv5-table-ip-limit` | `10` | Maximum amount of nodes with the same IP in discv5 routing tables |
| `discv5-bucket-ip-limit` | `2` | Maximum amount of nodes with the same IP in discv5 routing table buckets |
| `discv5-bits-per-hop` | `1` | Kademlia's b variable, increase for less hops per lookup |
## Waku peer exchange config
| Name | Default Value | Description |
| -------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
| `peer-exchange` | `false` | Enable waku peer exchange protocol (responder side): true\|false |
| `peer-exchange-node` | | Peer multiaddr to send peer exchange requests to. (enables peer exchange protocol requester side) |
## WebSocket config
| Name | Default Value | Description |
| ---------------------------- | ------------- | ------------------------------------------------------ |
| `websocket-support` | `false` | Enable websocket: true\|false |
| `websocket-port` | `8000` | WebSocket listening port |
| `websocket-secure-support` | `false` | Enable secure websocket: true\|false |
| `websocket-secure-key-path` | | Secure websocket key path: '/path/to/key.txt' |
| `websocket-secure-cert-path` | | Secure websocket Certificate path: '/path/to/cert.txt' |
## Non-relay, request-response protocol DOS protection configuration
| Name | Default Value | Description |
| ------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rate-limit` | | This is a repeatable option. Each can describe a specific rate limit configuration for a particular protocol.<br />Formatted as:`<protocol>:volume/period<time-unit>`<br />- if protocol is not given, settings will be taken as default for un-set protocols. Ex: `80/2s`<br />-Supported protocols are: `lightpush`\|`filter`\|`px`\|`store`\|`storev2`\|`storev3`<br />-volume must be an integer value, representing number of requests over the period of time allowed.<br />-period\<time-unit\> must be an integer with defined unit as one of `h`\|`m`\|`s`\|`ms`<br />- `storev2` and `storev3` takes precedence over `store` which can easy set both store protocols at once.<br />- In case of multiple set of the same protocol limit, last one will take place.<br />- if config is not set, - which is the default - means unlimited requests are allowed.<br />-filter has a bit different approach. It has a default setting applied if not overridden. Rate limit setting for filter will be applied per subscriber-peers, not globally - it must be considered when changing the setting.<br /><br />Examples:<br />`--rate-limit="100/1s"` - default for all protocols if not set otherwise.<br />`--rate-limit="lightpush:0/0s"` - lightpush protocol will not be rate-limited.<br />`--rate-limit="store:130/1500ms"` - both store-v3 and store-v2 will apply 130 request per each 1500ms separately.<br />`--rate-limit="px:10/1h"` PeerExchange will serve only 10 requests every hour.<br />`--rate-limit="filter:8/5m"` - will allow 8 subs/unsubs/ping requests for each subscriber within every 5 min. |
:::tip
To configure your node using the provided configuration options, have a look at the [Node Configuration Methods](/guides/nwaku/config-methods) guide.
:::
docs/run-node/configure-discovery.md
+113
View File
@@ -0,0 +1,113 @@
---
title: Configure Peer Discovery
hide_table_of_contents: true
---
This guide provides detailed steps to configure a `nwaku` node to discover and connect with peers in the Waku Network.
:::info
You can configure a `nwaku` node to use multiple peer discovery mechanisms simultaneously.
:::
## Configure static peers
You can provide [static peers](/learn/concepts/static-peers) to a `nwaku` node during startup using the `staticnode` configuration option. To connect to multiple peers on startup, repeat the `staticnode` option:
```shell
./build/wakunode2 \
--staticnode=[PEER MULTIADDR 1] \
--staticnode=[PEER MULTIADDR 2]
```
For example, consider a `nwaku` node that connects to two static peers on the same local host (IP: `0.0.0.0`) using TCP ports `60002` and `60003`:
```shell
./build/wakunode2 \
--staticnode=/ip4/0.0.0.0/tcp/60002/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H \
--staticnode=/ip4/0.0.0.0/tcp/60003/p2p/16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ
```
## Configure DNS discovery
To enable [DNS Discovery](/learn/concepts/dns-discovery) in a `nwaku` node, use the following configuration options:
- `dns-discovery`: Enables `DNS Discovery` on the node (disabled by default).
- `dns-discovery-url`: URL for DNS node list in the format `enrtree://<key>@<fqdn>` where `<fqdn>` is the fully qualified domain name and `<key>` is the base32 encoding of the compressed 32-byte public key that signed the list at that location.
- `dns-discovery-name-server` (optional): DNS name server IPs to query. You can repeat this option to provide multiple DNS name servers.
```shell
./build/wakunode2 \
--dns-discovery=true \
--dns-discovery-url=enrtree://[PUBLIC KEY]@[DOMAIN NAME] \
--dns-discovery-name-server=[DNS NAME SERVER IP]
```
:::info
If you omit the `dns-discovery-name-server` option, `nwaku` will attempt to use the CloudFlare servers `1.1.1.1` and `1.0.0.1`.
:::
For example, consider a `nwaku` node that enables `DNS Discovery`, connects to a DNS node list, and queries the IPs `8.8.8.8` and `8.8.4.4`:
```shell
./build/wakunode2 \
--dns-discovery=true \
--dns-discovery-url=enrtree://AIRVQ5DDA4FFWLRBCHJWUWOO6X6S4ZTZ5B667LQ6AJU6PEYDLRD5O@sandbox.waku.nodes.status.im \
--dns-discovery-name-server=8.8.8.8 \
--dns-discovery-name-server=8.8.4.4
```
## Configure Discv5
To enable [Discv5](/learn/concepts/discv5) in a `nwaku` node, use the following configuration options:
- `discv5-discovery`: Enables `Discv5` on the node (disabled by default).
- `discv5-bootstrap-node`: ENR for `Discv5` routing table bootstrap node. You can repeat this option to provide multiple bootstrap entries.
```shell
./build/wakunode2 \
--discv5-discovery=true \
--discv5-bootstrap-node=[DISCV5 ENR BOOTSTRAP ENTRY 1] \
--discv5-bootstrap-node=[DISCV5 ENR BOOTSTRAP ENTRY 2]
```
For example, consider a `nwaku` node that enables `Discv5` and bootstraps its routing table using a static `ENR`:
```shell
./build/wakunode2 \
--discv5-discovery=true \
--discv5-bootstrap-node=enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw
```
:::info
When Discv5 is enabled and used with [DNS Discovery](#configure-dns-discovery), the `nwaku` node will attempt to bootstrap the Discv5 routing table by extracting `ENRs` from peers discovered through DNS.
:::
## Configure peer exchange
To enable [Peer Exchange](/learn/concepts/peer-exchange) in a `nwaku` node, use the following configuration options:
- `peer-exchange`: Enables `Peer Exchange` on the node as a responder (disabled by default).
- `peer-exchange-node` (optional): Multiaddr for bootstrap node with the peer exchange protocol enabled.
```shell
./build/wakunode2 \
--peer-exchange=true \
--peer-exchange-node=[PEER MULTIADDR WITH EXCHANGE ENABLED]
```
For example, consider two `nwaku` nodes configured as a `server` (peer exchange responder node) and `client` (node using peer exchange) on the same local host (IP: `0.0.0.0`):
```shell title="Server: Nwaku Node with Peer Exchange Enabled"
./build/wakunode2 --peer-exchange=true
```
```shell title="Client: Nwaku Node Bootstrapping with Peer Exchange"
./build/wakunode2 \
--tcp-port=30305 \
--ports-shift=1 \
--peer-exchange-node=/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmLCe6zVqCS6KMqqRbbhyoJjfYZGr1Q3thTSbyKzibQkFR
```
:::info
`nwaku` provides a [`relay-peer-exchange`](/guides/nwaku/config-options#relay-config) option via `libp2p` for peer exchange, allowing network growth through neighbouring nodes. However, this feature can compromise security and network robustness, so we recommend only using it in high-trust environments.
:::
docs/run-node/configure-nwaku.md
+281
View File
@@ -0,0 +1,281 @@
---
title: Node Configuration Examples
hide_table_of_contents: true
---
This guide provides detailed steps to configure a `nwaku` node for different use cases.
## Connect to other peers
To join the Waku Network, nodes must [bootstrap](/learn/glossary#bootstrapping) for an entry point before discovering more peers. Nwaku provides multiple [peer discovery](/learn/concepts/peer-discovery) mechanisms:
- [Configure Static Peers](/guides/nwaku/configure-discovery#configure-static-peers)
- [Configure DNS Discovery](/guides/nwaku/configure-discovery#configure-dns-discovery)
- [Configure Discv5](/guides/nwaku/configure-discovery#configure-discv5)
- [Configure Peer Exchange](/guides/nwaku/configure-discovery#configure-peer-exchange)
## Configure a domain name
You can set up an IPv4 DNS domain name that resolves to the public IPv4 address of a node using the `dns4-domain-name` option. This allows the node's publicly announced multiaddrs to use the `/dns4` scheme.
```shell
./build/wakunode2 --dns4-domain-name=[DOMAIN NAME]
```
For example, consider the domain name `nwakunode.com`, which resolves to a `nwaku` node:
```shell
./build/wakunode2 --dns4-domain-name=nwakunode.com
```
Browser nodes can only connect to nodes with a domain name and secure WebSocket (`wss`) configured. These nodes will generate a discoverable ENR with `/wss` as the multiaddr and `/dns4` as the domain name. This configuration is essential for verifying domain certificates when establishing a secure connection.
:::info
This example describes configuring a domain name that resolves to your node's IP address and is unrelated to [DNS Discovery](/learn/concepts/dns-discovery).
:::
:::tip
You can use the domain name provided by your cloud provider to configure the domain name for your node.
:::
## Configure store protocol and message store
To enable message caching and serve them to network peers, enable the [Store protocol](/learn/concepts/protocols#store) using the following configuration options:
- `store`: Enables storing messages to serve them to peers (disabled by default).
- `store-message-retention-policy`: Retention policy of the store node (how long messages will be stored). Three different retention policies are supported:
- Time retention policy: `time:<duration-in-seconds>` (e.g., `time:14400`)
- Capacity retention policy: `capacity:<messages-count>` (e.g, `capacity:25000`)
- Size retention policy: `size:<storage-in-MB/GB>` (e.g, `size:512MB` or `size:10GB`)
- Set this option to `none` to disable the retention policy. If you omit this option, it will default to `time:172800` (48 hours).
- `store-message-db-url`: Database connection URL for storing messages in the [SQLAlchemy database URL format](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls). Setting this option to an empty string will instruct the node to use the fallback in-memory message store. If you omit this option, it will default to `sqlite://store.sqlite3`.
```shell
./build/wakunode2 \
--store=true \
--store-message-retention-policy=[MESSAGE RETENTION POLICY] \
--store-message-db-url=[DATABASE CONNECTION URL]
```
For example, consider a `nwaku` node that is configured to be a `Store` protocol and retain messages received in the last `21600` seconds (6 hours):
```shell
./build/wakunode2 \
--store=true \
--store-message-retention-policy=time:21600 \
--store-message-db-url=sqlite://store.sqlite3
```
You can configure `nwaku` as a `Store client` using the `storenode` option. This allows the node to query peers for historical messages but not store any message itself.
```shell
./build/wakunode2 --storenode=[STORE PEER MULTIADDR]
```
For example, consider a `nwaku` node that does not store messages but can query peers for historical messages:
```shell
./build/wakunode2 --storenode=/dns4/node-01.ac-cn-hongkong-c.waku.sandbox.status.im/tcp/30303/p2p/16Uiu2HAmSJvSJphxRdbnigUV5bjRRZFBhTtWFTSyiKaQByCjwmpV
```
## Configure store sync
To enable synchronization between stores, enable the protocol via the configuration options below;
- `store-sync`: Enable store sync protocol (disable by default).
- `store-sync-interval`: Interval between store synchronization attempts, in seconds (300s default).
- `store-sync-range`: Amount of time to sync, in seconds (3600s default).
- `store-sync-relay-jitter`: Sync range offset to account for relay's message propagation jitter, in seconds (20s default).
Configuration example.
```
./build/wakunode2 \
--store-sync=true \
--store-sync-interval=300 \
--store-sync-range=3600 \
--store-sync-relay-jitter=20
```
## Generate and configure a node key
Nodes generate [new random key pairs](/learn/glossary#node-key) at each boot, leading to different `multiaddrs`. To maintain consistency, you can use a pre-generated private key with the `nodekey` option:
```shell
./build/wakunode2 --nodekey=[NODE PRIVATE KEY]
```
This option takes a [Secp256k1](https://en.bitcoin.it/wiki/Secp256k1) private key (64-char hex string). On Linux, you can use the OpenSSL `rand` command for a pseudo-random 32-byte hex string:
```shell
openssl rand -hex 32
# 286cae9f2990bfc49dafdd3a9e737f56ddba3656e5e427108cef456fb67680e8
```
On Linux, you can create a reusable key file using OpenSSL. To get the 32-byte private key in hex format, use the `ecparam` command and some standard utilities:
```shell
# Generate key file
openssl ecparam -genkey -name secp256k1 -out my_private_key.pem
# Extract 32-byte private key
openssl ec -in my_private_key.pem -outform DER | tail -c +8 | head -c 32| xxd -p -c 32
# read EC key
# writing EC key
# 286cae9f2990bfc49dafdd3a9e737f56ddba3656e5e427108cef456fb67680e8
```
You can use the output `286cae9f2990bfc49dafdd3a9e737f56ddba3656e5e427108cef456fb67680e8` as a `Node Key` for `nwaku`:
```shell
./build/wakunode2 --nodekey=286cae9f2990bfc49dafdd3a9e737f56ddba3656e5e427108cef456fb67680e8
```
## Configure WebSocket transport
WebSocket is the only [transport method](/learn/concepts/transports) browser nodes support using [@waku/sdk](/guides/js-waku/). To enable WebSocket in `nwaku` to serve browser peers, use the following configuration options:
- `websocket-support`: Enables WebSocket (`ws`) on the node (disabled by default).
- `websocket-port` (optional): WebSocket listening port. If you omit this option, it will default to `8000`.
- `websocket-secure-support`: Enables Secure WebSocket (`wss`) on the node (disabled by default).
- `websocket-secure-key-path`: Secure WebSocket key path.
- `websocket-secure-cert-path`: Secure WebSocket Certificate path.
```shell
./build/wakunode2 \
--websocket-support=true \
--websocket-port=[WEBSOCKET LISTENING PORT] \
--websocket-secure-support=true \
--websocket-secure-key-path=[SECURE WEBSOCKET KEY PATH] \
--websocket-secure-cert-path=[SECURE WEBSOCKET CERTIFICATE PATH]
```
For example, consider a `nwaku` node that enabled WebSocket (unencrypted) for local testing on port `8001`:
```shell
./build/wakunode2 \
--websocket-support=true \
--websocket-port=8001
```
Consider a `nwaku` node that enabled Secure WebSocket (encrypted) using its key and certificate (`privkey.pem` and `fullchain.pem`) on port `8002`:
```shell
./build/wakunode2 \
--websocket-secure-support=true \
--websocket-secure-key-path=privkey.pem \
--websocket-secure-cert-path=fullchain.pem \
--websocket-port=8002
```
:::tip
You can use [Let's Encrypt](https://letsencrypt.org/) or [Certbot](https://certbot.eff.org/) to generate a valid certificate for your `nwaku` node:
```shell
sudo certbot certonly -d <your.domain.name>
```
:::
## Configure REST API server
Nwaku provides a [REST API](https://waku-org.github.io/waku-rest-api/) to interact with the node and Waku Network. To enable the REST API, use the following configuration options:
- `rest`: Enables the REST API server on the node (disabled by default).
- `rest-address` (optional): Listening address of the REST API server. If you omit this option, it will default to `127.0.0.1`.
- `rest-port` (optional): Listening port of the REST API server. If you omit this option, it will default to `8645`.
- `rest-relay-cache-capacity` (optional): Capacity of the Relay REST API message cache. If you omit this option, it will default to `30`.
- `rest-admin` (optional): Enables access to REST admin API (disabled by default).
- `rest-private` (optional): Enables access to REST private API (disabled by default).
```shell
./build/wakunode2 \
--rest=true \
--rest-address=[REST SERVER LISTENING ADDRESS] \
--rest-port=[REST SERVER LISTENING PORT] \
--rest-relay-cache-capacity=[MESSAGE CACHE CAPACITY] \
--rest-admin=[true|false] \
--rest-private=[true|false]
```
For example, consider a `nwaku` node that enabled the REST API server on port `9000`:
```shell
./build/wakunode2 \
--rest=true \
--rest-port=9000 \
--rest-address=127.0.0.1
```
Consider a `nwaku` node that enabled the REST `admin` and `private` API with a message cache capacity of `100`:
```shell
./build/wakunode2 \
--rest=true \
--rest-admin=true \
--rest-private=true \
--rest-relay-cache-capacity=100
```
## Configure filter protocol
To enable `nwaku` to serve light clients, enable the [Filter protocol](/learn/concepts/protocols#filter) using `filter` option:
```shell
./build/wakunode2 --filter=true
```
You can configure `nwaku` as a `Filter client` using the `filternode` and `filter-timeout` options. This allows the node to request content filtering of messages from peers.
```shell
./build/wakunode2 \
--filternode=[FILTER PEER MULTIADDR] \
--filter-timeout=[FILTER PEER TIMEOUT]
```
For example, consider a `nwaku` node that requests content filtering of messages from peers with a timeout of `21600` seconds (6 hours):
```shell
./build/wakunode2 \
--filternode=/dns4/node-01.ac-cn-hongkong-c.waku.sandbox.status.im/tcp/30303/p2p/16Uiu2HAmSJvSJphxRdbnigUV5bjRRZFBhTtWFTSyiKaQByCjwmpV \
--filter-timeout=21600
```
:::info
If you omit the `filter-timeout` option, it will default to `14400` seconds (4 hours).
:::
## Configure light push protocol
To enable `nwaku` to serve light clients, enable the [Light Push protocol](/learn/concepts/protocols#light-push) using the `lightpush` option:
```shell
./build/wakunode2 --lightpush=true
```
You can configure `nwaku` as a `Light Push client` using the `lightpushnode` option. This allows the node to request lightpush of published messages from peers.
```shell
./build/wakunode2 --lightpushnode=[LIGHT PUSH PEER MULTIADDR]
```
For example, consider a `nwaku` node that requests lightpush of published messages from peers:
```shell
./build/wakunode2 --lightpushnode=/dns4/node-01.ac-cn-hongkong-c.waku.sandbox.status.im/tcp/30303/p2p/16Uiu2HAmSJvSJphxRdbnigUV5bjRRZFBhTtWFTSyiKaQByCjwmpV
```
## Run nwaku behind a reverse proxy
When using a reverse proxy server for SSL/TLS encryption, you only want to announce the proxy server's IP or domain. Nwaku provides the `ext-multiaddr-only` and `ext-multiaddr` options for specifying published multiaddr:
```shell
./build/wakunode2 \
--ext-multiaddr-only=true \
--ext-multiaddr=[MULTIADDR TO PUBLISH]
```
:::info
The `ext-multiaddr-only` option takes precedence over the `nat` and `dns4-domain-name` options, using the values provided by the `ext-multiaddr` option instead.
:::
docs/run-node/faq.md
+39
View File
@@ -0,0 +1,39 @@
---
title: Nwaku FAQ
hide_table_of_contents: true
sidebar_label: Frequently Asked Questions
---
import { AccordionItem } from '@site/src/components/mdx'
<AccordionItem title="How can I run a Waku node?">
Check out the <a href="/guides/nwaku/run-docker-compose">Run Nwaku with Docker Compose</a> guide to learn the simplest and fastest way to run a node. You can also check the comprehensive <a href="/guides/nwaku/run-node">Run a Nwaku Node</a> guide to explore other options like <a href="/guides/nwaku/run-node#download-the-binary">downloading binaries</a> and <a href="/guides/nwaku/build-source">building from source</a>.
</AccordionItem>
<AccordionItem title="What are the system requirements for running a node?">
We recommend running a nwaku node with at least 2GB of RAM, especially if WSS is enabled. If running just a Relay node, 0.5GB of RAM is sufficient.
</AccordionItem>
<AccordionItem title="How can I interact with my running nwaku node?">
You can interact with a running nwaku node using the <a href="https://waku-org.github.io/waku-rest-api/">REST API interface</a> or the <a href="/guides/js-waku/">JavaScript Waku SDK</a>.
</AccordionItem>
<AccordionItem title="How can I view the logs of a nwaku node running in Docker?">
To check your node logs in Docker, use the command: "docker-compose logs -f nwaku"
</AccordionItem>
<AccordionItem title="What configuration methods are available for nwaku nodes?">
You can configure Nwaku nodes using command line options and flags, environment variables, and TOML configuration files. Check out the <a href="/guides/nwaku/config-methods">Node Configuration Methods</a> guide to understand their usage and priority.
</AccordionItem>
<AccordionItem title="How can I configure my nwaku node before running?">
Check out the <a href="/guides/nwaku/config-options">Node Configuration Options</a> guide for available node configuration options, their default values and descriptions. For examples of common configuration use cases, visit the <a href="/guides/nwaku/configure-nwaku">Node Configuration Examples</a> guide.
</AccordionItem>
<AccordionItem title="What peer discovery mechanisms are available for nwaku nodes, and how can I configure them?">
You can configure peer discovery for nwaku nodes through options like <a href="/learn/concepts/static-peers">Static Peers</a>, <a href="/learn/concepts/dns-discovery">DNS Discovery</a>, <a href="/learn/concepts/discv5">DiscV5</a>, and <a href="/learn/concepts/peer-exchange">Peer Exchange</a>. Check out the <a href="/guides/nwaku/configure-discovery">Configure Peer Discovery</a> guide for setting up your node.
</AccordionItem>
<AccordionItem title="How do I find my nwaku node's addresses for peer discovery?">
The node listening and ENR addresses can be found through the node's logs and <a href="https://waku-org.github.io/waku-rest-api/#get-/debug/v1/info">REST API</a>. Check out the <a href="/guides/nwaku/run-node#find-the-node-addresses">Find the node addresses</a> section to understand how to locate your node addresses.
</AccordionItem>
docs/run-node/find-node-address.md
+60
View File
@@ -0,0 +1,60 @@
---
title: Find Your Node Address
hide_table_of_contents: true
---
:::info
When starting the node, `nwaku` will display all the public listening and discovery addresses at the `INFO` log level.
:::
You can find the addresses of a running node through its logs or by calling the [Get node info](https://waku-org.github.io/waku-rest-api/#get-/debug/v1/info) endpoint of the [REST API](https://waku-org.github.io/waku-rest-api/).
## Listening addresses
Look for the log entry that begins with `Listening on`, for example:
```txt title="Nwaku Log Output"
INF 2023-06-15 16:09:54.448+01:00 Listening on topics="waku node" tid=1623445 file=waku_node.nim:922 full=[/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmQCsH9V81xoqTwGuT3qwkZWbwY1TtTQwpr3DjHU2TSwMn][/ip4/0.0.0.0/tcp/8000/ws/p2p/16Uiu2HAmQCsH9V81xoqTwGuT3qwkZWbwY1TtTQwpr3DjHU2TSwMn]
```
```shell
# Listening TCP transport address
/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmQCsH9V81xoqTwGuT3qwkZWbwY1TtTQwpr3DjHU2TSwMn
# Listening WebSocket address
/ip4/0.0.0.0/tcp/8000/ws/p2p/16Uiu2HAmQCsH9V81xoqTwGuT3qwkZWbwY1TtTQwpr3DjHU2TSwMn
```
## Discoverable ENR addresses
A `nwaku` node can encode its addressing information in an [Ethereum Node Record (ENR)](https://eips.ethereum.org/EIPS/eip-778).
### ENR for DNS discovery
Look for the log entry that begins with `DNS: discoverable ENR`, for example:
```txt title="Nwaku Log Output"
INF 2023-06-15 16:09:54.448+01:00 DNS: discoverable ENR topics="waku node" tid=1623445 file=waku_node.nim:923 enr=enr:-Iu4QBKYj8Ovxwz4fIalxZ_1a8dOCU2WC-1LQrcBCCb4Np93f9-UuSZXn3vagJL1S3k3hwRYfOp3JSbW7_VqwtqMIeMBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQOrmyV59dAzY4ZKrvrj32VOoZbLby8dCKFnXnqhIdQ0NYN0Y3CC6mCFd2FrdTIB
```
```shell
# ENR the node addresses are encoded in
enr:-Iu4QBKYj8Ovxwz4fIalxZ_1a8dOCU2WC-1LQrcBCCb4Np93f9-UuSZXn3vagJL1S3k3hwRYfOp3JSbW7_VqwtqMIeMBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQOrmyV59dAzY4ZKrvrj32VOoZbLby8dCKFnXnqhIdQ0NYN0Y3CC6mCFd2FrdTIB
```
### ENR for Discv5
Look for the log entry that begins with `Discv5: discoverable ENR`, for example:
```txt title="Nwaku Log Output"
INF 2023-06-15 16:09:54.448+01:00 Discv5: discoverable ENR topics="waku node" tid=1623445 file=waku_node.nim:924 enr=enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw
```
```shell
# ENR the node addresses are encoded in
enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw
```
:::tip Congratulations!
You have successfully found the listening and discoverable addresses for your `nwaku` node. Have a look at the [Configure Peer Discovery](/guides/nwaku/configure-discovery) guide to learn how to discover and connect with peers in the network.
:::
docs/run-node/index.md
+141
View File
@@ -0,0 +1,141 @@
---
title: Run a Nwaku Node
hide_table_of_contents: true
---
Nwaku is a lightweight and robust Nim client for running a Waku node, equipped with tools to monitor and maintain a running node. Nwaku is highly configurable, enabling operators to select the [protocols](/learn/concepts/protocols) they want to support based on their needs, motivations, and available resources.
![waku architecture](/img/architecture.png)
This guide provides detailed steps to download, build, configure, and connect a `nwaku` node to the Waku Network. It also includes interacting with the node and finding its addresses.
:::info
We recommend running a `nwaku` node with at least 2GB of RAM, especially if `WSS` is enabled. If running just a `Relay` node, 0.5GB of RAM is sufficient.
:::
## Get the node binary
To run a node, you must have the `nwaku` binary. Nwaku provides multiple options for running a node:
#### Run nwaku in Docker (recommended)
We recommend [using Docker Compose](/guides/nwaku/run-docker-compose) to run a node because it's the simplest and fastest way to configure and run one:
| | Description | Documentation |
| ---------------- | ---------------------------------------- | ----------------------------------------------------------------- |
| Docker Compose | Run a `nwaku` node with Docker Compose | [Run Nwaku with Docker Compose](/guides/nwaku/run-docker-compose) |
| Docker Container | Run a `nwaku` node in a Docker Container | [Run Nwaku in a Docker Container](/guides/nwaku/run-docker) |
#### Download the binary
| | Description | Documentation |
| ------------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Precompiled Binary | Download a precompiled binary of the `nwaku` node | [Download Nwaku Binary](https://github.com/waku-org/nwaku/tags) |
| Nightly Release | Try the latest `nwaku` updates without compiling the binaries | [Download Nightly Release](https://github.com/waku-org/nwaku/releases/tag/nightly) |
#### Build the binary
| | Description | Documentation |
| ----------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------- |
| Build from Source | Build the node from the [nwaku source code](https://github.com/waku-org/nwaku) | [Build Nwaku from Source](/guides/nwaku/build-source) |
:::tip
You can run the `nwaku` binaries and Docker images on cloud service providers like [Google Cloud](https://cloud.google.com/), [Microsoft Azure](https://azure.microsoft.com/), [Amazon Web Services](https://aws.amazon.com/), and [DigitalOcean](https://www.digitalocean.com/).
:::
## Run the node
Once you have gotten the `nwaku` binary, run it using the [default configuration](/guides/nwaku/config-methods#default-configuration-values):
```shell
# Run the Docker Compose
docker-compose up -d
# Run the standalone binary
./build/wakunode2
```
:::tip
To learn how to customise the configuration of a `nwaku` node, have a look at the [Node Configuration Methods](/guides/nwaku/config-methods) and [Node Configuration Examples](/guides/nwaku/configure-nwaku) guides.
:::
## Bootstrap the node
To join the Waku Network, nodes must [bootstrap](/learn/glossary#bootstrapping) for an entry point before discovering more peers. Nwaku provides multiple [peer discovery](/learn/concepts/peer-discovery) mechanisms:
| | Description | Documentation |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Static Peers | Configure the bootstrap nodes that `nwaku` should establish connections upon startup | [Configure Static Peers](/guides/nwaku/configure-discovery#configure-static-peers) |
| DNS Discovery | Enable `nwaku` to bootstrap nodes using the [DNS Discovery](/learn/concepts/dns-discovery) mechanism | [Configure DNS Discovery](/guides/nwaku/configure-discovery#configure-dns-discovery) |
| Discv5 | Enable `nwaku` to discover peers using the [Discv5](/learn/concepts/discv5) mechanism | [Configure Discv5](/guides/nwaku/configure-discovery#configure-discv5) |
| Peer Exchange | Enable [Peer Exchange](/learn/concepts/peer-exchange) protocol for light nodes to request peers from your `nwaku` node | [Configure Peer Exchange](/guides/nwaku/configure-discovery#configure-peer-exchange) |
:::tip
We suggest [configuring WebSocket transport](/guides/nwaku/configure-nwaku#configure-websocket-transport) for your node to enable support and serving of browser peers using [@waku/sdk](/guides/js-waku/).
:::
## Interact with the node
You can interact with a running `nwaku` node through the [REST API](https://waku-org.github.io/waku-rest-api/), such as querying the node information using the [Get node info](https://waku-org.github.io/waku-rest-api/#get-/debug/v1/info) endpoint:
```mdx-code-block
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
```
<Tabs>
<TabItem value="request" label="Request">
```shell
curl --location 'http://127.0.0.1:8645/debug/v1/info' \
--header 'Accept: application/json'
```
</TabItem>
<TabItem value="response" label="Response">
```json
{
"listenAddresses": [
"/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmUbPquFQqje3jiqoB5YoiUbBya59NB4qqEzeiTNGHeA6w"
],
"enrUri": "enr:-Iu4QCQZXZDb_JsYmLoYor0F5E_95HbIywgO_wgx2rIdDbmCJZkTzmlCr0wmMzV47lgik_tVwww5mIng90Ris83TisMBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQPszztG-Ev52ZB7tk0jF8s6Md4KvyY_rhzNZokaaB_ABIN0Y3CC6mCFd2FrdTIB"
}
```
</TabItem>
</Tabs>
:::info
The `listenAddresses` field stores the node's listening addresses, while the `enrUri` field stores the discoverable `ENR` URI for peer discovery.
:::
## Check the node health status
You can check the health status of the node by calling the [Get node health status](https://waku-org.github.io/waku-rest-api/#get-/health) endpoint of the [REST API](https://waku-org.github.io/waku-rest-api/):
<Tabs>
<TabItem value="request" label="Request">
```shell
curl --location 'http://127.0.0.1:8645/health' \
--header 'Accept: text/plain'
```
</TabItem>
<TabItem value="response" label="Response">
```txt
Node is healthy
```
</TabItem>
</Tabs>
:::tip
If you encounter issues running your node or require assistance with anything, please visit the [#node-help channel](https://discord.com/channels/1110799176264056863/1216748184592711691) on our Discord.
:::
:::tip Congratulations!
You have successfully started, configured, and connected a `nwaku` node to the Waku Network. Have a look at the [Node Configuration Examples](/guides/nwaku/configure-nwaku) guide to learn how to configure `nwaku` for different use cases.
:::
docs/run-node/run-docker-compose.md
+128
View File
@@ -0,0 +1,128 @@
---
title: Run Nwaku with Docker Compose
hide_table_of_contents: true
---
[nwaku-compose](https://github.com/waku-org/nwaku-compose) is a ready-to-use Docker Compose setup that configures the following automatically:
- `nwaku` node running [Relay](/learn/concepts/protocols#relay) and [Store](/learn/concepts/protocols#store) protocols with [RLN](/learn/concepts/protocols#rln-relay) enabled.
- Simple frontend to interact with the node and Waku network to send and receive messages.
- [Grafana](https://grafana.com/) metrics dashboard for advanced users and node operators to monitor the node.
## Video tutorial
<div class="video-container">
<iframe class="yt-video" src="https://www.youtube.com/embed/fs0ynLk4z0I" title="How to run a Waku node using Nwaku Compose" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>
:::tip
Check out the [Waku Node Operator Cheatsheet](/Waku-NodeOperator.pdf) to learn how to easily run, monitor, and interact with a node.
:::
## Prerequisites
- [Git](https://git-scm.com/) or [GitHub Desktop](https://desktop.github.com/)
- [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/)
- [Ethereum Sepolia HTTPS Endpoint](https://github.com/waku-org/nwaku/blob/master/docs/tutorial/pre-requisites-of-running-on-chain-spam-protected-chat2.md#3-access-a-node-on-the-sepolia-testnet-using-infura)
- [Wallet with Sepolia Ethereum](https://github.com/waku-org/nwaku/blob/master/docs/tutorial/pre-requisites-of-running-on-chain-spam-protected-chat2.md#2-obtain-sepolia-eth-from-faucet) (~0.6 Sepolia ETH)
- A password to protect your RLN membership
:::info
We recommend running a `nwaku` node with at least 2GB of RAM, especially if `WSS` is enabled. If running just a `Relay` node, 0.5GB of RAM is sufficient.
:::
## Clone the repository
```shell
git clone https://github.com/waku-org/nwaku-compose
cd nwaku-compose
```
## Configure the setup
Docker Compose [reads the .env file](https://docs.docker.com/compose/environment-variables/set-environment-variables/#additional-information-3) from the filesystem. You can use `.env.example` as a template to provide the configuration values. The recommended process for working with `.env` files is to duplicate `.env.example`, rename it as `.env`, and then make the necessary value edits.
```shell
cp .env.example .env
${EDITOR} .env
```
:::caution
Ensure that you do **NOT** include any secrets in the `.env.example` file, as it could accidentally be shared in your Git repository.
:::
## Register for RLN membership
The RLN membership is your access key to The Waku Network. Its registration is done on-chain, allowing your `nwaku` node to send messages decentralised and privately, respecting some rate limits. Other peers won't relay messages that exceed the rate limit.
This command registers your membership and saves it in the `keystore/keystore.json` file. You should have Docker running at this step:
```shell
./register_rln.sh
```
:::tip
If you only want to relay traffic without sending messages to the network, you don't need to register for RLN membership.
:::
## Run the node
Launch all the processes: `nwaku` node, database for storing messages, and Grafana for metrics with the following command. Your RLN membership is loaded into `nwaku` under the hood:
```shell
docker-compose up -d
```
View the logs of the node to confirm that it is running correctly:
```shell
docker-compose logs -f nwaku
```
## Monitor the node
Visit [http://localhost:3000/d/yns_4vFVk/nwaku-monitoring](http://localhost:3000/d/yns_4vFVk/nwaku-monitoring) to view your node metrics in real time.
![nwaku compose dashboard](/img/nwaku-compose-dashboard.png)
:::tip
To access Grafana from outside your machine, remove `127.0.0.1` and open the port. Consider setting up a password for Grafana to ensure security.
:::
## Interact with the node
Your `nwaku` node provides a [REST API](https://waku-org.github.io/waku-rest-api/) on port `8645` for interacting with it:
```shell
# Get nwaku version
curl --location 'http://127.0.0.1:8645/debug/v1/version'
# Get nwaku info
curl --location 'http://127.0.0.1:8645/debug/v1/info'
```
Send a message to a `contentTopic`, which all subscribers will receive. Please note that the `payload` is encoded in `base64`.
```shell
curl --location 'http://127.0.0.1:8645/relay/v1/auto/messages' \
--header 'Content-Type: application/json' \
--data '{
"payload": "'$(echo -n "Hello Waku Network - from Anonymous User" | base64)'",
"contentTopic": "/my-app/2/chatroom-1/proto"
}'
```
Retrieve messages sent to a `contentTopic`. Please note that this query can be made to any `Store` node within the network:
```shell
curl --location 'http://127.0.0.1:8645/store/v1/messages?contentTopics=%2Fmy-app%2F2%2Fchatroom-1%2Fproto&pageSize=50&ascending=true' \
--header 'Accept: application/json'
```
:::tip
If you encounter issues running your node or require assistance with anything, please visit the [#node-help channel](https://discord.com/channels/1110799176264056863/1216748184592711691) on our Discord.
:::
:::tip Congratulations!
You have successfully started a `nwaku` node with `RLN` enabled using Docker Compose. Have a look at the [Node Configuration Examples](/guides/nwaku/configure-nwaku) and [Advanced Configuration](https://github.com/waku-org/nwaku-compose/blob/master/ADVANCED.md) guides to learn how to configure `nwaku` for different use cases.
:::
docs/run-node/run-docker.md
+81
View File
@@ -0,0 +1,81 @@
---
title: Run Nwaku in a Docker Container
hide_table_of_contents: true
---
This guide provides detailed steps to build and run a `nwaku` node in a Docker container. If you prefer a pre-configured setup with a monitoring dashboard, see the [Run Nwaku with Docker Compose](/guides/nwaku/run-docker-compose) guide.
## Prerequisites
Ensure [Docker](https://www.docker.com/) is installed on your system using the appropriate instructions provided in the [Docker documentation](https://docs.docker.com/engine/install/).
:::info
We recommend running a `nwaku` node with at least 2GB of RAM, especially if `WSS` is enabled. If running just a `Relay` node, 0.5GB of RAM is sufficient.
:::
## Get Docker image
The Nwaku Docker images are available on the Docker Hub public registry under the [wakuorg/nwaku](https://hub.docker.com/r/wakuorg/nwaku) repository. Please visit [wakuorg/nwaku/tags](https://hub.docker.com/r/wakuorg/nwaku/tags) for images of specific releases.
## Build Docker image
You can also build the Docker image locally:
```shell
# Clone the repository
git clone --recurse-submodules https://github.com/waku-org/nwaku
cd nwaku
# Build docker image
make docker-image
```
## Run Docker container
Run `nwaku` in a new Docker container:
```shell
docker run [OPTIONS] [IMAGE] [ARG...]
```
- `OPTIONS` are your selected [Docker options](https://docs.docker.com/engine/reference/commandline/run/#options)
- `IMAGE` is the image and tag you pulled from the registry or built locally
- `ARG...` is the list of arguments for your [node configuration options](/guides/nwaku/config-options)
Run `nwaku` using the most typical configuration:
```shell
docker run -i -t -p 60000:60000 -p 9000:9000/udp wakuorg/nwaku:v0.32.0 \
--dns-discovery=true \
--dns-discovery-url=enrtree://AIRVQ5DDA4FFWLRBCHJWUWOO6X6S4ZTZ5B667LQ6AJU6PEYDLRD5O@sandbox.waku.nodes.status.im \
--discv5-discovery=true \
--nat=extip:[YOUR PUBLIC IP] # or, if you are behind a nat: --nat=any
```
To find your public IP, use:
```shell
dig TXT +short o-o.myaddr.l.google.com @ns1.google.com | awk -F'"' '{ print $2}'
```
For more detailed information about all possible configurations, please run
```shell
docker run -t wakuorg/nwaku:v0.32.0 --help
```
:::info
Note that running a node in The Waku Network (--cluster-id=1) requires a special set of configurations and therefore, it is recommended to run in this case with docker compose
:::
:::info
We recommend using explicit port mappings (`-p`) when exposing ports accessible from outside the host (listening and discovery ports, API servers).
:::
:::tip
If you encounter issues running your node or require assistance with anything, please visit the [#node-help channel](https://discord.com/channels/1110799176264056863/1216748184592711691) on our Discord.
:::
:::tip Congratulations!
You have successfully built and started a `nwaku` node in a Docker container. Have a look at the [Node Configuration Examples](/guides/nwaku/configure-nwaku) guide to learn how to configure `nwaku` for different use cases.
:::
docs/run-node/upgrade-instructions.md
+32
View File
@@ -0,0 +1,32 @@
---
title: Upgrade Instructions
hide_table_of_contents: true
sidebar_label: Upgrade Instructions
---
import { AccordionItem } from '@site/src/components/mdx'
If you are currently using Nwaku, running an old version and want to upgrade your node, please follow the below migration instructions for each target release newer than your current running version in ascending order.
For example, if you are interested in the version v0.32.0 and are currently running v0.30.0, follow the instructions for v0.31.0 and then the ones for v0.32.0
## Target Releases
<AccordionItem title="v0.32.0">
The `--protected-topic` CLI config was deprecated and is replaced by the new `--protected-shard` configuration. Instead of configuring `topic:public_key` you will now need to configure `shard:public_key`<br /><br />
For example, if you used to run your node with `--protected-topic="waku/2/rs/3/4:your_public_key"` you will need to replace this configuration for `--protected-shard="4:your_public_key"`
</AccordionItem>
<AccordionItem title="v0.31.0">
Named sharding was deprecated in this version. This means that pubsub topics will only be supported if they comply with the static sharding format: <code>/waku/2/rs/&lt;CLUSTER_ID&gt;/&lt;SHARD_ID&gt;</code><br /><br />
In order to migrate your existing application, you need to:
1. Make sure that your clients are sending messages to pubsub topics in the required format. Check that in your interactions with Nwaku's REST API or when using `js-waku`, the configured pubsub topics follow the static sharding format defined above.
2. When running a node with the `--pubsub-topic` CLI flag, the values provided should comply with the static sharding format.
3. If your application relies on nodes or clients that may not be updated immediately, keep your node on an older version while subscribing to both the current pubsub topic and the new pubsub topic that will comply with the static sharding format. In that case, you can keep backward compatibility for a migration period.
</AccordionItem>