doc: add queue layer tutorial

doc/README.md

@@ -1,13 +1,12 @@
 # Documentation
 
-## Guide d'utilisation
+- [(FR) - Premiers pas](./fr/getting-started.md)
-
+- [(FR) - Architecture générale](./fr/general-architecture.md)
-> TODO
 
 ## Référence
 
-> TODO
+- [Fichier de configuration](../misc/packaging/common/config.yml)
 
 ## Tutoriels
 
-> TODO
+- [(FR) - Ajouter un calque de type "file d'attente"](./fr/tutorials/add-queue-layer.md)

doc/fr/general-architecture.md

@@ -0,0 +1,3 @@
+## Architecture générale
+
+> TODO

doc/fr/getting-started.md

@@ -0,0 +1,95 @@
+# Premiers pas
+
+## Prérequis
+
+- Une machine Ubuntu 22.04
+
+## Étapes
+
+### Installation
+
+1. Installer le serveur Redis
+
+    ```bash
+    apt update
+    apt install redis
+    ```
+
+2. Sur votre machine Ubuntu, télécharger les dernières versions disponibles du paquet Debian correspondant à votre architecture sur la page ["Versions"](https://forge.cadoles.com/Cadoles/bouncer/releases) du projet:
+    - `bouncer-bin_<version>_linux_<arch>.deb`
+    - `bouncer-proxy_<version>_linux_<arch>.deb`
+    - `bouncer-admin_<version>_linux_<arch>.deb`
+
+
+3. Installer les paquets Debian
+
+    ```bash
+    # Commencer par le paquet bouncer-bin
+    dpkg -i "bouncer-bin_<version>_linux_<arch>.deb"
+
+    # Puis installer les paquets de services
+    dpkg -i "bouncer-proxy_<version>_linux_<arch>.deb"
+    dpkg -i "bouncer-admin_<version>_linux_<arch>.deb"
+    ```
+
+4. Générer un jeton d'authentification pour le CLI d'administration
+
+    ```bash
+    bouncer --config /etc/bouncer/config.yml auth create-token --role writer --subject $(whoami) > .bouncer-token
+    ```
+
+5. Tester que le CLI est en capacité d'interroger l'API d'administration
+
+    ```bash
+    bouncer admin query proxy
+    ```
+
+    Un message équivalent à celui ci devrait s'afficher:
+
+    ```
+    +------+---------+--------+
+    | NAME | ENABLED | WEIGHT |
+    +------+---------+--------+
+    +------+---------+--------+
+    ```
+
+### Créer un premier proxy
+
+1. Créer un proxy vers https://www.cadoles.com via le CLI
+
+    ```bash
+    # Création du proxy nommé 'cadoles' vers https://www.cadoles.com
+    bouncer admin proxy create --to https://www.cadoles.com --proxy-name cadoles
+    ```
+
+    Un message équivalent à celui ci devrait s'afficher:
+
+    ```
+    +---------+-------+-------------------------+---------+--------+-------------------------+-------------------------+
+    | NAME    | FROM  | TO                      | ENABLED | WEIGHT | CREATEDAT               | UPDATEDAT               |
+    +---------+-------+-------------------------+---------+--------+-------------------------+-------------------------+
+    | cadoles | ["*"] | https://www.cadoles.com | false   | 0      | "2023-05-28T14:28:46... | "2023-05-28T14:28:46... |
+    +---------+-------+-------------------------+---------+--------+-------------------------+-------------------------+
+    ```
+
+
+2. À ce stade, le proxy est créé mais encore inactif. Activer le proxy
+
+    ```bash
+    # Activation du proxy
+    bouncer admin proxy update --proxy-name cadoles --enabled=true
+    ```
+
+    Un message équivalent à celui ci devrait s'afficher:
+
+    ```
+    +---------+-------+-------------------------+---------+--------+-------------------------+-------------------------+
+    | NAME    | FROM  | TO                      | ENABLED | WEIGHT | CREATEDAT               | UPDATEDAT               |
+    +---------+-------+-------------------------+---------+--------+-------------------------+-------------------------+
+    | cadoles | ["*"] | https://www.cadoles.com | true    | 0      | "2023-05-28T14:28:46... | "2023-05-28T14:28:55... |
+    +---------+-------+-------------------------+---------+--------+-------------------------+-------------------------+
+    ```
+
+3. Ouvrir la page `https://<ip_serveur>:8080/` dans un navigateur. Le site Cadoles s'affiche !
+
+**Bravo, vous avez créé votre premier proxy avec Bouncer !**

doc/fr/tutorials/add-queue-layer.md

@@ -0,0 +1,48 @@
+# Ajouter un calque de type "file d'attente"
+
+## Étapes
+
+1. Sur le serveur hébergeant les services Bouncer, utiliser le CLI pour créer un nouveau calque ("layer") pour votre proxy. Dans l'exemple, nous utiliserons le proxy `cadoles` créé dans le cadre du tutoriels ["Premiers pas"](../getting-started.md).
+
+    ```bash
+    # Création d'un calque nommé 'my-queue' pour le proxy 'cadoles' de type 'queue'
+    bouncer admin layer create --proxy-name cadoles --layer-name my-queue --layer-type queue
+    ```
+
+    Un message équivalent à celui ci devrait s'afficher:
+
+    ```
+    +----------+-------+---------+--------+---------+-------------------------+-------------------------+
+    | NAME     | TYPE  | ENABLED | WEIGHT | OPTIONS | CREATEDAT               | UPDATEDAT               |
+    +----------+-------+---------+--------+---------+-------------------------+-------------------------+
+    | my-queue | queue | false   | 0      | {}      | "2023-05-28T14:40:25... | "2023-05-28T14:40:25... |
+    +----------+-------+---------+--------+---------+-------------------------+-------------------------+
+    ```
+
+2. À ce stade, le calque est encore inactif. Définir la capacité de la file d'attente à 1 et activer le calque en utilisant le CLI
+
+    ```bash
+    bouncer admin layer update --proxy-name cadoles --layer-name my-queue --enabled=true --options '{"capacity": 1}'
+    ```
+
+    Un message équivalent à celui ci devrait s'afficher:
+
+    ```
+    +----------+-------+---------+--------+----------------+-------------------------+-------------------------+
+    | NAME     | TYPE  | ENABLED | WEIGHT | OPTIONS        | CREATEDAT               | UPDATEDAT               |
+    +----------+-------+---------+--------+----------------+-------------------------+-------------------------+
+    | my-queue | queue | true    | 0      | {"capacity":1} | "2023-05-28T14:51:45... | "2023-05-28T14:52:21... |
+    +----------+-------+---------+--------+----------------+-------------------------+-------------------------+
+    ```
+
+    > **Astuce**
+    > 
+    > Les options de chaque type de calque répondent à un schéma spécifique, défini au format [JSON Schema](https://json-schema.org/).
+    > 
+    > Par exemple, le schéma du calque type 'queue' est consultable [ici](../../../internal/queue/schema/layer-options.json).
+
+3. Le proxy `cadoles` a désormais une file d'attente avec une capacité d'un seul utilisateur. Vous pouvez effectuer le test en ouvrant votre navigateur sur l'adresse `http://<ip_serveur>:8080/` puis en ouvrant une fenêtre de navigation privée sur la même adresse:
+    - La première fenêtre devrait afficher le site Cadoles;
+    - La seconde fenêtre devrait afficher le message suivant: `queued (rank: 2, status: 2/1)`.
+
+    Si vous laissez expirer la "session" de la première fenêtre (environ 1 minute par défaut) et que vous rafraîchissez la seconde, vous devriez avoir une inversion des états.

misc/packaging/common/config.yml

@@ -1,10 +1,18 @@
+# Configuration du service "admin"
 admin:
     http:
+        # Hôte d'écoute du service, 
+        # 0.0.0.0 pour écouter sur toutes les interfaces
         host: 127.0.0.1
+        # Port d'écoute du service
         port: 8081
+
+    # Configuration CORS du service
+    # Uniquement nécessaire si un frontend web
+    # est branché sur l'API d'administration.
     cors:
         allowedOrigins:
-            - http://localhost:3001
+            - http://localhost:8081
         allowCredentials: true
         allowMethods:
             - POST
@@ -21,14 +29,35 @@ admin:
     auth:
         issuer: http://127.0.0.1:8081
         privateKey: /etc/bouncer/admin-key.json
+
+# Configuration du service "proxy"
 proxy:
     http:
+        # Hôte d'écoute du service, 
+        # 0.0.0.0 pour écouter sur toutes les interfaces
         host: 0.0.0.0
+        # Port d'écoute du service
         port: 8080
+
+# Configuration du client Redis
+#
+# Les modes "standalone", "sentinel" et "cluster" de Redis sont supportés:
+# - Mode "standalone": renseigner une seule entrée dans redis.addresses;
+# - Mode "sentinel": renseigner une adresse dans redis.master et une ou plusieurs adresses dans redis.addresses;
+# - Mode "cluster": renseigner plusieurs adresses dans redis.addresses et laisser redis.master vide.
 redis:
     addresses:
         - localhost:6379
     master: ""
+
+# Configuration des logs
 logger:
+    # Niveau de verbosité
+    # 0 - DEBUG
+    # 1 - INFO
+    # 2 - WARNING
+    # 3 - ERROR
+    # 4 - FATAL
     level: 1
+    # Format des logs, "human" ou "json"
     format: human