Refactor example docs

README.md

@@ -555,17 +555,6 @@ applications into Kubernetes.
 
 ### Media-plane deployment model
 
-* [One to one video call with Kurento](/docs/examples/kurento-one2one-call/README.md): This tutorial
-  shows how to use STUNner to connect WebRTC clients to a media server deployed into Kubernetes
-  behind STUNner in the [media-plane deployment model](/docs/DEPLOYMENT.md). All this happens
-  *without* modifying the media server code in any way, just by adding 5-10 lines of
-  straightforward JavaScript to configure clients to use STUNner as the TURN server.
-* [Magic mirror with Kurento](/docs/examples/kurento-magic-mirror/README.md): This tutorial has been
-  adopted from the [Kurento](https://www.kurento.org) [magic
-  mirror](https://doc-kurento.readthedocs.io/en/stable/tutorials/node/tutorial-magicmirror.html)
-  demo, deploying a basic WebRTC loopback server behind STUNner with some media processing
-  added. In particular, the application uses computer vision and augmented reality techniques to
-  add a funny hat on top of faces.
 * [Video-conferencing with LiveKit](/docs/examples/livekit/README.md): This tutorial helps you deploy
   the [LiveKit](https://livekit.io) WebRTC media server behind STUNner. The docs also show how to
   obtain a valid TLS certificate to secure your signaling connections, courtesy of the
@@ -576,6 +565,12 @@ applications into Kubernetes.
   behind STUNner. The docs also show how to obtain a valid TLS certificate to secure your signaling
   connections, using [cert-manager](https://cert-manager.io), [nip.io](https://nip.io) and [Let's
   Encrypt](https://letsencrypt.org).
+* [Video-conferencing with Elixir WebRTC](/docs/examples/elixir-webrtc/README.md): This tutorial helps
+  you deploy a fully fledged [Elixir WebRTC](https://elixir-webrtc.org/) video-conferencing room called
+  [Nexus](https://github.com/elixir-webrtc/apps/tree/master/nexus) into Kubernetes
+  behind STUNner. The docs also show how to obtain a valid TLS certificate to secure your signaling
+  connections, using [cert-manager](https://cert-manager.io), [nip.io](https://nip.io) and [Let's
+  Encrypt](https://letsencrypt.org).
 * [Video-conferencing with Jitsi](/docs/examples/jitsi/README.md): This tutorial helps you deploy a
   fully fledged [Jitsi](https://jitsi.org) video-conferencing service into Kubernetes behind
   STUNner. The docs also show how to obtain a valid TLS certificate to secure your signaling
@@ -595,6 +590,17 @@ applications into Kubernetes.
   providing an ingress gateway service to a remote desktop application. We use
   [neko.io](https://neko.m1k1o.net) to run a browser in a secure container inside the Kubernetes
   cluster, and stream the desktop to clients via STUNner.
+* [One to one video call with Kurento](/docs/examples/kurento-one2one-call/README.md): This tutorial
+  shows how to use STUNner to connect WebRTC clients to a media server deployed into Kubernetes
+  behind STUNner in the [media-plane deployment model](/docs/DEPLOYMENT.md). All this happens
+  *without* modifying the media server code in any way, just by adding 5-10 lines of
+  straightforward JavaScript to configure clients to use STUNner as the TURN server.
+* [Magic mirror with Kurento](/docs/examples/kurento-magic-mirror/README.md): This tutorial has been
+  adopted from the [Kurento](https://www.kurento.org) [magic
+  mirror](https://doc-kurento.readthedocs.io/en/stable/tutorials/node/tutorial-magicmirror.html)
+  demo, deploying a basic WebRTC loopback server behind STUNner with some media processing
+  added. In particular, the application uses computer vision and augmented reality techniques to
+  add a funny hat on top of faces.
 
 ## Documentation
 

docs/INSTALL.md

@@ -28,7 +28,7 @@ helm install stunner-gateway-operator stunner/stunner-gateway-operator --create-
     --namespace=stunner-system
 ```
 
-And that's all: you don't need to install the dataplane separately, this is handled automatically by the operator.  The `stunnerd` pods created by the operator can be customized using the Dataplane custom resource: you can specify the `stunnerd` container image version, provision resources per each `stunenrd` pod, deploy into the host network namespace, etc.; see the documentation [here](https://pkg.go.dev/github.com/l7mp/stunner-gateway-operator/api/v1alpha1#DataplaneSpec).
+And that's all: you don't need to install the dataplane separately, this is handled automatically by the operator.  The `stunnerd` pods created by the operator can be customized using the Dataplane custom resource: you can specify the `stunnerd` container image version, provision resources per each `stunnerd` pod, deploy into the host network namespace, etc.; see the documentation [here](https://pkg.go.dev/github.com/l7mp/stunner-gateway-operator/api/v1alpha1#DataplaneSpec).
 
 ### Development version
 
@@ -63,6 +63,22 @@ helm install stunner-prod stunner/stunner --create-namespace --namespace=stunner
 helm install stunner-dev stunner/stunner --create-namespace --namespace=stunner-dev
 ```
 
+### Skip install CRDs
+
+You can install the STUNner chart without the Gateway API CRDs and STUNner CRDs with the `--skip-crds` flag. However, ensure that the CRDs are already present in the cluster, as the STUNner Gateway Operator will fail to start without them.
+
+```console
+helm install stunner-gateway-operator stunner/stunner-gateway-operator --create-namespace \
+    --namespace=stunner-system --skip-crds
+```
+
+To manually install the CRDs:
+
+```console
+kubectl apply -k github.com/kubernetes-sigs/gateway-api/config/crd?ref=v1.0.0
+kubectl apply -f https://raw.githubusercontent.com/l7mp/stunner-helm/refs/heads/main/helm/stunner-gateway-operator/crds/stunner-crd.yaml
+```
+
 ## Customization
 
 The Helm charts let you fine-tune STUNner features, including [compute resources](#resources) provisioned for `stunnerd` pods, [UDP multithreading](#udp-multithreading), and[graceful shutdown](#graceful-shutdown).

docs/README.md

@@ -36,14 +36,15 @@
 
 ### Media-plane deployment model
 
-* [One to one video call with Kurento](examples/kurento-one2one-call)
-* [Magic mirror with Kurento](examples/kurento-magic-mirror/README.md)
 * [Video-conferencing with LiveKit](examples/livekit/README.md)
 * [Video-conferencing with mediasoup](examples/mediasoup/README.md)
 * [Video-conferencing with Janus](examples/janus/README.md)
+* [Video-conferencing with Elixir WebRTC](examples/elixir-webrtc/README.md)
 * [Video-conferencing with Jitsi](examples/jitsi/README.md)
 * [Cloud-gaming with CloudRetro](examples/cloudretro/README.md)
 * [Remote desktop access with Neko](examples/neko/README.md)
+* [One to one video call with Kurento](examples/kurento-one2one-call)
+* [Magic mirror with Kurento](examples/kurento-magic-mirror/README.md)
 
 ## Manuals
 

docs/examples/TLS.md

@@ -0,0 +1,103 @@
+# TLS
+
+This documentation sums up the TLS and certificate issues you will encounter deploying the examples.
+
+## The issue
+
+Some 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 the demos, 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 installation guides will be about securing client connections to the client-side apps and the WebRTC mediaservers over TLS. Once HTTPS is correctly working, integrating the mediaservers with STUNner is very simple.
+
+## TLS certificates
+
+Some WebRTC servers 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, we still have a solution for that.
+
+> [!NOTE]
+>
+> By default, the examples and commands snippets assume you don't own a domain.
+
+### If you don't have your own domain
+
+[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 the mediaserver. This will allow us to point the domain name `client-<ingress-IP>.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.
+
+### If you have your own domain
+
+We use `nip.io` to "own a domain" in some examples. To replace it with your own domain, you must locate the corresponding lines in the specific mediaserver's configuration file and overwrite them.
+
+> [!NOTE]
+>
+> Although they might look similar, every mediaserver has a different configuration. You might need to (re)configure more things in one mediaserver than another.
+
+> [!NOTE]
+>
+> Make sure to set up your Ingress correctly and do not forget to create a new DNS record pointing to your Ingress' IP address!
+
+## Installation
+
+### Ingress
+
+The first step of secured traffic ingestion is obtaining a valid cert by installing 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 other Ingress implementations might work (check their documentation for install steps).
+
+```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 the demo.
+
+## Troubleshooting
+
+#### Wildcard DNS domain rate limiting
+
+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`.
+
+#### Certificate issuance
+
+If you work with certificates you must be aware that signing a certificate request takes some time and it differs for every CA (certificate authority). If you sense there is a problem with the certificate being signed or issued, you can check it directly and see what is going on.
+
+First, you'll need to find the certificate and its related resources in your cluster.
+```console
+kubectl get certificate -A
+kubectl get certificaterequests.cert-manager.io -A
+kubectl get certificatesigningrequests.certificates.k8s.io
+```
+
+To find more information about them
+```console
+kubectl describe certificate <certificate> -A
+kubectl describe certificaterequests.cert-manager.io <cert-request> -A
+kubectl describe certificatesigningrequests.certificates.k8s.io <cert-signing-request>
+```
+
+# Help
+
+STUNner development is coordinated in Discord, feel free to [join](https://discord.gg/DyPgEsbwzc).

docs/examples/benchmark/README.md

@@ -165,3 +165,7 @@ Notice that the average packets/second rate will be slightly lower in case of a
 
 * It is advised to repeat the measurment with different packet sizes. Recommended packet sizes in bytes are 64, 128, 256, 512, 1024, and 1200. Small packet sizes result lower effective throughput (when packet drop is < 1%).
 * Measuring [measuring one-way latency](https://stackoverflow.com/questions/63793030/iperf2-latency-is-a-two-way-or-one-way-latency) with `iperf` requires the clocks at the iperf client and server to be synchronized.  Without this the results may be corrupted, and you may even see negative latencies.
+
+# Help
+
+STUNner development is coordinated in Discord, feel free to [join](https://discord.gg/DyPgEsbwzc).

docs/examples/cloudretro/README.md

@@ -15,11 +15,7 @@ In this demo you will learn how to:
 
 ## Prerequisites
 
-The below installation instructions require an operational cluster running a supported version of
-Kubernetes (>1.22). Most hosted or private Kubernetes cluster services will work, but make sure
-that the cluster comes with a functional load-balancer integration (all major hosted Kubernetes
-services should support this). Otherwise, STUNner will not be able to allocate a public IP address
-for clients to reach your WebRTC infra.
+See prerequisites [here](../../INSTALL.md#prerequisites).
 
 You will need a basic familiarity [with the CloudRetro
 architecture](https://webrtchacks.com/open-source-cloud-gaming-with-webrtc), especially the concept
@@ -79,12 +75,7 @@ the CloudRetro servers running on a private pod IP address. That is where STUNne
 
 ### STUNner
 
-First we install STUNner gateway operator with helm ([more info](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
-```
+First we install the stable version of STUNner, please follow the instructions in [this section](../../INSTALL.md#installation-1).
 
 Wait until all the necessary resources are up and running, then you are ready to continue.
 
@@ -242,3 +233,7 @@ kubectl delete -f cloudretro-setup-coordinator.yaml
 kubectl delete -f cloudretro-setup-workers.yaml
 kubectl delete -f cloudretro-stunner-cleanup.yaml
 ```
+
+# Help
+
+STUNner development is coordinated in Discord, feel free to [join](https://discord.gg/DyPgEsbwzc).

docs/examples/direct-one2one-call/README.md

@@ -296,3 +296,7 @@ Delete the demo deployment using the below command:
 kubectl delete -f docs/examples/direct-one2one-call/direct-one2one-call-server.yaml
 kubectl delete -f docs/examples/direct-one2one-call/direct-one2one-call-stunner.yaml
 ```
+
+# Help
+
+STUNner development is coordinated in Discord, feel free to [join](https://discord.gg/DyPgEsbwzc).