From 851f5d64ccd690823c77743409c532e0895f79ea Mon Sep 17 00:00:00 2001 From: William Petit Date: Thu, 29 Jun 2023 20:13:21 -0600 Subject: [PATCH] doc: add getting started with sources tutorial --- doc/README.md | 1 + doc/fr/tutorials/add-queue-layer.md | 4 +- doc/fr/tutorials/create-custom-layer.md | 57 +------- .../tutorials/getting-started-with-sources.md | 125 ++++++++++++++++++ 4 files changed, 130 insertions(+), 57 deletions(-) create mode 100644 doc/fr/tutorials/getting-started-with-sources.md diff --git a/doc/README.md b/doc/README.md index 7c5ea7c..38d68d7 100644 --- a/doc/README.md +++ b/doc/README.md @@ -16,4 +16,5 @@ ### Développement +- [(FR) - Démarrer avec les sources](./fr/tutorials/getting-start-with-sources.md) - [(FR) - Créer son propre layer](./fr/tutorials/create-custom-layer.md) \ No newline at end of file diff --git a/doc/fr/tutorials/add-queue-layer.md b/doc/fr/tutorials/add-queue-layer.md index fa7b0ad..a6a3d5f 100644 --- a/doc/fr/tutorials/add-queue-layer.md +++ b/doc/fr/tutorials/add-queue-layer.md @@ -2,7 +2,7 @@ ## É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). +1. Sur le serveur hébergeant les services Bouncer, utiliser le CLI pour créer un nouveau 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' @@ -19,7 +19,7 @@ +----------+-------+---------+--------+---------+-------------------------+-------------------------+ ``` -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 +2. À ce stade, le layer est encore inactif. Définir la capacité de la file d'attente à 1 et activer le layer en utilisant le CLI: ```bash bouncer admin layer update --proxy-name cadoles --layer-name my-queue --layer-enabled=true --layer-options '{"capacity": 1}' diff --git a/doc/fr/tutorials/create-custom-layer.md b/doc/fr/tutorials/create-custom-layer.md index 1380963..91bb39c 100644 --- a/doc/fr/tutorials/create-custom-layer.md +++ b/doc/fr/tutorials/create-custom-layer.md @@ -1,64 +1,11 @@ # Créer son propre layer -Dans ce tutoriel, nous allons voir comme implémenter un layer personnalisé qui permettra d'ajouter une authentification de type [`Basic Auth](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) à un proxy. +Dans ce tutoriel, nous verrons comment implémenter un layer personnalisé qui permettra d'ajouter une authentification de type [`Basic Auth](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) à un proxy. ## Prérequis -Les éléments suivants doivent être installés sur votre machine: - -- [Golang > 1.20](https://go.dev/) -- [Docker](https://www.docker.com/) -- [Git](https://git-scm.com/) -- [GNU Make](https://www.gnu.org/software/make/) - +Avoir un environnement de développement local fonctionnel. Voir tutoriel ["Démarrer avec les sources"](./getting-started-with-sources.md). ## Étapes - -### Préparer son environnement de développement - -1. Cloner le dépôt des sources du projet Bouncer - - ``` - git clone https://forge.cadoles.com/Cadoles/bouncer - ``` - -2. Se positionner dans le répertoire du projet - - ``` - cd bouncer - ``` - -3. Lancer le projet en mode "développement" - - ``` - make watch - ``` - -Si toutes les dépendances sont correctement installées et configurées sur votre machine, la console devrait afficher une série de messages pour ensuite s'arrêter sur quelque chose ressemblant à: - -``` -14:47:06: daemon: make run BOUNCER_CMD="--config config.yml server admin run" -2023-06-23 20:47:06.095 [INFO] <./internal/command/server/admin/run.go:42> RunCommand.func1 listening {"url": "http://127.0.0.1:8081"} -2023-06-23 20:47:06.095 [INFO] <./internal/admin/server.go:126> (*Server).run http server listening -14:47:06: daemon: make run-redis -bouncer-redis -docker run --rm -t \ - --name bouncer-redis \ - -v /home/wpetit/workspace/bouncer/data/redis:/data \ - -p 6379:6379 \ - redis:alpine3.17 \ - redis-server --save 60 1 --loglevel warning -1:C 23 Jun 2023 20:47:06.754 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo -1:C 23 Jun 2023 20:47:06.754 # Redis version=7.0.11, bits=64, commit=00000000, modified=0, pid=1, just started -1:C 23 Jun 2023 20:47:06.754 # Configuration loaded -1:M 23 Jun 2023 20:47:06.759 # Warning: Could not create server TCP listening socket ::*:6379: unable to bind socket, errno: 97 -1:M 23 Jun 2023 20:47:06.760 # Server initialized -1:M 23 Jun 2023 20:47:06.760 # WARNING Memory overcommit must be enabled! Without it, a background save or replication may fail under low memory condition. Being disabled, it can can also cause failures without low memory condition, see https://github.com/jemalloc/jemalloc/issues/1328. To fix this issue add 'vm.overcommit_memory = 1' to /etc/sysctl.conf and then reboot or run the command 'sysctl vm.overcommit_memory=1' for this to take effect -``` - -À ce stade, le serveur `bouncer-admin` écoute sur http://127.0.0.1:8081 et le serveur `bouncer-proxy` sur http://127.0.0.1:8080. - -L'outil [`modd`](https://github.com/cortesi/modd) est utilisé pour surveiller les modifications sur les sources et relancer automatiquement la compilation et les services en cas de changement. - ### Préparer la structure de base du nouveau layer Une implémetation d'un layer se compose majoritairement de 3 éléments: diff --git a/doc/fr/tutorials/getting-started-with-sources.md b/doc/fr/tutorials/getting-started-with-sources.md new file mode 100644 index 0000000..a9708f7 --- /dev/null +++ b/doc/fr/tutorials/getting-started-with-sources.md @@ -0,0 +1,125 @@ +# Démarrer avec les sources + +Dans ce tutoriel, nous verrons comment lancer un environnement de développement en local sur notre machine afin de travailler sur les sources de Bouncer. + +## Prérequis + +Les éléments suivants doivent être installés sur votre machine: + +- [Golang > 1.20](https://go.dev/) +- [Docker](https://www.docker.com/) +- [Git](https://git-scm.com/) +- [GNU Make](https://www.gnu.org/software/make/) + +Les ports suivants doivent être disponibles sur votre machine: + +- `8080` +- `8081` + +## Étapes + +1. Cloner le dépôt des sources du projet Bouncer + + ``` + git clone https://forge.cadoles.com/Cadoles/bouncer + ``` + +2. Se positionner dans le répertoire du projet + + ``` + cd bouncer + ``` + +3. Lancer le projet en mode "développement" + + ``` + make watch + ``` + +Si toutes les dépendances sont correctement installées et configurées sur votre machine, la console devrait afficher une série de messages pour ensuite s'arrêter sur quelque chose ressemblant à: + +``` +14:47:06: daemon: make run BOUNCER_CMD="--config config.yml server admin run" +2023-06-23 20:47:06.095 [INFO] <./internal/command/server/admin/run.go:42> RunCommand.func1 listening {"url": "http://127.0.0.1:8081"} +2023-06-23 20:47:06.095 [INFO] <./internal/admin/server.go:126> (*Server).run http server listening +14:47:06: daemon: make run-redis +bouncer-redis +docker run --rm -t \ + --name bouncer-redis \ + -v /home/wpetit/workspace/bouncer/data/redis:/data \ + -p 6379:6379 \ + redis:alpine3.17 \ + redis-server --save 60 1 --loglevel warning +1:C 23 Jun 2023 20:47:06.754 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo +1:C 23 Jun 2023 20:47:06.754 # Redis version=7.0.11, bits=64, commit=00000000, modified=0, pid=1, just started +1:C 23 Jun 2023 20:47:06.754 # Configuration loaded +1:M 23 Jun 2023 20:47:06.759 # Warning: Could not create server TCP listening socket ::*:6379: unable to bind socket, errno: 97 +1:M 23 Jun 2023 20:47:06.760 # Server initialized +1:M 23 Jun 2023 20:47:06.760 # WARNING Memory overcommit must be enabled! Without it, a background save or replication may fail under low memory condition. Being disabled, it can can also cause failures without low memory condition, see https://github.com/jemalloc/jemalloc/issues/1328. To fix this issue add 'vm.overcommit_memory = 1' to /etc/sysctl.conf and then reboot or run the command 'sysctl vm.overcommit_memory=1' for this to take effect +``` + +À ce stade, le serveur `bouncer-admin` écoute sur http://127.0.0.1:8081 et le serveur `bouncer-proxy` sur http://127.0.0.1:8080. + +> **Note** +> +> L'outil [`modd`](https://github.com/cortesi/modd) est utilisé pour surveiller les modifications sur les sources et relancer automatiquement la compilation et les services en cas de changement. + +## Commandes `make` utiles + +### `make watch` + +Surveiller les sources, compiler celles ci en cas de modifications et lancer les services `bouncer-proxy` et `bouncer-admin`. + +#### `make test` + +Exécuter les tests unitaires/d'intégration du projet. + +#### `make build` + +Compiler une version de développement du binaire `bouncer`. + +#### `make docker-build` + +Construire une image Docker pour Bouncer. + +Vous pouvez ensuite lancer l'image localement avec la commande: + +``` +docker run \ + -it --rm \ + reg.cadoles.com/cadoles/bouncer: \ + -p 8080:8080 \ + bouncer server proxy run +``` + +## Arborescence du projet + +```bash +. +├── bin # Répertoire de destination des binaires Go de développement +├── cmd # Package principal (main) du binaire Bouncer +├── data # Répertoire des données de développement (Redis) +├── dist # Répertoire de destination des archives/paquets pour la publication +├── doc # Répertoire de documentation du projet +├── internal # Source Go du projet +│   ├── admin +│   ├── auth +│   ├── chi +│   ├── client +│   ├── command +│   ├── config +│   ├── format +│   ├── imports +│   ├── jwk +│   ├── proxy +│   ├── schema +│   ├── setup +│   └── store +├── layers # Fichiers annexes liés aux layers (templates HTML) +│   └── queue +├── misc # Fichiers annexes +│   ├── jenkins # Fichiers liés au pipeline d'intégration continue Jenkins +│   ├── logo # Logo du projet +│   └── packaging # Fichiers liés à l'empaquetage des binaires +└── tools # Outils utilisés en développement +```