Skip to content
minanodeBeta release

Run a relay

A native node relays gossip and serves blocks and ledgers to the peers it connects to. Open its peer port so other nodes can join through it, and open its WebRTC signaling listener to serve web nodes.

Accept native peers

Allow inbound TCP port 8302 in your firewall. Behind a router, also forward the port to this machine. In the command below, replace the example address with your public IP. Behind NAT, --libp2p-external-ip advertises that address. It does not set up port forwarding.

mina node \
  --network devnet -d ~/.mina-relay \
  --libp2p-port 8302 \
  --libp2p-external-ip 203.0.113.10

Keep and publish your peer id

The first start creates p2p-secret-key in the work directory, with mode 0600 on Unix. Later starts load it, so the peer id stays the same. Keep the file private, and keep the same work directory. If you delete the file, the identity changes at the next start. A malformed file or unsafe permissions stop the startup.

An explicit --p2p-secret-key or MINA_P2P_SEC_KEY takes precedence over the saved key. An encrypted --libp2p-keypair with MINA_LIBP2P_PASS takes precedence over both. Explicit keys do not replace the saved key. Never share a work directory between nodes, because they would use the same identity and share changing node data.

Read the public peer id from the startup log. Never read or publish the key file.

rg 'P2P identity' ~/.mina-relay/mina.log

Publish this native peer address, replacing the IP and peer id:

/ip4/203.0.113.10/tcp/8302/p2p/PEER_ID

Accept web node peers

Web nodes connect over WebRTC. To accept them, turn on the separate signaling listener with --webrtc-signal-port, or MINA_WEBRTC_SIGNAL_PORT. The listener's address defaults to 127.0.0.1. --webrtc-signal-addr, or MINA_WEBRTC_SIGNAL_ADDR, changes it. The binary needs the p2p-webrtc feature, which the default native build includes.

The listener serves only POST /mina/webrtc/signal and GET /mina/webrtc/signal/{offer}, with browser CORS. It exposes no dashboard, API, or worker control. Requests have a 30-second deadline and a 2 MiB body limit.

minaweb.org dials only the relays its build lists. Your relay serves a web node you run yourself with --relay. With --webrtc-sharing-relay, a relay introduces only browsers that turned sharing on. 0.21.0 removes --webrtc-signaling-relay. Use --webrtc-sharing-relay instead. Sharing with other browsers explains what an introduction exposes.

mina node --network devnet -d ~/.mina-relay \
  --libp2p-port 8302 --libp2p-external-ip 203.0.113.10 \
  --webrtc-signal-addr 127.0.0.1 --webrtc-signal-port 8303

Signaling exchanges the connection details. WebRTC then uses its own UDP connection. Add --webrtc-udp-ports 40000-40999, and allow that UDP range through the firewall. Behind a 1:1 NAT, also forward the range, and set --webrtc-nat-ip to your public IP.

Clients whose networks block direct UDP also need a TURN server. --webrtc-ice-servers reads a JSON file of ICE server settings in the browser's format, including STUN or TURN URLs and credentials.

A web node on the same machine uses the address below. Its TCP port is the signaling listener, separate from the libp2p port. The client builds the signaling URL from this host and port.

/ip4/127.0.0.1/tcp/8303/webrtc/http/p2p/PEER_ID

Put signaling behind HTTPS

An HTTPS page needs HTTPS signaling. Caddy can serve it and get its own TLS certificate. This Caddyfile also caps signaling bodies at 128 KiB. Use Caddy only for a relay that serves your own web node, as Serve the public explains.

Keep port 8303 on loopback. Keep the HTTP API and the dashboard on their default, 127.0.0.1:3000, as Open it on a server explains.

  1. Point a DNS name, here signal.example.org, at your server.
  2. Allow inbound TCP ports 80 and 443.
  3. Save this Caddyfile, with your domain in place of the example, and run Caddy with it:
signal.example.org {
  @signal path /mina/webrtc/signal /mina/webrtc/signal/*
  handle @signal {
    request_body {
      max_size 128KiB
    }
    reverse_proxy 127.0.0.1:8303
  }
  handle {
    respond "Not found" 404
  }
}
caddy run --config ./Caddyfile --adapter caddyfile

Give this web peer address to --relay. It resolves to https://signal.example.org:443/mina/webrtc/signal. Use the same public peer id as in the native address.

/dns4/signal.example.org/tcp/443/webrtc/https/p2p/PEER_ID

Proxy only the signaling listener. A path prefix at the proxy is optional. Clients accept /http-path/URL_ENCODED_PREFIX before /p2p/PEER_ID. If you use a prefix, strip it at the proxy before it forwards the request to the listener.

Serve the public

The Caddy setup above is for a relay that serves your own web node. Caddy has no built-in rate or connection limits, so don't use it for a relay that any page can reach.

The minaweb.org relays put nginx in front of the signaling listener, with per-address rate and connection limits. Each runs its own coturn 4.18.0, built from the pinned upstream release tarball, with TURN credentials that expire. A firewall rule lets coturn send only to that host's relay node.