From 35045d9d97082ca73a31f5980371d0bf1da73cf4 Mon Sep 17 00:00:00 2001 From: Hanno Cornelius <68783915+jm-clius@users.noreply.github.com> Date: Fri, 20 May 2022 14:48:34 +0200 Subject: [PATCH] docs: add operator guide docs (#963) --- docs/operators/README.md | 35 +++ docs/operators/how-to/build.md | 59 +++++ docs/operators/how-to/configure-dns-disc.md | 30 +++ docs/operators/how-to/configure-domain.md | 16 ++ docs/operators/how-to/configure-key.md | 54 +++++ docs/operators/how-to/configure-store.md | 56 +++++ docs/operators/how-to/configure-websocket.md | 35 +++ docs/operators/how-to/configure.md | 11 + docs/operators/how-to/connect.md | 60 +++++ docs/operators/how-to/run.md | 217 +++++++++++++++++++ docs/operators/quickstart.md | 28 +++ 11 files changed, 601 insertions(+) create mode 100644 docs/operators/README.md create mode 100644 docs/operators/how-to/build.md create mode 100644 docs/operators/how-to/configure-dns-disc.md create mode 100644 docs/operators/how-to/configure-domain.md create mode 100644 docs/operators/how-to/configure-key.md create mode 100644 docs/operators/how-to/configure-store.md create mode 100644 docs/operators/how-to/configure-websocket.md create mode 100644 docs/operators/how-to/configure.md create mode 100644 docs/operators/how-to/connect.md create mode 100644 docs/operators/how-to/run.md create mode 100644 docs/operators/quickstart.md diff --git a/docs/operators/README.md b/docs/operators/README.md new file mode 100644 index 000000000..05535d222 --- /dev/null +++ b/docs/operators/README.md @@ -0,0 +1,35 @@ +# The nwaku guide for operators + +*If you're eager to get started, check out our [quickstart guide](./quickstart.md).* + +Nwaku is a client implementation in Nim of the [Waku v2 family of protocols](https://rfc.vac.dev/spec/10/) for peer-to-peer communication. +The protocols are designed to be secure, privacy-preserving, censorship-resistant and able to run in resource restricted environments. +Moreover, we've taken a modular approach so that node operators can choose which protocols they want to support +based on their own motivations and availability of resources. +We call this concept ["adaptive nodes"](https://rfc.vac.dev/spec/30/), +implying that a Waku v2 network can consist of heterogeneous nodes contributing at different levels to the network. + +Nwaku (formerly `nim-waku`) aims to be a lightweight and robust Waku v2 client. +It serves as the reference implementation for researchers, +who extend the client in parallel to spec development. +As such, it is first in line to support innovative and new Waku v2 protocols, +but configurable enough to serve the adaptive needs of a various operators. +We are also developing a set of operator-focused tools to monitor and maintain a running nwaku node. + +This guide provides step-by-step tutorials covering how to build and configure your own nwaku node, +connect to an existing Waku v2 network +and use existing tools for monitoring and maintaining a running node. + +## Helpful resources + + + +## Getting in touch or reporting an issue + +For an inquiry, or if you would like to propose new features, feel free to [open a general issue](https://github.com/status-im/nwaku/issues/new/). + +For bug reports, please [tag your issue with the `bug` label](https://github.com/status-im/nwaku/issues/new/). + +If you believe the reported issue requires critical attention, please [use the `critical` label](https://github.com/status-im/nwaku/issues/new?labels=critical,bug) to assist with triaging. + +To get help, or participate in the conversation, join the [Vac Discord](https://discord.gg/KNj3ctuZvZ) server. \ No newline at end of file diff --git a/docs/operators/how-to/build.md b/docs/operators/how-to/build.md new file mode 100644 index 000000000..473547c9d --- /dev/null +++ b/docs/operators/how-to/build.md @@ -0,0 +1,59 @@ +# Build nwaku + +Nwaku can be built on Linux and macOS. +Windows support is experimental. + +## Installing dependencies + +Cloning and building nwaku requires the usual developer tools, +such as a C compiler, Make, Bash and Git. + +### Linux + +On common Linux distributions the dependencies can be installed with + +```sh +# Debian and Ubuntu +sudo apt-get install build-essential git + +# Fedora +dnf install @development-tools + +# Archlinux, using an AUR manager +yourAURmanager -S base-devel +``` + +### macOS + +Assuming you use [Homebrew](https://brew.sh/) to manage packages + +```sh +brew install cmake +``` + +## Building nwaku + +### 1. Clone the nwaku repository + +```sh +git clone https://github.com/status-im/nwaku +cd nwaku +``` + +### 2. Make the `wakunode2` target + +```sh +# The first `make` invocation will update all Git submodules. +# You'll run `make update` after each `git pull`, in the future, to keep those submodules up to date. +make wakunode2 +``` + +This will create a `wakunode2` binary in the `./build/` directory. + +> **Note:** Building `wakunode2` requires 2GB of RAM. +The build will fail on systems not fulfilling this requirement. + +> Setting up a `wakunode2` on the smallest [digital ocean](https://docs.digitalocean.com/products/droplets/how-to/) droplet, you can either +> * compile on a stronger droplet featuring the same CPU architecture and downgrade after compiling, or +> * activate swap on the smallest droplet, or +> * use Docker. diff --git a/docs/operators/how-to/configure-dns-disc.md b/docs/operators/how-to/configure-dns-disc.md new file mode 100644 index 000000000..4cff1563a --- /dev/null +++ b/docs/operators/how-to/configure-dns-disc.md @@ -0,0 +1,30 @@ +# Use DNS discovery to connect to existing nodes + +> **Note:** This page describes using DNS to discover other peers +and is unrelated to the [domain name configuration](./configure-domain.md) for your nwaku node. + +A node can discover other nodes to connect to using [DNS-based discovery](../../tutorial/dns-disc.md). +The following command line options are available: + +``` +--dns-discovery Enable DNS Discovery +--dns-discovery-url URL for DNS node list in format 'enrtree://@' +--dns-discovery-name-server DNS name server IPs to query. Argument may be repeated. +``` + +- `--dns-discovery` is used to enable DNS discovery on the node. +Waku DNS discovery is disabled by default. +- `--dns-discovery-url` is mandatory if DNS discovery is enabled. +It contains the URL for the node list. +The URL must be in the format `enrtree://@` where `` is the fully qualified domain name and `` is the base32 encoding of the compressed 32-byte public key that signed the list at that location. +- `--dns-discovery-name-server` is optional and contains the IP(s) of the DNS name servers to query. +If left unspecified, the Cloudflare servers `1.1.1.1` and `1.0.0.1` will be used by default. + +A node will attempt connection to all discovered nodes. + +This can be used, for example, to connect to one of the existing fleets. +Current URLs for the published fleet lists: +- production fleet: `enrtree://ANTL4SLG2COUILKAPE7EF2BYNL2SHSHVCHLRD5J7ZJLN5R3PRJD2Y@prod.waku.nodes.status.im` +- test fleet: `enrtree://AOFTICU2XWDULNLZGRMQS4RIZPAZEHYMV4FYHAPW563HNRAOERP7C@test.waku.nodes.status.im` + +See the [separate tutorial](../../tutorial/dns-disc.md) for a complete guide to DNS discovery. \ No newline at end of file diff --git a/docs/operators/how-to/configure-domain.md b/docs/operators/how-to/configure-domain.md new file mode 100644 index 000000000..dee1f8bce --- /dev/null +++ b/docs/operators/how-to/configure-domain.md @@ -0,0 +1,16 @@ +# Configure a domain name + +> **Note:** This page describes configuring a domain name that resolves to your node's IP +and is unrelated to [DNS discovery](./configure-dns-disc.md), +by which a node may discover the listening addresses of other peers using DNS. + +It is possible to configure an IPv4 DNS domain name that resolves to the node's public IPv4 address. + +```shell +wakunode2 --dns4-domain-name=mynode.example.com +``` + +This allows for the node's publically announced `multiaddrs` to use the `/dns4` scheme. +In addition, nodes with domain name and [secure websocket configured](./configure-websocket.md), +will generate a discoverable ENR containing the `/wss` multiaddr with `/dns4` domain name. +This is necessary to verify domain certificates when connecting to this node over secure websocket. \ No newline at end of file diff --git a/docs/operators/how-to/configure-key.md b/docs/operators/how-to/configure-key.md new file mode 100644 index 000000000..8da84f90c --- /dev/null +++ b/docs/operators/how-to/configure-key.md @@ -0,0 +1,54 @@ +# Generate and configure a node key + +By default a node will generate a new, random key pair each time it boots, +resulting in a different public libp2p `multiaddrs` after each restart. + +To maintain consistent addressing across restarts, +it is possible to configure the node with a previously generated private key using the `--nodekey` option. + +```shell +wakunode2 --nodekey=<64_char_hex> +``` + +This option takes a [Secp256k1](https://en.bitcoin.it/wiki/Secp256k1) private key in 64 char hexstring format. + +To generate such a key on Linux systems, +use the openssl `rand` command to generate a pseudo-random 32 byte hexstring. + +```sh +openssl rand -hex 32 +``` + +Example output: + +```sh +$ openssl rand -hex 32 +6a29e767c96a2a380bb66b9a6ffcd6eb54049e14d796a1d866307b8beb7aee58 +``` + +where the key `6a29e767c96a2a380bb66b9a6ffcd6eb54049e14d796a1d866307b8beb7aee58` can be used as `nodekey`. + +To create a reusable keyfile on Linux using `openssl`, +use the `ecparam` command coupled with some standard utilities +whenever you want to extract the 32 byte private key in hex format. + +```sh +# Generate keyfile +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 +``` + +Example output: + +```sh +read EC key +writing EC key +0c687bb8a7984c770b566eae08520c67f53d302f24b8d4e5e47cc479a1e1ce23 +``` + +where the key `0c687bb8a7984c770b566eae08520c67f53d302f24b8d4e5e47cc479a1e1ce23` can be used as `nodekey`. + +```sh +wakunode2 --nodekey=0c687bb8a7984c770b566eae08520c67f53d302f24b8d4e5e47cc479a1e1ce23 +``` diff --git a/docs/operators/how-to/configure-store.md b/docs/operators/how-to/configure-store.md new file mode 100644 index 000000000..8418d2100 --- /dev/null +++ b/docs/operators/how-to/configure-store.md @@ -0,0 +1,56 @@ +# Configure store protocol + +Store protocol is enabled by default on a nwaku node. +This is controlled by the `--store` CLI option. + +```sh +# Disable store protocol on startup +./build/wakunode2 --store:false +``` + +Note that this only mounts the `store` protocol, +meaning your node will indicate to other peers that it supports `store`. +It does not yet allow your node to either retrieve historical messages as a client +or store and serve historical messages itself. + +## Configuring a store client + +Ensure that `store` is enabled (this is `true` by default) and provide at least one store service node address with the `--storenode` CLI option. + +See the following example, using the peer at `/dns4/node-01.ac-cn-hongkong-c.wakuv2.test.statusim.net/tcp/30303/p2p/16Uiu2HAkvWiyFsgRhuJEb9JfjYxEkoHLgnUQmr1N5mKWnYjxYRVm` as store service node. + +```sh +./build/wakunode2 \ + --store:true \ + --storenode:/dns4/node-01.ac-cn-hongkong-c.wakuv2.test.statusim.net/tcp/30303/p2p/16Uiu2HAkvWiyFsgRhuJEb9JfjYxEkoHLgnUQmr1N5mKWnYjxYRVm +``` + +Your node can now send queries to retrieve historical messages +from the configured store service node. +One way to trigger such queries is asking your node for historical messages using the [Waku v2 JSON RPC API](https://rfc.vac.dev/spec/16/). + +## Configuring a store service node + +To store historical messages on your node which can be served to store clients the `--persist-messages` CLI option must be enabled. +By default a node would store up to the latest `50 000` messages. +This is configurable using the `--store-capacity` option. +A node that has a `--db-path` set will backup historical messages to a local database at the DB path +and persist these messages even after a restart. + +```sh +./build/wakunode2 \ + --store:true \ + --persist-messages:true \ + --db-path:/mnt/nwaku/data/db1/ \ + --store-capacity:150000 +``` + +### How much resources should I allocate? + +Currently store service nodes use an in-memory key-value store as primary storage with the disk-based database only used for backups. +Most Waku messages average a size of 1KB - 2KB, +implying a minimum memory requirement of at least ~250MB +for a medium capacity store of 100k messages. +Note, however, that the allowable maximum size for Waku messages is up to 1MB. +We are working on a disk-only and hybrid store to lower the memory requirement. +It will soon also be possible to configure store capacity on maximum store size or number of days' history to keep. \ No newline at end of file diff --git a/docs/operators/how-to/configure-websocket.md b/docs/operators/how-to/configure-websocket.md new file mode 100644 index 000000000..4f1c461c6 --- /dev/null +++ b/docs/operators/how-to/configure-websocket.md @@ -0,0 +1,35 @@ +# Configure websocket transport + +Websocket is currently the only Waku transport supported by browser nodes using [js-waku](https://github.com/status-im/js-waku). +Setting up websocket enables your node to directly serve browser peers. + +A valid certificate is necessary to serve browser nodes, +you can use [`letsencrypt`](https://letsencrypt.org/): + +```shell +sudo letsencrypt -d +``` + +You will need the `privkey.pem` and `fullchain.pem` files. + +To enable secure websocket, pass the generated files to `wakunode2`: +Note, the default port for websocket is 8000. + +```shell +wakunode2 --websocket-secure-support=true --websocket-secure-key-path="/privkey.pem" --websocket-secure-cert-path="/fullchain.pem" +``` + +## Self-signed certificates + +Self-signed certificates are not recommended for production setups because: + +- Browsers do not accept self-signed certificates +- Browsers do not display an error when rejecting a certificate for websocket. + +However, they can be used for local testing purposes: + +```shell +mkdir -p ./ssl_dir/ +openssl req -x509 -newkey rsa:4096 -keyout ./ssl_dir/key.pem -out ./ssl_dir/cert.pem -sha256 -nodes +wakunode2 --websocket-secure-support=true --websocket-secure-key-path="./ssl_dir/key.pem" --websocket-secure-cert-path="./ssl_dir/cert.pem" +``` \ No newline at end of file diff --git a/docs/operators/how-to/configure.md b/docs/operators/how-to/configure.md new file mode 100644 index 000000000..6ca598f08 --- /dev/null +++ b/docs/operators/how-to/configure.md @@ -0,0 +1,11 @@ +# Configure a nwaku node + +Nwaku can be configured to serve the adaptive needs of different operators. +This page serves as an index of tutorials explaining how to configure your nwaku node for different use cases. + +1. [Connect to other peers](./connect.md) +1. [Configure a domain name](./configure-domain.md) +1. [Use DNS discovery to connect to existing nodes](./configure-dns-disc.md) +1. [Configure store protocol](./configure-store.md) +1. [Generate and configure a node key](./configure-key.md) +1. [Configure websocket transport](./configure-websocket.md) \ No newline at end of file diff --git a/docs/operators/how-to/connect.md b/docs/operators/how-to/connect.md new file mode 100644 index 000000000..a75da1157 --- /dev/null +++ b/docs/operators/how-to/connect.md @@ -0,0 +1,60 @@ +# Connect to other peers + +*Note that this tutorial describes how to **configure** a node to connect to other peers before runnning the node. +For connecting a running node to existing peers, +see the [JSON-RPC API](https://rfc.vac.dev/spec/16/).* + +There are currently three options. +Note that each of these options can be used in combination with any of the other two. +In other words, it is possible to configure a node to connect +to a static list of peers and +to discover such peer lists using DNS discovery and +discover and connect to random peers using discovery v5 with a bootstrap node. + +## Option 1: Configure peers statically + +Static peers can be provided to a nwaku node on startup using the `--staticnode` CLI parameter. +The `--staticnode` option can be repeated for each peer you want to connect to on startup. + +```sh +./build/wakunode2 \ + --staticnode: \ + --staticnode: +``` + +As an example, consider a nwaku node that connects to two known peers +on the same local host (with IP `0.0.0.0`) +with TCP ports `60002` and `60003`, +and peer IDs `16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H` and `16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ` respectively. + +```sh +./build/wakunode2 \ + --staticnode:/ip4/0.0.0.0/tcp/60002/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H \ + --staticnode:/ip4/0.0.0.0/tcp/60003/p2p/16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ +``` + +## Option 2: Discover peers using DNS discovery + +A node can discover other nodes to connect to using DNS-based discovery. +For a quickstart guide on how to configure DNS discovery, +see [this tutorial](./configure-dns-disc.md). +There is also a [more comprehensive tutorial](../../tutorial/dns-disc.md) for advanced users. + +## Option 3: Discover peers using Waku Discovery v5 + + + +Enable Discovery v5 using the `--discv5-discovery` option. + +It is possible to configure bootstrap entries for the Discovery v5 routing table +using the `--discv5-bootstrap-node` option repeatedly. + +```sh +./build/wakunode2 \ + --discv5-discovery:true \ + --discv5-bootstrap-node: \ + --discv5-bootstrap-node: +``` + +Note that if Discovery v5 is enabled and used in conjunction with DNS-based discovery, +the nwaku node will attempt to bootstrap the Discovery v5 routing table with ENRs extracted from the peers discovered via DNS. diff --git a/docs/operators/how-to/run.md b/docs/operators/how-to/run.md new file mode 100644 index 000000000..880df1f47 --- /dev/null +++ b/docs/operators/how-to/run.md @@ -0,0 +1,217 @@ +# Running nwaku + +Nwaku binaries can be [built](./build.md) and run on Linux and macOS. +Windows support is experimental. + +```sh +# Run with default configuration +./build/wakunode2 + +# See available command line options +./build/wakunode2 --help +``` + +## Default configuration + +By default a nwaku node will: +- generate a new private key and libp2p identities after every restart. +See [this tutorial](./configure-key.md) if you want to generate and configure a persistent private key. +- listen for incoming libp2p connections on the default TCP port (`60000`) +- enable `relay` protocol +- subscribe to the default pubsub topic, namely `/waku/2/default-waku/proto` +- enable `store` protocol, but only as a client. +This implies that the nwaku node will not persist any historical messages itself, +but can query `store` service peers who do so. +To configure `store` as a service node, +see [this tutorial](./configure-store.md). + +> **Note:** The `filter` and `lightpush` protocols are _not_ enabled by default. +Consult the [configuration guide](./configure.md) on how to configure your nwaku node to run these protocols. + +Some typical non-default configurations are explained below. +For more advanced configuration, see the [configuration guide](./configure.md). +Different ways to connect to other nodes are expanded upon in our [connection guide](./connect.md). + +## Finding your listening address(es) + +Find the log entry beginning with `Listening on`. +It should be printed at INFO level when you start your node +and contains a list of all publically announced listening addresses for the nwaku node. + +For example + +``` +INF 2022-05-11 16:42:30.591+02:00 Listening on topics="wakunode" tid=6661 file=wakunode2.nim:941 full=[/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H][/ip4/0.0.0.0/tcp/8000/ws/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H] +``` + +indicates that your node is listening on the TCP transport address + +``` +/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H +``` + +and websocket address + +``` +/ip4/0.0.0.0/tcp/8000/ws/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H +``` + +You can also query a running node for its listening addresses +using a [`get_waku_v2_debug_v1_info` JSON-RPC API](https://rfc.vac.dev/spec/16/#get_waku_v2_debug_v1_info) call. + +For example + +```sh +curl -d '{"jsonrpc":"2.0","id":"id","method":"get_waku_v2_debug_v1_info", "params":[]}' --header "Content-Type: application/json" http://localhost:8545 +``` + +returns a response similar to + +```json +{ + "jsonrpc": "2.0", + "id": "id", + "result": { + "listenAddresses": [ + "/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmLU5Nwng9dWFZwM2DgJ5QGcUuDnefJyHJiXUCVaprhgL4" + ], + "enrUri": "enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw" + } +} +``` + +## Finding your discoverable ENR address(es) + +A nwaku node can encode its addressing information in an [Ethereum Node Record (ENR)](https://eips.ethereum.org/EIPS/eip-778) according to [`31/WAKU2-ENR`](https://rfc.vac.dev/spec/31/). +These ENR are most often used for discovery purposes. + +### ENR for DNS discovery + +Find the log entry beginning with `DNS: discoverable ENR`. +It should be printed at INFO level when you start your node with [DNS discovery enabled](./configure-dns-disc.md) +and contains an ENR that can be added to node lists discoverable via DNS. + +For example + +``` +INF 2022-05-20 11:52:48.772+02:00 DNS: discoverable ENR topics="wakunode" tid=5182 file=wakunode2.nim:941 enr=enr:-Iu4QBZs5huNuEAjI9WA0HOAjzpmp39vKJAtYRG3HXH86-i3HGcxMgupIkyDBmBq9qJ2wFfgMiW8AUzUxTFMAzfJM5MBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQN0EcrUbHrL_O_kNXDlBvcO1I4yZUdNk7VZI5GsXaWgvYN0Y3CC6mCFd2FrdTID +``` + +indicates that your node addresses are encoded in the ENR + +``` +enr=enr:-Iu4QBZs5huNuEAjI9WA0HOAjzpmp39vKJAtYRG3HXH86-i3HGcxMgupIkyDBmBq9qJ2wFfgMiW8AUzUxTFMAzfJM5MBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQN0EcrUbHrL_O_kNXDlBvcO1I4yZUdNk7VZI5GsXaWgvYN0Y3CC6mCFd2FrdTID +``` + +### ENR for Discovery v5 + +Find the log entry beginning with `Discv5: discoverable ENR`. +It should be printed at INFO level when you start your node with [Waku Discovery v5 enabled](https://rfc.vac.dev/spec/33/) +and contains the ENR that will be discoverable by other peers. + +For example + +``` +INF 2022-05-20 11:52:48.775+02:00 Discv5: discoverable ENR topics="wakunode" tid=5182 file=wakunode2.nim:905 enr=enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw +``` + +indicates that your node addresses are encoded in the ENR + +``` +enr=enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw +``` + +## Typical configuration (relay node) + +The typical configuration for a nwaku node is to run the `relay` protocol, +subscribed to the default pubsub topic `/waku/2/default-waku/proto`, +and connecting to one or more existing peers. +We assume below that running nodes also participate in Discovery v5 +to continually discover and connect to random peers for a more robust mesh. + +### Connecting to known peer(s) + +A typical run configuration for a nwaku node is to connect to existing peers with known listening addresses using the `--staticnode` option. +The `--staticnode` option can be repeated for each peer you want to connect to on startup. +This is also useful if you want to run several nwaku instances locally +and therefore know the listening addresses of all peers. + +As an example, consider a nwaku node that connects to two known peers +on the same local host (with IP `0.0.0.0`) +with TCP ports `60002` and `60003`, +and peer IDs `16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H` and `16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ` respectively. +The Discovery v5 routing table can similarly be bootstrapped using a static ENR. +We include an example below. + +```sh +./build/wakunode2 \ + --ports-shift:1 \ + --staticnode:/ip4/0.0.0.0/tcp/60002/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H \ + --staticnode:/ip4/0.0.0.0/tcp/60003/p2p/16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ \ + --discv5-discovery:true \ + --discv5-bootstrap-node:enr:-JK4QM2ylZVUhVPqXrqhWWi38V46bF2XZXPSHh_D7f2PmUHbIw-4DidCBnBnm-IbxtjXOFbdMMgpHUv4dYVH6TgnkucBgmlkgnY0gmowhCJ6_HaJc2VjcDI1NmsxoQM06FsT6EJ57mzR_wiLu2Bz1dER2nUFSCpaFzCccQtnhYN0Y3CCdl-DdWRwgiMohXdha3UyDw +``` + +> **Tip:** `--ports-shift` shifts all configured ports forward by the configured amount. +This is another useful option when running several nwaku instances on a single machine +and would like to avoid port clashes without manually configuring each port. + +### Connecting to the `wakuv2.prod` network + +*See [this explainer](https://github.com/status-im/nwaku/blob/6ebe26ad0587d56a87a879d89b7328f67f048911/docs/contributors/waku-fleets.md) on the different networks and Waku v2 fleets.* + +You can use DNS discovery to bootstrap connection to the existing production network. +Discovery v5 will attempt to extract the ENRs of the discovered nodes as bootstrap entries to the routing table. + +```sh +./build/wakunode2 \ + --ports-shift:1 \ + --dns-discovery:true \ + --dns-discovery-url:enrtree://ANTL4SLG2COUILKAPE7EF2BYNL2SHSHVCHLRD5J7ZJLN5R3PRJD2Y@prod.waku.nodes.status.im \ + --discv5-discovery:true +``` + +### Connecting to the `wakuv2.test` network + +*See [this explainer](https://github.com/status-im/nwaku/blob/6ebe26ad0587d56a87a879d89b7328f67f048911/docs/contributors/waku-fleets.md) on the different networks and Waku v2 fleets.* + +You can use DNS discovery to bootstrap connection to the existing test network. +Discovery v5 will attempt to extract the ENRs of the discovered nodes as bootstrap entries to the routing table. + +```sh +./build/wakunode2 \ + --ports-shift:1 \ + --dns-discovery:true \ + --dns-discovery-url:enrtree://AOFTICU2XWDULNLZGRMQS4RIZPAZEHYMV4FYHAPW563HNRAOERP7C@test.waku.nodes.status.im \ + --discv5-discovery:true +``` + +## Typical configuration (relay and store service node) + +Often nwaku nodes choose to also store historical messages +from where it can be queried by other peers who may have been temporarily offline. +For example, a typical configuration for such a store service node, +[connecting to the `wakuv2.test`](#connecting-to-the-wakuv2test-fleet) fleet on startup, +appears below. + +```sh +./build/wakunode2 \ + --ports-shift:1 \ + --store:true \ + --persist-messages:true \ + --db-path:/mnt/nwaku/data/db1/ \ + --store-capacity:150000 \ + --dns-discovery:true \ + --dns-discovery-url:enrtree://AOFTICU2XWDULNLZGRMQS4RIZPAZEHYMV4FYHAPW563HNRAOERP7C@test.waku.nodes.status.im \ + --discv5-discovery:true +``` + +See our [store configuration tutorial](./configure-store.md) for more. + +## Interact with a running nwaku node + +A running nwaku node can be interacted with using the [Waku v2 JSON RPC API](https://rfc.vac.dev/spec/16/). + +> **Note:** Private and Admin API functionality are disabled by default. +To configure a nwaku node with these enabled, +use the `--rpc-admin:true` and `--rpc-private:true` CLI options. \ No newline at end of file diff --git a/docs/operators/quickstart.md b/docs/operators/quickstart.md new file mode 100644 index 000000000..501abd282 --- /dev/null +++ b/docs/operators/quickstart.md @@ -0,0 +1,28 @@ +# Quickstart: running a nwaku node + +This guide explains how to build and run a nwaku node +for the most common use cases. +For a more advanced configuration see our [configuration guides](./how-to/configure.md) + +## 1. Build + +[Build the nwaku node](./how-to/build.md) +or download a precompiled binary from our [releases page](https://github.com/status-im/nwaku/releases). +Docker images are published to [statusteam/nim-waku](https://hub.docker.com/r/statusteam/nim-waku/tags) on DockerHub. + + + +## 2. Run + +[Run the nwaku node](./how-to/run.md) using a default or common configuration +or [configure](./how-to/configure.md) the node for more advanced use cases. + +[Connect](./how-to/connect.md) the nwaku node to other peers to start communicating. + +## 3. Interact + +A running nwaku node can be interacted with using the [Waku v2 JSON RPC API](https://rfc.vac.dev/spec/16/). + +> **Note:** Private and Admin API functionality are disabled by default. +To configure a nwaku node with these enabled, +use the `--rpc-admin:true` and `--rpc-private:true` CLI options.