waku-org
/
nwaku
mirror of https://github.com/waku-org/nwaku.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: add docker and quickstart guides (#1289)

This commit is contained in:
Hanno Cornelius 2022-10-24 11:31:33 +03:00 committed by GitHub
parent 9b59052bcd
commit 8f5363ea8f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 161 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/operators/README.md
View File

@ -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.

79
docs/operators/docker-quickstart.md Normal file
View File

@ -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`.

47
docs/operators/overview.md Normal file
View File

@ -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
```

66
docs/operators/quickstart.md
View File

@ -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.
<!-- TODO: more advanced explanation on finding and using docker images -->
## 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}'
```