Refactor configuration documentation

README.md

@@ -7,8 +7,9 @@
 TURN server in pure Elixir.
 
 Aims to implement:
-- [RFC 5766](https://datatracker.ietf.org/doc/html/rfc5766)
-- [RFC 6156](https://datatracker.ietf.org/doc/html/rfc6156#autoid-7)
+- RFC 5389: [Session Traversal Utilities for NAT (STUN)](https://datatracker.ietf.org/doc/html/rfc5389)
+- RFC 5766: [Traversal Using Relays around NAT (TURN): Relay Extensions to Session Traversal Utilities for NAT (STUN)](https://datatracker.ietf.org/doc/html/rfc5766)
+- RFC 6156: [Traversal Using Relays around NAT (TURN) Extension for IPv6](https://datatracker.ietf.org/doc/html/rfc6156#autoid-7)
 
 This project is in early stage of development and some of the features described in the RFCs might be missing.
 Expect breaking changes.
@@ -43,7 +44,7 @@ pc = new RTCPeerConnection({
 });
 ```
 
-## Installation
+## Installation and running
 
 1. From source
 
@@ -57,77 +58,17 @@ mix run --no-halt
 2. In Docker
 
 ```console
-docker run ghcr.io/elixir-webrtc/rel:latest
+docker run --network=host ghcr.io/elixir-webrtc/rel:latest
 ```
 
 ## Features and configuration
 
-Currently, Rel is configured via environment variables.
+Rel exposes Prometheus metrics endpoint (by default `http://127.0.0.1:9568/metrics`).
 
-### TURN server
+Rel supports authentication described in [A REST API For Access To TURN Services](https://datatracker.ietf.org/doc/html/draft-uberti-rtcweb-turn-rest-00#section-2.2).
+By default available under `http://127.0.0.1:4000/`. Example request would be `POST http://127.0.0.1:4000/&service=turn&username=johnsmith`.
+Key query parameter currently is not supported.
 
-Rel by default listens on `0.0.0.0:3478/UDP` for TURN traffic. This can be configured via `LISTEN_IP` and `LISTEN_PORT`.
-
-```console
-LISTEN_IP=0.0.0.0
-LISTEN_PORT=3478
-```
-
-`EXTERNAL_LISTEN_IP` is the IP address at which Rel is visible to clients. By default, Rel will try to guess the address
-based on active network interfaces, but this must be set explicitly when e.g. using Docker without `--network host`.
-
-```console
-EXTERNAL_LISTEN_IP=167.235.241.140
-```
-
-By default, Rel will use the same addresses (`RELAY_IP == LISTEN_IP and EXTERNAL_RELAY_IP == EXTERNAL_LISTEN_IP`) to open allocations, but this
-can be set to something else:
-
-```console
-RELAY_IP=0.0.0.0
-EXTERNAL_RELAY_IP=167.235.241.140
-```
-
-Rel will try to open relay addresses in `49_152 - 65_535` port range, but this can be changed. `RELAY_PORT_END` must be greater than `RELAY_PORT_START`.
-
-```console
-RELAY_PORT_START=35000
-RELAY_PORT_END=45000
-```
-
-Remember to use the `REALM` variable specific to your deployment. It's used in `REALM` STUN attributes. See
-[this section of RFC 2617](https://datatracker.ietf.org/doc/html/rfc2617#section-3.2.1) to learn about appropriate values for `REALM` attribute.
-
-```console
-REALM=my-amazing-turn.com
-```
-
-You can configure the number of running `listener` processes. By default, it is equal to number of running Erlang VM schedulers:
-
-```console
-LISTENER_COUNT=8
-```
-
-### Auth
-
-Auth Provider is an HTTP endpoint that provides credentials required by *A REST API For Access To TURN Services*.
-By default it is available at `http://127.0.0.1:4000/`, but the address, encryption and CORS can be configured:
-
-```console
-AUTH_IP=127.0.0.1
-AUTH_PORT=4000
-AUTH_USE_TLS=false
-AUTH_KEYFILE=./rel.key
-AUTH_CERTFILE./rel.cert
-AUTH_ALLOW_CORS=false
-```
-
-### Metrics
-
-By default, Rel provides Prometheus metrics at `http://127.0.0.1:9578/metrics`. The address can be configured:
-
-```console
-METRICS_IP=127.0.0.1
-METRICS_PORT=9568
-```
+credentials endpoint described in [Public deployment](#public-deployment) section (by default `http://127.0.0.1:4000/`).
 
+Rel is configured via environment variables. All of the possible options are described in [sample env file](./sample.env).

sample.env

@@ -0,0 +1,53 @@
+# Rel config env variables
+
+# Values presented in this example file are used by default
+# except where explicitly specified otherwise
+
+## TURN
+
+# Server address and port on which Rel listens for TURN/STUN requests
+LISTEN_IP=0.0.0.0
+LISTEN_PORT=3478
+
+# Server address as seen from the client
+# By default it is equal to LISTEN_PORT or (if LISTEN_PORT == 0.0.0.0) Rel
+# will try to guess the address based on host's network interfaces
+# It must be explicitly set when e.g. running in Docker without `--network=host`
+# EXTERNAL_LISTEN_IP=167.235.241.140
+
+# Address and port range where relay address will be allocated
+RELAY_IP=0.0.0.0
+RELAY_PORT_START=49152
+RELAY_PORT_END=65535
+
+# Relay address as seen from peers
+# Behave the same way as EXTERNAL_LISTEN_IP
+# EXTERNAL_RELAY_IP=167.235.241.140
+
+# Values used in REALM STUN attribute, see https://datatracker.ietf.org/doc/html/rfc5389#section-15.7
+REALM=example.com
+
+# Number of running listener processes. By default equal to number of running Erlang VM schedulers
+# LISTENER_COUNT=8
+
+## AUTH PROVIDER
+
+# Auth provider is available under http(s)://$AUTH_IP:$AUTH_PORT/
+AUTH_IP=127.0.0.1
+AUTH_PORT=4000
+
+# whether to use HTTP or HTTPS
+# If true, AUTH_KEYFILE and AUTH_CERFILE must be explicitly set
+AUTH_USE_TLS=false
+# AUTH_KEYFILE=./rel.key
+# AUTH_CERTFILE=./rel.cert
+
+# Whether to allos Cross-Origin Resource Sharing
+# May be useful when requesting credentials via JavaScript in the browser
+AUTH_ALLOW_CORS=false
+
+## METRICS
+
+# Prometheus metrics are served on http://$METRICS_IP:$METRICS_PORT/metrics
+METRICS_IP=127.0.0.1
+METRICS_PORT=9568