diff --git a/docs/operators/README.md b/docs/operators/README.md index 05535d222..af42d02a8 100644 --- a/docs/operators/README.md +++ b/docs/operators/README.md @@ -1,6 +1,6 @@ # The nwaku guide for operators -*If you're eager to get started, check out our [quickstart guide](./quickstart.md).* +*If you're eager to get started, check out our [quickstart guide](./quickstart.md) for typical configurations or [step-by-step overview](./overview.md) for newcomers.* 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. diff --git a/docs/operators/docker-quickstart.md b/docs/operators/docker-quickstart.md new file mode 100644 index 000000000..b10cf36f7 --- /dev/null +++ b/docs/operators/docker-quickstart.md @@ -0,0 +1,79 @@ +# Quickstart: running nwaku in a Docker container + +This guide explains how to run a nwaku node in a Docker container. + +## Prerequisites + +Make sure you have Docker installed. +Installation instructions for different platforms can be found in the [Docker docs](https://docs.docker.com/engine/install/). + +For example, to use Docker's convenience script for installation: + +```bash +curl -fsSL https://get.docker.com -o get-docker.sh +sudo sh get-docker.sh +``` + +## Step 1: Get Docker image + +Nwaku Docker images are published to the Docker Hub public registry under [`statusteam/nim-waku`](https://hub.docker.com/r/statusteam/nim-waku). +For specific releases the published images are tagged with the release version, e.g. [`statusteam/nim-waku:v0.12.0`](https://hub.docker.com/layers/statusteam/nim-waku/v0.12.0/images/sha256-7b5bcd3f8084218b411e627ab7864ce999d7b49e37ad1d0b1089b18cbf4b79d4?context=explore). +Images are also published for each commit to the `master` branch in the [nwaku repo](https://github.com/status-im/nwaku/commits/master) +and tagged with the corresponding commit hash. +See [`statusteam/nim-waku`](https://hub.docker.com/r/statusteam/nim-waku/tags) on Docker Hub for a full list of available tags. + +To pull the image of your choice, use + +```bash +docker pull statusteam/nim-waku:v0.12.0 # or, whichever tag you prefer in the format statusteam/nim-waku:[tag] +``` + +You can also build the Docker image locally using + +```bash +git clone --recurse-submodules https://github.com/status-im/nwaku +cd nwaku +docker build -t statusteam/nim-waku:latest . +``` + +## Step 2: Run + +To run nwaku in a new Docker container, +use the following command: + +```bash +docker run [OPTIONS] IMAGE [ARG...] +``` + +where `OPTIONS` are your selected Docker options, +`IMAGE` the image and tag you pulled from the registry or built in Step 1 +and `ARG...` the list of nwaku arguments for your [chosen nwaku configuration](./how-to/configure.md). + +For Docker options we recommend explicit port mappings (`-p`) at least +for your exposed libp2p listening ports +and any discovery ports (e.g. the Waku discv5 port) that must be reachable from outside the host. + +As an example, consider the following command to run nwaku in a Docker container with the most typical configuration: + +```bash +docker run -i -t -p 60000:60000 -p 9000:9000/udp statusteam/nim-waku:v0.12.0 \ + --dns-discovery:true \ + --dns-discovery-url:enrtree://AOGECG2SPND25EEFMAJ5WF3KSGJNSGV356DSTL2YVLLZWIV6SAYBM@prod.waku.nodes.status.im \ + --discv5-discovery \ + --nat:extip:[yourpublicip] # or, if you are behind a nat: --nat=any +``` + +This runs nwaku in a new container from the `statusteam/nim-waku:v0.12.0` image, +connects to `wakuv2.prod` as bootstrap fleet and +enables [Waku Discovery v5](https://rfc.vac.dev/spec/33/) for ambient peer discovery, +while mapping the default libp2p listening port (`60000`) +and default discv5 UDP port (`9000`) to the host. + +> **Tip:** The `docker run` command will pull the specified image from Docker Hub if it's not yet available locally, +so it's possible to skip Step 1 and pull the image from your configured registry automatically when running. + +If you've used the `-i` and `-t` Docker options when running the new container, +the `run` command would have allocated an interactive terminal +where you'll see the `stdout` logs from the running nwaku process. +To detach gracefully from the running container, +use `Ctrl-P` followed by `Ctrl-Q`. diff --git a/docs/operators/overview.md b/docs/operators/overview.md new file mode 100644 index 000000000..9038264a7 --- /dev/null +++ b/docs/operators/overview.md @@ -0,0 +1,47 @@ +# Overview: running a nwaku node + +This guide provides on overview for newcomers +on 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) + +To set up a nwaku node on a DigitalOcean droplet, +refer to our [quickstart guide for droplets](./droplet-quickstart.md). +If you prefer running nwaku in Docker container, +see our [Docker guide](./docker-quickstart.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 Docker Hub. +See our [Docker quickstart guide](./docker-quickstart.md) to run nwaku in a Docker container. + +## 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. + +```bash +curl -d '{"jsonrpc":"2.0","method":"get_waku_v2_debug_v1_info","params":[],"id":1}' -H 'Content-Type: application/json' localhost:8546 -s | jq +``` + + +Or using the [Waku v2 HTTP REST API](../api/v2/rest-api.md): + +> **Note:** REST API functionality is in ALPHA and therefore it is disabled by default. To configure a nwaku node with this enabled, use the `--rest:true` CLI option. + + +```bash +curl http://localhost:8546/debug/v1/info -s | jq +``` diff --git a/docs/operators/quickstart.md b/docs/operators/quickstart.md index 118917e84..360b63af9 100644 --- a/docs/operators/quickstart.md +++ b/docs/operators/quickstart.md @@ -1,44 +1,46 @@ # 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) +This guide helps you run a nwaku node with typical configuration. +It connects your node to the `wakuv2.prod` fleet for bootstrapping +and enables discovery v5 for continuous peer discovery. +Only [`relay`](https://rfc.vac.dev/spec/11/) protocol is enabled. +For a more comprehensive overview, +see our [step-by-step guide](./overview.md). -To quickly set up a nwaku node on DigitalOcean, refer to this [guide](./droplet-quickstart.md) +## Option 1: run nwaku binary -## 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. +*Prerequisites are the usual developer tools, +such as a C compiler, Make, Bash and Git.* ```bash -curl -d '{"jsonrpc":"2.0","method":"get_waku_v2_debug_v1_info","params":[],"id":1}' -H 'Content-Type: application/json' localhost:8546 -s | jq +git clone --recurse-submodules https://github.com/status-im/nwaku +cd nwaku +make wakunode2 +./build/wakunode2 \ + --dns-discovery:true \ + --dns-discovery-url:enrtree://AOGECG2SPND25EEFMAJ5WF3KSGJNSGV356DSTL2YVLLZWIV6SAYBM@prod.waku.nodes.status.im \ + --discv5-discovery \ + --nat=extip:[yourpublicip] # or, if you are behind a nat: --nat=any ``` +## Option 2: run nwaku in a Docker container -Or using the [Waku v2 HTTP REST API](../api/v2/rest-api.md): - -> **Note:** REST API functionality is in ALPHA and therefore it is disabled by default. To configure a nwaku node with this enabled, use the `--rest:true` CLI option. - +*Prerequisite is a [Docker installation](./docker-quickstart.md#prerequisites).* ```bash -curl http://localhost:8546/debug/v1/info -s | jq +docker run -i -t -p 60000:60000 -p 9000:9000/udp \ + statusteam/nim-waku:v0.12.0 \ # or, the image:tag of your choice + --dns-discovery:true \ + --dns-discovery-url:enrtree://AOGECG2SPND25EEFMAJ5WF3KSGJNSGV356DSTL2YVLLZWIV6SAYBM@prod.waku.nodes.status.im \ + --discv5-discovery \ + --nat:extip:[yourpublicip] # or, if you are behind a nat: --nat=any +``` + +## Tips and tricks + +To find the public IP of your host, +you can use + +```bash +dig TXT +short o-o.myaddr.l.google.com @ns1.google.com | awk -F'"' '{ print $2}' ```