Compare commits

...

2 Commits

Author SHA1 Message Date
wpetit 7a45a5ba3b fix(packaging): alpine startup script
Cadoles/bouncer/pipeline/head This commit looks good Details
2023-05-28 17:08:51 +02:00
wpetit 1cfe07a343 doc: add queue layer tutorial 2023-05-28 17:08:30 +02:00
7 changed files with 180 additions and 14 deletions

View File

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

View File

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

95
doc/fr/getting-started.md Normal file
View 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 !**

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

View File

@ -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

View File

@ -6,10 +6,6 @@ supervisor=supervise-daemon
output_log="/var/log/bouncer/admin.log"
error_log="$output_log"
start_pre() {
/usr/bin/bouncer --workdir /usr/share/bouncer --config /etc/bouncer/config.yml database migrate
}
depend() {
need net
}

View File

@ -6,10 +6,6 @@ supervisor=supervise-daemon
output_log="/var/log/bouncer/proxy.log"
error_log="$output_log"
start_pre() {
/usr/bin/bouncer --workdir /usr/share/bouncer --config /etc/bouncer/config.yml database migrate
}
depend() {
need net
}