Self Hosting

Peerix relies on signaling servers and TURN servers for media relay under certain network conditions. You can self-host these servers as part of your deployment or use managed services provided by Peerix.

Below are short guides for setting up open-source signaling and TURN servers using Docker for development and production.

Signaling Server

You can use several open-source signaling servers that implement pub/sub functionality, such as NATS, MQTT, Mercure, and more. Peerix is designed to work with any signaling server that can exchange messages between peers, so choose the one that best fits your needs.

NATS Server

The NATS server handles signaling messages between peers. It lets peers discover each other and exchange messages needed to establish peer-to-peer connections. Use the official NATS server image to run a NATS server for development or production.

Run a local NATS server with WebSocket support:

cat << EOF > /tmp/nats-server.conf
websocket: {
  port: 8080,
  no_tls: true,
  same_origin: false
}
EOF

docker run --rm -p 4222:4222 -p 8080:8080 \
  -v /tmp/nats-server.conf:/nats-server.conf \
  nats:latest -c /nats-server.conf

Then use the URL ws://localhost:8080 to connect to your NATS server. How to use it with Peerix is described in the NATS driver section.

Mercure Server

The Mercure server is another option. It is a real-time hub for publishing and subscribing to updates using Server-Sent Events (SSE). Use the official Mercure server image for development or production.

Run a local Mercure server:

docker run --rm -p 8080:80 \
  -e SERVER_NAME=':80' \
  -e MERCURE_PUBLISHER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
  -e MERCURE_SUBSCRIBER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
  dunglas/mercure:latest caddy run --config /etc/caddy/dev.Caddyfile

Then use the URL http://localhost:8080/.well-known/mercure to connect. How to use it with Peerix is described in the SSE driver section.

Mosquitto Server

Eclipse Mosquitto is a lightweight MQTT broker that can be used for signaling. It’s well suited to low-bandwidth or high-latency networks.

Run a local Mosquitto server with WebSocket support:

cat << EOF > /tmp/mosquitto.conf
listener 9001
protocol websockets
allow_anonymous true
EOF

docker run --rm -p 1883:1883 -p 9001:9001 \
  -v /tmp/mosquitto.conf:/mosquitto.conf \
  eclipse-mosquitto:latest \
  mosquitto -c /mosquitto.conf

Then use the URL ws://localhost:9001/mqtt to connect. How to use it with Peerix is described in the MQTT driver section.

Centrifugo Server

Centrifugo is a real-time messaging server that supports WebSocket and HTTP communication. Use the official image to run Centrifugo for development or production.

Run a local Centrifugo server:

docker run --rm --ulimit nofile=65536:65536 -p 8000:8000 \
  -e CENTRIFUGO_CLIENT_ALLOWED_ORIGINS='*' \
  -e CENTRIFUGO_CLIENT_INSECURE=true \
  centrifugo/centrifugo centrifugo

Then use the URL ws://localhost:8000/connection/websocket to connect. How to use it with Peerix is described in the Centrifuge driver section.

TURN Server

A TURN server relays media when direct peer-to-peer communication is not possible. This is useful when NATs or firewalls prevent direct connections between peers. You can use Coturn to run your own TURN server for development and production.

Setting Up TURN Server

Start the TURN server with:

docker run -d \
  --name coturn \
  --network host \
  --tmpfs /var/lib/coturn:uid=0,gid=0,mode=1777 \
  -e DETECT_EXTERNAL_IP=yes \
  -e DETECT_RELAY_IP=yes \
  coturn/coturn:latest \
  --listening-port=3478 \
  --realm=your-realm \
  --user=username:password \
  --lt-cred-mech \
  --log-file=stdout

See the Coturn Docker image page for more configuration details.

Use it in Peer configuration:

const peer = new Peer({
  driver,
  iceServers: [
    {
      urls: 'turn:your-turn-server:3478',
      username: 'username',
      credential: 'password',
    },
  ],
});

Testing TURN Server

To verify your TURN server, use the Trickle ICE page from the WebRTC project:

1. Open the Trickle ICE page.
2. Add your TURN server details to the ICE server configuration.
3. Click “Gather candidates”.
4. Review the gathered candidates to confirm your TURN server is used for relaying.

If configured correctly, you should see candidates with the type relay, indicating that media would be relayed through your TURN server when needed.