Skip to content

Commit 4466901

Browse files
ndrppndrpp
authored
feat(#1317): update quickstart script & networking docs (#1320)
* feat(#1317): update quickstart script & networking docs * fix: update known node url * fix: set only /tls/ws address to avoid user having to configure extra port * feat(#1317): auto detect user public IP in the quickstart script
1 parent 83f5966 commit 4466901

File tree

2 files changed

+120
-66
lines changed

2 files changed

+120
-66
lines changed

‎docs/networking.md‎

Lines changed: 98 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,107 +1,145 @@
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+
]'
17+
```
18+
19+
The `/tls/ws` entry enables [AutoTLS](#tls-and-sni-server-name-indication) for node-to-browser communication. AutoTLS provisions a certificate and serves TLS at the transport layer on the WebSocket port, making it browser-compatible — no DNS setup required on your part.
20+
21+
## Option 2: Dynamic DNS (no static IP)
22+
23+
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.
24+
25+
Popular free DDNS providers: [DuckDNS](https://www.duckdns.org/), [No-IP](https://www.noip.com/), [Dynu](https://www.dynu.com/).
26+
27+
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:
28+
29+
```bash
30+
P2P_ANNOUNCE_ADDRESSES='[
31+
"/dns4/mynode.duckdns.org/tcp/9000",
32+
"/dns4/mynode.duckdns.org/tcp/9001/ws",
33+
"/dns4/mynode.duckdns.org/tcp/9001/tls/ws"
34+
]'
35+
```
36+
37+
## Option 3: Port Forwarding
38+
39+
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.
40+
41+
1. Find the local IP of your machine (e.g. `192.168.1.50`).
42+
2. Log in to your router admin panel and add port forwarding rules:
43+
- External TCP port `9000` → `192.168.1.50:9000`
44+
- External TCP port `9001` → `192.168.1.50:9001`
45+
3. Find your public IP (e.g. via `curl ifconfig.me`) or set up a DDNS hostname (see Option 2).
46+
4. Set `P2P_ANNOUNCE_ADDRESSES` to your public IP or DDNS hostname as shown above.
47+
48+
If your router supports UPnP, the node can attempt to configure port forwarding automatically. Enable it with:
49+
50+
```bash
51+
P2P_ENABLE_UPNP=true
52+
```
53+
54+
UPnP is not reliable on all routers and should not be relied on as the sole method.
55+
56+
## Option 4: Circuit Relay (fallback)
57+
58+
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.
59+
60+
Enable the circuit relay client:
61+
62+
```bash
63+
P2P_ENABLE_CIRCUIT_RELAY_CLIENT=true
64+
P2P_CIRCUIT_RELAYS=1
65+
```
66+
67+
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.
68+
69+
Do not enable `P2P_ENABLE_CIRCUIT_RELAY_SERVER` on edge nodes; that setting is for well-connected nodes that want to help others.
70+
71+
---
1772

1873
## TLS and SNI (Server Name Indication)
1974

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`:
75+
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 a `/tls/ws` entry in `P2P_ANNOUNCE_ADDRESSES`, which the quickstart script does automatically.
2276

23-
Add to .env file
77+
AutoTLS serves TLS at the transport layer on the WebSocket port, making it standard browser-compatible WSS — no separate port is needed.
78+
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"
3086
]'
3187
```
3288

33-
Or in config.json file:
89+
Or in `config.json`:
3490

3591
```json
3692
{
3793
"p2pConfig": {
3894
"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"
95+
"/ip4/<your-ip>/tcp/9000",
96+
"/ip4/<your-ip>/tcp/9001/ws",
97+
"/ip4/<your-ip>/tcp/9001/tls/ws"
4298
]
4399
}
44100
}
45101
```
46102

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

49105
```
50106
----- A TLS certificate was provisioned -----
51107
----- TLS addresses: -----
52-
/ip4/<your-ip-addr>/tcp/9001/sni/...
53-
/ip4/<your-ip-addr>/tcp/9005/sni/...
108+
/ip4/<your-ip>/tcp/9001/sni/...
109+
/ip4/<your-ip>/tcp/9001/sni/...
54110
----- End of TLS addresses -----
55111
```
56112

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

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

61117
```bash
62-
curl http://localhost:8000/getP2pPeer?peerId=16Uiu2HAkwWe6BFQXZWg6zE9X7ExynvXEe9BRTR5Wn3udNs7JpUDx
118+
curl http://localhost:8000/getP2pPeer?peerId=<your-peer-id>
63119
```
64120

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

67123
```json
68124
{
69125
"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"
126+
{ "multiaddr": "/ip4/1.2.3.4/tcp/9000", "isCertified": false },
127+
{ "multiaddr": "/ip4/1.2.3.4/tcp/9001/ws", "isCertified": false },
128+
{ "multiaddr": "/ip4/1.2.3.4/tcp/9001/tls/ws", "isCertified": false }
129+
]
97130
}
98131
```
99132

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

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:
135+
Ask a known public node to report back what it knows about you:
103136

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

‎scripts/ocean-node-quickstart.sh‎

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,12 @@ ensure_jq() {
113113
fi
114114
}
115115

116+
get_public_ip() {
117+
if command -v curl >/dev/null 2>&1; then
118+
DETECTED_PUBLIC_IP=$(curl -s ifconfig.me)
119+
fi
120+
}
121+
116122
echo "Checking prerequisites (jq) are installed.."
117123
ensure_jq
118124

@@ -170,8 +176,14 @@ if [ "$enable_upnp" == "y" ]; then
170176
P2P_ENABLE_UPNP='true'
171177
fi
172178

173-
174-
read -p "Provide the public IPv4 address or FQDN where this node will be accessible: " P2P_ANNOUNCE_ADDRESS
179+
get_public_ip
180+
if [ -n "$DETECTED_PUBLIC_IP" ]; then
181+
echo -ne "Provide the public IPv4 address or FQDN where this node will be accessible (press Enter to accept detected address: "$DETECTED_PUBLIC_IP") ":
182+
read P2P_ANNOUNCE_ADDRESS
183+
P2P_ANNOUNCE_ADDRESS=${P2P_ANNOUNCE_ADDRESS:-$DETECTED_PUBLIC_IP}
184+
else
185+
read -p "Provide the public IPv4 address or FQDN where this node will be accessible: " P2P_ANNOUNCE_ADDRESS
186+
fi
175187

176188
if [ -n "$P2P_ANNOUNCE_ADDRESS" ]; then
177189
validate_ip_or_fqdn "$P2P_ANNOUNCE_ADDRESS"
@@ -182,10 +194,10 @@ if [ -n "$P2P_ANNOUNCE_ADDRESS" ]; then
182194

183195
if [[ "$P2P_ANNOUNCE_ADDRESS" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
184196
# IPv4
185-
P2P_ANNOUNCE_ADDRESSES='["/ip4/'$P2P_ANNOUNCE_ADDRESS'/tcp/'$P2P_ipV4BindTcpPort'", "/ip4/'$P2P_ANNOUNCE_ADDRESS'/ws/tcp/'$P2P_ipV4BindWsPort'"]'
197+
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"]'
186198
elif [[ "$P2P_ANNOUNCE_ADDRESS" =~ ^[a-zA-Z0-9.-]+$ ]]; then
187199
# FQDN
188-
P2P_ANNOUNCE_ADDRESSES='["/dns4/'$P2P_ANNOUNCE_ADDRESS'/tcp/'$P2P_ipV4BindTcpPort'", "/dns4/'$P2P_ANNOUNCE_ADDRESS'/ws/tcp/'$P2P_ipV4BindWsPort'"]'
200+
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"]'
189201
fi
190202
else
191203
P2P_ANNOUNCE_ADDRESSES=''
@@ -686,8 +698,8 @@ services:
686698
# P2P_connectionsDialTimeout: ''
687699
P2P_ENABLE_UPNP: '$P2P_ENABLE_UPNP'
688700
# P2P_ENABLE_AUTONAT: ''
689-
# P2P_ENABLE_CIRCUIT_RELAY_SERVER: ''
690-
# P2P_ENABLE_CIRCUIT_RELAY_CLIENT: ''
701+
P2P_ENABLE_CIRCUIT_RELAY_SERVER: false
702+
P2P_ENABLE_CIRCUIT_RELAY_CLIENT: false
691703
# P2P_BOOTSTRAP_NODES: ''
692704
# P2P_FILTER_ANNOUNCED_ADDRESSES: ''
693705
DOCKER_COMPUTE_ENVIRONMENTS: '$DOCKER_COMPUTE_ENVIRONMENTS'
@@ -753,3 +765,7 @@ echo -e "\e[1;32mP2P IPv6 TCP Port: $P2P_ipV6BindTcpPort\e[0m"
753765
echo -e "\e[1;32mP2P IPv6 WebSocket Port: $P2P_ipV6BindWsPort\e[0m"
754766
echo ""
755767
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"
768+
echo ""
769+
echo -e "If your node is not reachable by other peers (NAT, no public IP, port forwarding issues),"
770+
echo -e "refer to the networking guide for help with Dynamic DNS, port forwarding, and circuit relay:"
771+
echo -e "\e[1;34mhttps://github.com/oceanprotocol/ocean-node/blob/main/docs/networking.md\e[0m"

0 commit comments

Comments
 (0)