Skip to content

Commit 08ad0a4

Browse files
ndrppndrpp
committed
feat(#1317): update quickstart script & networking docs
1 parent 6a3e228 commit 08ad0a4

2 files changed

Lines changed: 108 additions & 64 deletions

File tree

‎docs/networking.md‎

Lines changed: 100 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,107 +1,147 @@
11
# Ocean Node Networking
22

3-
## Networking in cloud environments or DMZ
3+
For other nodes (and browsers) to reach your node, it must be reachable at a stable, publicly routable address. Work through the options below in order — stop at the first one that applies to your setup.
44

5-
In order for your node to join the network, the others nodes needs to be able to connect to it.
6-
All options can be controlled using [environment
7-
variables](env.md#p2p)
5+
## Option 1: Static Public IP
86

9-
To quickly start your node, you can keep all of the default values,but most likely it will hurt performance. If you want a customised approach, here are the full steps:
7+
If your machine has a static public IP directly assigned to it (common in VPS/cloud environments), set `P2P_ANNOUNCE_ADDRESSES` to announce that address. The quickstart script does this automatically when you provide your IP or domain name.
108

11-
- decide what IP version to use (IPV4 or/and IPv6). You should use both if available.
12-
- decide if you want to filter private ips (if you run multiple nodes in a LAN or cloud environment, leave them on)
13-
- if you already have an external ip configured on your machine, you are good to go.
14-
- if you have a private ip, but an UPNP gateway, you should be fine as well.
15-
- if you have a private ip and you can forward external ports from your gateway, use P2P_ANNOUNCE_ADDRESSES and let other nodes know your external IP/port.
16-
- if you cannot forward ports on your gateway, the only choice is to use a circuit relay server (then all traffic will go through that node and it will proxy)
9+
Example for a node with public IP `1.2.3.4`, using ports 9000 (TCP) and 9001 (WebSocket/TLS):
10+
11+
```bash
12+
P2P_ANNOUNCE_ADDRESSES='[
13+
"/ip4/1.2.3.4/tcp/9000",
14+
"/ip4/1.2.3.4/tcp/9001/ws",
15+
"/ip4/1.2.3.4/tcp/9001/tls/ws",
16+
"/ip4/1.2.3.4/tcp/9001/tls/wss"
17+
]'
18+
```
19+
20+
The `/tls/ws` and `/tls/wss` entries enable [AutoTLS](#tls-and-sni-server-name-indication) for node-to-browser communication. AutoTLS handles certificate provisioning automatically — no DNS setup required on your part.
21+
22+
## Option 2: Dynamic DNS (no static IP)
23+
24+
If your public IP changes (residential ISP, dynamic VPS), use a Dynamic DNS (DDNS) service to get a stable hostname that always resolves to your current IP.
25+
26+
Popular free DDNS providers: [DuckDNS](https://www.duckdns.org/), [No-IP](https://www.noip.com/), [Dynu](https://www.dynu.com/).
27+
28+
Once you have a hostname (e.g. `mynode.duckdns.org`), set up the DDNS client on your machine to keep it updated, then use the hostname in your announce addresses:
29+
30+
```bash
31+
P2P_ANNOUNCE_ADDRESSES='[
32+
"/dns4/mynode.duckdns.org/tcp/9000",
33+
"/dns4/mynode.duckdns.org/tcp/9001/ws",
34+
"/dns4/mynode.duckdns.org/tcp/9001/tls/ws",
35+
"/dns4/mynode.duckdns.org/tcp/9001/tls/wss"
36+
]'
37+
```
38+
39+
## Option 3: Port Forwarding
40+
41+
If you are behind a NAT router (home network), you need to forward the P2P ports from your router to the machine running the node.
42+
43+
1. Find the local IP of your machine (e.g. `192.168.1.50`).
44+
2. Log in to your router admin panel and add port forwarding rules:
45+
- External TCP port `9000` → `192.168.1.50:9000`
46+
- External TCP port `9001` → `192.168.1.50:9001`
47+
3. Find your public IP (e.g. via `curl ifconfig.me`) or set up a DDNS hostname (see Option 2).
48+
4. Set `P2P_ANNOUNCE_ADDRESSES` to your public IP or DDNS hostname as shown above.
49+
50+
If your router supports UPnP, the node can attempt to configure port forwarding automatically. Enable it with:
51+
52+
```bash
53+
P2P_ENABLE_UPNP=true
54+
```
55+
56+
UPnP is not reliable on all routers and should not be relied on as the sole method.
57+
58+
## Option 4: Circuit Relay (fallback)
59+
60+
If none of the above options are available (strict NAT, no port forwarding, no public IP), use a circuit relay. A relay node proxies traffic between peers, allowing your node to participate in the network without being directly reachable.
61+
62+
Enable the circuit relay client:
63+
64+
```bash
65+
P2P_ENABLE_CIRCUIT_RELAY_CLIENT=true
66+
P2P_CIRCUIT_RELAYS=1
67+
```
68+
69+
Note: circuit relay increases latency and bandwidth usage on the relay node. It should be a last resort — a node running only via relay is a burden on the network and will have degraded performance.
70+
71+
Do not enable `P2P_ENABLE_CIRCUIT_RELAY_SERVER` on edge nodes; that setting is for well-connected nodes that want to help others.
72+
73+
---
1774

1875
## TLS and SNI (Server Name Indication)
1976

20-
AutoTLS is used to provision TLS certificates for your node in order to allow P2P node-to-browser communication.
21-
To enable SNI with Ocean Node's autoTLS feature, include `/tls/ws` or `/tls/wss` addresses in `P2P_ANNOUNCE_ADDRESSES`:
77+
AutoTLS provisions TLS certificates for your node automatically, enabling P2P node-to-browser communication. It is always active internally — no DNS or certificate setup required on your part. For it to work, you must include `/tls/ws` or `/tls/wss` entries in `P2P_ANNOUNCE_ADDRESSES`, which the quickstart script does automatically.
2278

23-
Add to .env file
79+
Example `.env` / docker-compose entry:
2480

2581
```bash
26-
export P2P_ANNOUNCE_ADDRESSES='[
27-
"/ip4/<your-ip-addr>/tcp/9000",
28-
"/ip4/<your-ip-addr>/tcp/9001/tls/ws",
29-
"/ip4/<your-ip-addr>/tcp/9005/tls/wss",
82+
P2P_ANNOUNCE_ADDRESSES='[
83+
"/ip4/<your-ip>/tcp/9000",
84+
"/ip4/<your-ip>/tcp/9001/ws",
85+
"/ip4/<your-ip>/tcp/9001/tls/ws",
86+
"/ip4/<your-ip>/tcp/9001/tls/wss"
3087
]'
3188
```
3289

33-
Or in config.json file:
90+
Or in `config.json`:
3491

3592
```json
3693
{
3794
"p2pConfig": {
3895
"announceAddresses": [
39-
"/ip4/<your-ip-addr>/tcp/9000",
40-
"/ip4/<your-ip-addr>/tcp/9001/tls/ws",
41-
"/ip4/<your-ip-addr>/tcp/9005/tls/wss"
96+
"/ip4/<your-ip>/tcp/9000",
97+
"/ip4/<your-ip>/tcp/9001/ws",
98+
"/ip4/<your-ip>/tcp/9001/tls/ws",
99+
"/ip4/<your-ip>/tcp/9001/tls/wss"
42100
]
43101
}
44102
}
45103
```
46104

47-
When TLS certificates are provisioned, you should see logs like:
105+
When a TLS certificate is provisioned successfully, you will see logs like:
48106

49107
```
50108
----- A TLS certificate was provisioned -----
51109
----- TLS addresses: -----
52-
/ip4/<your-ip-addr>/tcp/9001/sni/...
53-
/ip4/<your-ip-addr>/tcp/9005/sni/...
110+
/ip4/<your-ip>/tcp/9001/sni/...
111+
/ip4/<your-ip>/tcp/9001/sni/...
54112
----- End of TLS addresses -----
55113
```
56114

57-
In order to check connectivity, you can do the following:
115+
## Verifying Connectivity
58116

59-
### On your node, check and observe how your node sees itself:
117+
### Check how your node sees itself
60118

61119
```bash
62-
curl http://localhost:8000/getP2pPeer?peerId=16Uiu2HAkwWe6BFQXZWg6zE9X7ExynvXEe9BRTR5Wn3udNs7JpUDx
120+
curl http://localhost:8000/getP2pPeer?peerId=<your-peer-id>
63121
```
64122

65-
and observe the addresses section:
123+
Look at the `addresses` array in the response. Are any of those IPs/hostnames reachable from outside your network?
66124

67125
```json
68126
{
69127
"addresses": [
70-
{ "multiaddr": "/ip4/127.0.0.1/tcp/34227", "isCertified": false },
71-
{ "multiaddr": "/ip4/127.0.0.1/tcp/36913/ws", "isCertified": false },
72-
{ "multiaddr": "/ip4/172.15.0.1/tcp/34227", "isCertified": false },
73-
{ "multiaddr": "/ip4/172.15.0.1/tcp/36913/ws", "isCertified": false },
74-
{ "multiaddr": "/ip4/172.26.53.25/tcp/34227", "isCertified": false },
75-
{ "multiaddr": "/ip4/172.26.53.25/tcp/36913/ws", "isCertified": false },
76-
{ "multiaddr": "/ip6/::1/tcp/41157", "isCertified": false }
77-
],
78-
"protocols": [
79-
"/floodsub/1.0.0",
80-
"/ipfs/id/1.0.0",
81-
"/ipfs/id/push/1.0.0",
82-
"/ipfs/ping/1.0.0",
83-
"/libp2p/autonat/1.0.0",
84-
"/libp2p/circuit/relay/0.2.0/hop",
85-
"/libp2p/circuit/relay/0.2.0/stop",
86-
"/libp2p/dcutr",
87-
"/meshsub/1.0.0",
88-
"/meshsub/1.1.0",
89-
"/ocean/nodes/1.0.0",
90-
"/ocean/nodes/1.0.0/kad/1.0.0",
91-
"/ocean/nodes/1.0.0/lan/kad/1.0.0"
92-
],
93-
"metadata": {},
94-
"tags": {},
95-
"id": "16Uiu2HAkwWe6BFQXZWg6zE9X7ExynvXEe9BRTR5Wn3udNs7JpUDx",
96-
"publicKey": "08021221021efd24150c233d689ade0f9f467aa6a5a2969a5f52d70c85caac8681925093e3"
128+
{ "multiaddr": "/ip4/1.2.3.4/tcp/9000", "isCertified": false },
129+
{ "multiaddr": "/ip4/1.2.3.4/tcp/9001/ws", "isCertified": false },
130+
{ "multiaddr": "/ip4/1.2.3.4/tcp/9001/tls/ws", "isCertified": false }
131+
]
97132
}
98133
```
99134

100-
Are any of those IPs reachable from other nodes?
135+
### Check how your node is seen by the network
101136

102-
### To observe how your node is seen by others, start your node, wait a bit and then ask another node to give you details about you:
137+
Ask a known public node to report back what it knows about you:
103138

104139
```bash
105-
curl http://node2.oceanprotocol.com:8000/getP2pPeer?peerId=16Uiu2HAk
106-
wWe6BFQXZWg6zE9X7ExynvXEe9BRTR5Wn3udNs7JpUDx
140+
curl http://node2.oceanprotocol.com:8000/getP2pPeer?peerId=<your-peer-id>
107141
```
142+
143+
If the response is empty or missing your public address, the node is not reachable from the outside.
144+
145+
## All P2P Environment Variables
146+
147+
See [env.md](env.md#p2p) for the full list of P2P configuration options.

‎scripts/ocean-node-quickstart.sh‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -182,10 +182,10 @@ if [ -n "$P2P_ANNOUNCE_ADDRESS" ]; then
182182

183183
if [[ "$P2P_ANNOUNCE_ADDRESS" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
184184
# IPv4
185-
P2P_ANNOUNCE_ADDRESSES='["/ip4/'$P2P_ANNOUNCE_ADDRESS'/tcp/'$P2P_ipV4BindTcpPort'", "/ip4/'$P2P_ANNOUNCE_ADDRESS'/ws/tcp/'$P2P_ipV4BindWsPort'"]'
185+
P2P_ANNOUNCE_ADDRESSES='["/ip4/'$P2P_ANNOUNCE_ADDRESS'/tcp/'$P2P_ipV4BindTcpPort'", "/ip4/'$P2P_ANNOUNCE_ADDRESS'/tcp/'$P2P_ipV4BindWsPort'/ws", "/ip4/'$P2P_ANNOUNCE_ADDRESS'/tcp/'$P2P_ipV4BindWsPort'/tls/ws", "/ip4/'$P2P_ANNOUNCE_ADDRESS'/tcp/'$P2P_ipV4BindWsPort'/tls/wss"]'
186186
elif [[ "$P2P_ANNOUNCE_ADDRESS" =~ ^[a-zA-Z0-9.-]+$ ]]; then
187187
# FQDN
188-
P2P_ANNOUNCE_ADDRESSES='["/dns4/'$P2P_ANNOUNCE_ADDRESS'/tcp/'$P2P_ipV4BindTcpPort'", "/dns4/'$P2P_ANNOUNCE_ADDRESS'/ws/tcp/'$P2P_ipV4BindWsPort'"]'
188+
P2P_ANNOUNCE_ADDRESSES='["/dns4/'$P2P_ANNOUNCE_ADDRESS'/tcp/'$P2P_ipV4BindTcpPort'", "/dns4/'$P2P_ANNOUNCE_ADDRESS'/tcp/'$P2P_ipV4BindWsPort'/ws", "/dns4/'$P2P_ANNOUNCE_ADDRESS'/tcp/'$P2P_ipV4BindWsPort'/tls/ws", "/dns4/'$P2P_ANNOUNCE_ADDRESS'/tcp/'$P2P_ipV4BindWsPort'/tls/wss"]'
189189
fi
190190
else
191191
P2P_ANNOUNCE_ADDRESSES=''
@@ -686,8 +686,8 @@ services:
686686
# P2P_connectionsDialTimeout: ''
687687
P2P_ENABLE_UPNP: '$P2P_ENABLE_UPNP'
688688
# P2P_ENABLE_AUTONAT: ''
689-
# P2P_ENABLE_CIRCUIT_RELAY_SERVER: ''
690-
# P2P_ENABLE_CIRCUIT_RELAY_CLIENT: ''
689+
P2P_ENABLE_CIRCUIT_RELAY_SERVER: false
690+
P2P_ENABLE_CIRCUIT_RELAY_CLIENT: false
691691
# P2P_BOOTSTRAP_NODES: ''
692692
# P2P_FILTER_ANNOUNCED_ADDRESSES: ''
693693
DOCKER_COMPUTE_ENVIRONMENTS: '$DOCKER_COMPUTE_ENVIRONMENTS'
@@ -753,3 +753,7 @@ echo -e "\e[1;32mP2P IPv6 TCP Port: $P2P_ipV6BindTcpPort\e[0m"
753753
echo -e "\e[1;32mP2P IPv6 WebSocket Port: $P2P_ipV6BindWsPort\e[0m"
754754
echo ""
755755
echo -e "\e[1;32m4)\e[0m If using SSL/TLS with a custom domain name, make sure to listen on host port 443 for the HTTP API, or use a reverse proxy with TLS offloading"
756+
echo ""
757+
echo -e "If your node is not reachable by other peers (NAT, no public IP, port forwarding issues),"
758+
echo -e "refer to the networking guide for help with Dynamic DNS, port forwarding, and circuit relay:"
759+
echo -e "\e[1;34mhttps://github.com/oceanprotocol/ocean-node/blob/main/docs/networking.md\e[0m"

0 commit comments

Comments
 (0)