doc: add queue layer tutorial

doc/README.md

@@ -1,13 +1,12 @@
 # Documentation
 
-## Guide d'utilisation
-
-> TODO
+- [(FR) - Premiers pas](./fr/getting-started.md)
+- [(FR) - Architecture générale](./fr/general-architecture.md)
 
 ## 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.