From 1cfe07a3430cf151b2ecce584e73a4d870a8eb09 Mon Sep 17 00:00:00 2001 From: William Petit Date: Sun, 28 May 2023 17:08:30 +0200 Subject: [PATCH] doc: add queue layer tutorial --- doc/README.md | 9 ++- doc/fr/general-architecture.md | 3 + doc/fr/getting-started.md | 95 +++++++++++++++++++++++++++++ doc/fr/tutorials/add-queue-layer.md | 48 +++++++++++++++ misc/packaging/common/config.yml | 31 +++++++++- 5 files changed, 180 insertions(+), 6 deletions(-) create mode 100644 doc/fr/general-architecture.md create mode 100644 doc/fr/getting-started.md create mode 100644 doc/fr/tutorials/add-queue-layer.md diff --git a/doc/README.md b/doc/README.md index 22cf570..e738980 100644 --- a/doc/README.md +++ b/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 \ No newline at end of file +- [(FR) - Ajouter un calque de type "file d'attente"](./fr/tutorials/add-queue-layer.md) \ No newline at end of file diff --git a/doc/fr/general-architecture.md b/doc/fr/general-architecture.md new file mode 100644 index 0000000..0d495a1 --- /dev/null +++ b/doc/fr/general-architecture.md @@ -0,0 +1,3 @@ +## Architecture générale + +> TODO \ No newline at end of file diff --git a/doc/fr/getting-started.md b/doc/fr/getting-started.md new file mode 100644 index 0000000..4fa5acc --- /dev/null +++ b/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__linux_.deb` + - `bouncer-proxy__linux_.deb` + - `bouncer-admin__linux_.deb` + + +3. Installer les paquets Debian + + ```bash + # Commencer par le paquet bouncer-bin + dpkg -i "bouncer-bin__linux_.deb" + + # Puis installer les paquets de services + dpkg -i "bouncer-proxy__linux_.deb" + dpkg -i "bouncer-admin__linux_.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://:8080/` dans un navigateur. Le site Cadoles s'affiche ! + +**Bravo, vous avez créé votre premier proxy avec Bouncer !** \ No newline at end of file diff --git a/doc/fr/tutorials/add-queue-layer.md b/doc/fr/tutorials/add-queue-layer.md new file mode 100644 index 0000000..99980a7 --- /dev/null +++ b/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://: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. \ No newline at end of file diff --git a/misc/packaging/common/config.yml b/misc/packaging/common/config.yml index 810c204..f178ed7 100644 --- a/misc/packaging/common/config.yml +++ b/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