doc: add queue layer tutorial
This commit is contained in:
parent
8f0501b445
commit
1cfe07a343
@ -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)
|
||||
3
doc/fr/general-architecture.md
Normal file
3
doc/fr/general-architecture.md
Normal file
@ -0,0 +1,3 @@
|
||||
## Architecture générale
|
||||
|
||||
> TODO
|
||||
95
doc/fr/getting-started.md
Normal file
95
doc/fr/getting-started.md
Normal file
@ -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 !**
|
||||
48
doc/fr/tutorials/add-queue-layer.md
Normal file
48
doc/fr/tutorials/add-queue-layer.md
Normal file
@ -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.
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user