From 3a0fd570bf6373a29d2fb9a98db601ab9e8d2b88 Mon Sep 17 00:00:00 2001 From: Kornel David Date: Thu, 17 Oct 2024 00:16:34 +0200 Subject: [PATCH] docs(/examples/elixir): Inititial refactor --- docs/examples/elixir-webrtc/README.md | 62 +++------------------------ 1 file changed, 6 insertions(+), 56 deletions(-) diff --git a/docs/examples/elixir-webrtc/README.md b/docs/examples/elixir-webrtc/README.md index 2fdf4a5..9b98a7d 100644 --- a/docs/examples/elixir-webrtc/README.md +++ b/docs/examples/elixir-webrtc/README.md @@ -17,69 +17,19 @@ See prerequisites [here](../../INSTALL.md#prerequisites). > [!NOTE] > -> Let's start with a disclaimer. The Nexus client-side application must work over a secure HTTPS connection, because [getUserMedia](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#browser_compatibility) is available only in secure contexts. This implies that the client-server signaling connection must be secure too. In this demo, we will aim to obtain a proper CA-signed certificate (self-signed certificates haven't been tested). Obtaining a valid TLS certificate is a challenge. Thus, the majority of the below installation guide will be about securing client connections to Nexus over TLS; as it turns out, once HTTPS is correctly working integrating Nexus with STUNner is very simple. +> Let's start with a disclaimer. Securing connection between the user and the server is a must. Read more about TLS [here](../TLS.md). In the below example, STUNner will be installed into the identically named namespace (`stunner`), while Nexus and the Ingress gateway will live in the `default` namespace. -### TLS certificates +### Ingress and Cert manager installation -As mentioned above, the Nexus WebRTC server will need a valid TLS cert, which means it must run behind an existing DNS domain name backed by a CA signed TLS certificate. This is simple if you have your own domain, but if you don't then [nip.io](https://nip.io) provides a dead simple wildcard DNS for any IP address. We will use this to "own a domain" and obtain a CA signed certificate for Nexus. This will allow us to point the domain name `client-.nip.io` to an ingress HTTP gateway in our Kubernetes cluster, which will then use some automation (namely, cert-manager) to obtain a valid CA signed cert. - -Note that public wildcard DNS domains might run into [rate limiting](https://letsencrypt.org/docs/rate-limits/) issues. If this occurs you can try [alternative services](https://moss.sh/free-wildcard-dns-services/) instead of `nip.io`. - -### Ingress - -The first step of obtaining a valid cert is to install a Kubernetes Ingress: this will be used during the validation of our certificates and to terminate client TLS encrypted contexts. - -Install an ingress controller into your cluster. We used the official [nginx ingress](https://github.com/kubernetes/ingress-nginx), but this is not required. - -```console -helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx -helm repo update -helm install ingress-nginx ingress-nginx/ingress-nginx -``` - -Wait until Kubernetes assigns an external IP to the Ingress. - -```console -until [ -n "$(kubectl get service ingress-nginx-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}')" ]; do sleep 1; done -``` - -Store the Ingress IP address Kubernetes assigned to our Ingress; this will be needed later when we configure the validation pipeline for our TLS certs. - -```console -kubectl get service ingress-nginx-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' -export INGRESSIP=$(kubectl get service ingress-nginx-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}') -export INGRESSIP=$(echo $INGRESSIP | sed 's/\./-/g') -``` - -### Cert manager - -We use the official [cert-manager](https://cert-manager.io) to automate TLS certificate management. - -Add the Helm repository, which contains the cert-manager Helm chart, and install the charts: - -```console -helm repo add cert-manager https://charts.jetstack.io -helm repo update -helm install cert-manager jetstack/cert-manager --namespace cert-manager \ - --create-namespace --set global.leaderElection.namespace=cert-manager \ - --set crds.enabled=true --timeout 600s -``` - -At this point we have all the necessary boilerplate set up to automate TLS issuance for Nexus. +To ingest secured traffic into the cluster, you need to install additional resources. Please follow the instructions in [this section](../TLS.md#installation) to install an Ingress and the Cert manager. ### STUNner -Now comes the fun part. The simplest way to run this demo is to clone the [STUNner git repository](https://github.com/l7mp/stunner) and deploy (after some minor modifications) the [manifest](nexus-server.yaml) packaged with STUNner. +Now comes the fun part. The simplest way to run this demo is to clone the [STUNner git repository](https://github.com/l7mp/stunner) and deploy (after some minor modifications) the [manifest](livekit-server.yaml) packaged with STUNner. -Install the STUNner gateway operator and STUNner via [Helm](https://github.com/l7mp/stunner-helm): - -```console -helm repo add stunner https://l7mp.io/stunner -helm repo update -helm install stunner-gateway-operator stunner/stunner-gateway-operator --create-namespace --namespace=stunner -``` +To install the stable version of STUNner, please follow the instructions in [this section](../../INSTALL.md#installation-1). Configure STUNner to act as a STUN/TURN server to clients, and route all received media to the Nexus pods. @@ -130,7 +80,7 @@ export STUNNERIP=$(kubectl get service udp-gateway -n stunner -o jsonpath='{.sta ``` ### Nexus Docker images -The crucial step of integrating *any* WebRTC media server with STUNner is to ensure that the server instructs the clients to use STUNner as the STUN/TURN server. +The crucial step of integrating *any* WebRTC media server with STUNner is to ensure that the server instructs the clients to use STUNner as the STUN/TURN server. Unfortunately, currently the [official Nexus Docker image](ghcr.io/elixir-webrtc/apps/nexus) does not support this configuration in runtime (by default Google's STUN server is hardcoded into it). Therefore, we have to modify this setting to STUNner's IP and build a new Docker image.