Refactor example docs #164

davidkornel · 2024-09-29T16:25:46Z

WIP

This PR aims to refactor the documentation of the examples. We can remove some redundant text by referring to existing sections of the official documentation under the /docs directory. The PR itself aims to figure out a better format for current/future examples to improve the user experience. Less reading means faster deployment. However, this takes away some information that reaches the users as they tend to skip referred docs. Also, I'm afraid users will lose it if they need to navigate between multiple docs.

Note, that I tried to shorten the length of the example as much as possible, so we would have a starting point.

TODO:

TLS.md Section ### If you have your own domain
Move kurrento to the end of the list in all example listings.
Refactor all other examples.
add TLS.md to readthedocs (edit the mkdocs.yml)
Revert this commit
Fix blockquote syntax
Add elixir example from Add Elixir WebRTC - Nexus app demo to docs #162

Questions to figure out:

Separate TLS.md doc in the examples directory:
- Should we keep it there?
- Should we expand it by including something I missed?
- What else should we include in the troubleshooting section?
Troubleshooting doc in general (not just TLS)
- This might worth another issue/PR
STUNner install guide
- Although, it makes sense to point to the INSTALL.md guide, it feels weird to remove those two commands just to include a "go there to find out" text. WDYT?

* init version of the TLS docs * including: * why tls is needed * what to do if you own a domain of if you don't * a troubleshooting * refactored version of the Janus readme

…ction. It is included

…undantly include

rg0now · 2024-10-01T14:41:39Z

docs/examples/janus/README.md

@@ -11,7 +11,11 @@ In this demo you will learn 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. As a regrettable exception, Minikube is unfortunately not supported for this demo. The reason is that [Let's Encrypt certificate issuance is not available with nip.io](https://medium.com/@EmiiKhaos/there-is-no-possibility-that-you-can-get-lets-encrypt-certificate-with-nip-io-7483663e0c1b); later on you will learn more about why this is crucial above.
+See prerequisites [here](../../INSTALL.md#prerequisites).


Instead of a separate section, can we just say that you need (1) a Kubernetes cluster (and link the Prereq seq above), and STUNner installed (and link the INSTALL.md).

This allows us to remove the "Installation" section later, as well as the part "To install the stable version of STUNner, please follow the instructions in this section." Let's just put all prereqs/installations/whatnot to the front: one sentence, clean and simple.

rg0now · 2024-10-01T14:58:43Z

docs/examples/TLS.md

+First, you'll need to find the certificate and its related resources in your cluster.
+```console
+kubectl get certificate -A
+


Can we remove the extra linefeed here?

rg0now · 2024-10-01T15:01:58Z

Thanks, this is really cool. Minor points:

As per the TLS docs: I dunno a better place either so let's just leave it where it is now.
Kurento: it seems to still be the first one on the list, isn't it?
Rest: do you intend to rewrite the rest of the tutorials TLS-wise too? I'd love to have them consistent

levaitamas

Great work! Left some minor comments, otherwise looks good.

One additional TODO:

add TLS.md to readthedocs (edit the mkdocs.yml)

docs/examples/TLS.md

davidkornel · 2024-10-09T14:28:12Z

One additional TODO:

add TLS.md to readthedocs (edit the mkdocs.yml)

@levaitamas I'm not sure if I should include it in the examples section or make it top-level like all the other larger documents. What do you say?

levaitamas · 2024-10-09T14:31:30Z

One additional TODO:

add TLS.md to readthedocs (edit the mkdocs.yml)

@levaitamas I'm not sure if I should include it in the examples section or make it top-level like all the other larger documents. What do you say?

Since it begins as This documentation sums up the TLS and certificate issues you will encounter deploying the examples., I would put it to the top of examples with a title: Configuring TLS for examples or sth like that. wdyt?

…from the LiveKit server's config

davidkornel · 2024-10-11T19:48:20Z

Mediasoup and livekit demos done. mediasoup arch fig missing

davidkornel · 2024-10-15T18:57:06Z

Jitsi done

levaitamas · 2024-10-16T07:39:37Z

@levaitamas @rg0now Could you give me a review here? I refactored everything or at least most things. Do you see anything that's missing or should be worked on?

TODO add elixir demo from pr #162

Great work! Added some minor suggestions, otherwise LGTM.

davidkornel · 2024-10-19T15:05:58Z

@rg0now @levaitamas please review once more.

levaitamas · 2024-10-19T16:58:20Z

docs/examples/neko/README.md

+To run this example, you need:
+* a [Kubernetes cluster](../../INSTALL.md#prerequisites),
+* a [deployed STUNner](../../INSTALL.md#installation-1) (presumably the latest stable version),
+* an [Ingress controller](../TLS.md#ingress) to ingest traffic into the cluster.


the Ingress is optional

levaitamas · 2024-10-19T17:03:45Z

docs/examples/TLS.md

+
+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 this is not required.


Suggested change

Install an Ingress controller into your cluster. We used the official [nginx ingress](https://github.com/kubernetes/ingress-nginx), but this is not required.

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).

levaitamas · 2024-10-19T17:04:26Z

docs/examples/elixir-webrtc/README.md

+* a [Kubernetes cluster](../../INSTALL.md#prerequisites),
+* a [deployed STUNner](../../INSTALL.md#installation-1) (presumably the latest stable version),
+* an [Ingress controller](../TLS.md#ingress) to ingest traffic into the cluster,
+* a [Cert-manager](../TLS.md#cert-manager) to secure traffic.
