Host a fallback server¶

Use a Nostr4j TURN service when peers cannot connect directly or reach each other through the room. It forwards encrypted data over WebSockets.

Connect the room to the service¶

For rooms, supply the endpoint URL and TURN pool as shown in Add a TURN fallback. For streams, pass the URL to the connection constructor. Use an address reachable by both participants.

Run the reference implementation server¶

The ready-to-run image is available on GitHub Packages:

docker pull ghcr.io/nostrgameengine/nostr4j-turn-server:snapshot
docker run --rm -p 127.0.0.1:8081:8081 ghcr.io/nostrgameengine/nostr4j-turn-server:snapshot

You can also build the server from the GitHub source. With GraalVM 25 and native-image installed, run these commands from the repository root:

./gradlew :nostr4j-turn-server:test :nostr4j-turn-server:buildNativeExecutable
docker build -t nostr4j-turn-server nostr4j-turn-server
docker run --rm -p 127.0.0.1:8081:8081 nostr4j-turn-server

Build the executable before the image. The container runs as an unprivileged user; the command exposes port 8081 on the host's loopback address.

Put a TLS reverse proxy in front of the server to expose /turn over wss://, the secure WebSocket endpoint used by clients.

Configure the service¶

Pass environment variables when starting the container to change its listen address, authentication settings or identity. When running the server directly, system properties take precedence over the corresponding environment variables.