[Onboarding] Améliorer et documenter la génération des fichiers .env

.github/workflows/workflow-continuous-integration.yml

@@ -154,16 +154,6 @@ jobs:
       TAG: pr-${{ github.event.pull_request.number || github.event.number }}
       BROWSERS: "${{ github.base_ref == 'main' && 'chrome,firefox' || 'firefox' }}"
 
-  deploy-tests:
-    uses: ./.github/workflows/job-tests-deploy.yml
-    if: ${{ (needs.path-filter.outputs.apps != 'true' && needs.path-filter.outputs.packages != 'true' && needs.path-filter.outputs.ci != 'true') || (!github.event.pull_request.draft && github.base_ref == 'main') }}
-    needs:
-      - path-filter
-      - expose-vars
-      - build
-    with:
-      TAG: pr-${{ github.event.pull_request.number || github.event.number }}
-
   scan-vuln:
     uses: ./.github/workflows/job-scan.yml
     needs:

ENVIRONMENTS.md

@@ -0,0 +1,105 @@
+# Fichiers de configuration d'environnements
+
+Cette documentation a pour but de détailler tout ce qui concerne la gestion des configuration d'environnements (appelé couramment "fichiers .env").
+
+Comme vous aurez pu le constater, il y a beaucoup de choses à configurer pour un projet d'ampleur comme l'est la Console de CPiN, et il y a des cas d'usages très spécifiques qui seront décrits ici. Vous avez également la possibilité de composer votre propre manière de gérer vous variables d'environments en vous basant sur ce qui a été fait pour nous.
+
+## Cas d'usage supportés
+
+Avant de décrire dans le détail comment configurer les différents environments, il est important de rappeler les Cas d'Usage qui sont supportés par les scripts de CPiN:
+
+- **Développement totalement en local** : vous déployez l'entièreté de l'écosystème de `console`, sans considération d'un branchement à l'extérieur, et vous développez directement en mode "serve" sur `client`, `server`, un `plugin` en particulier, ou peut-être même une combinaison des trois.
+- **Développement conteneurisé en local** : vous déployez l'entièreté de l'écosystème de `console`, sans considération d'un branchement à l'extérieur, et même les composants fondamentaux de console (comme `client` et `server`) dans des conteneurs à l'aide d'images construites précédemment (en local, ou alors tirée depuis le registre de l'organisation CPiN)
+- **Développement conteneurisé hybride** : vous déployez localement seulement une partie de l'écosystème de `console` (`client` et/ou `server`, de manière à utiliser votre code local) et pour le reste (Base de données de `console`, `keycloak`, `gitlab`, les clusters applicatifs, etc.), vous vous branchez à un environnement existant (appelé `integ` pour `INTEGRATION`). Ce cas d'usage est très pratique pour tester votre code avec de "vraies données" d'un environnement fonctionnel (comme notre environnement interne `cpin-hp`)
+- Les cas de déploiements finaux du système complet, qui sont eux adressé par un chart Helm stocké dans [le dépôt `helm-charts`](https://github.com/cloud-pi-native/helm-charts)
+
+Maintenant que ces définitions sont établies, passons à la configuration pour chacun des cas d'usage
+
+## Considérations communes à tous les cas
+
+Le mode de fonctionnement de la configuration des environnements est assez classique : les applications `client` et `server` ont besoin d'avoir certaines variables d'environnements définies.
+
+Le mécanisme de surcharge des différentes configurations fonctionne de cette manière :
+
+```
+->: «surcharge»
+
+var d'env settée explicitement -> fichier .env.docker (si contexte docker) -> fichier .env.integ (si INTEGRATION=true) -> fichier .env
+```
+
+## Prégénération des fichiers .env, .env.docker, et .env.integ
+
+Un script permet de copier facilement les fichiers `.env*-example` en leur équivalent `.env*`: [`./ci/scripts/init-env.sh`](./ci/scripts/init-env.sh).
+
+> Il faut ensuite remplir ces fichiers, car ils ne sont là que simplement copiés avec les valeurs par défaut
+
+## Configuration pour le développement entièrement en local
+
+Docker Compose utilisé : [`docker/docker-compose.local.yml`](docker/docker-compose.local.yml) (infrastructure uniquement : Keycloak, PostgreSQL, pgAdmin, OpenCDS mock)
+
+Fichiers utilisés :
+
+- `apps/client/.env`
+- `apps/server/.env`
+
+Les valeurs par défaut, disponibles dans les fichiers `.env-example`, sont suffisantes dans 99% des cas. Cela dit, c'est un cas d'usage assez restreint car la console se reposant sur quelques composants externes comme une base de données PostgreSQL ou un serveur IAM comme `keycloak`, il faut configurer manuellement les `.env` pour pointer sur les bonnes URLs, etc. Pas infaisable, mais pas très pratique au quotidien, hors des cas simple de build des applications.
+
+**Commandes de lancement :**
+
+```bash
+# Lance l'infrastructure (Keycloak, PostgreSQL, pgAdmin, OpenCDS mock)
+pnpm dev
+
+# Puis dans d'autres terminaux, lancer le serveur et le client manuellement :
+pnpm --filter server run dev
+pnpm --filter client run dev
+```
+
+## Configuration pour le développement conteneurisé en local
+
+Docker Compose utilisé : [`docker/docker-compose.dev.yml`](docker/docker-compose.dev.yml) (tout conteneurisé avec Docker Compose Watch)
+
+Fichiers utilisés :
+
+- `apps/client/.env`
+- `apps/client/.env.docker`
+- `apps/server/.env`
+- `apps/server/.env.docker`
+
+Cette configuration est déjà plus intéressante, car elle s'appuie sur les conteneurs définis dans [ce docker-compose](docker/docker-compose.dev.yml), qui lance notamment une base de données PostreSQL (ainsi qu'un `pgadmin`), et un serveur Keycloak préchargé avec un royaume qui contient un jeu de données. Le docker-compose contient des instructions `develop` qui permettent soit de synchroniser certains fichiers, soit de carrément reconstruire l'image et de relancer le service concerné. De cette manière vous pouvez développer en laissant les conteneurs tourner. C'est un peu moins performant qu'un travail totalement en local, mais ça a le mérite d'être plus proche du déploiement cible.
+
+**Commande de lancement :**
+
+```bash
+# Lance l'ensemble des conteneurs (client, server, keycloak, postgres, pgadmin, opencds mock)
+# avec Docker Compose Watch pour la synchronisation du code
+pnpm docker:dev
+```
+
+## Configuration pour le développement hybride avec un environnement d'intégration existant
+
+Docker Compose utilisé : [`docker/docker-compose.integ.yml`](docker/docker-compose.integ.yml) (sans Keycloak, branché sur l'environnement d'intégration distant)
+
+Fichiers utilisés :
+
+- `apps/client/.env`
+- `apps/client/.env.docker`
+- `apps/client/.env.integ`
+- `apps/server/.env`
+- `apps/server/.env.docker`
+- `apps/server/.env.integ`
+
+Cette configuration est une itération de la précédente. Dans ce cas d'usage le Keycloak n'est pas créé en tant que conteneur, car on est supposé se brancher sur l'environnement d'intégration défini dans les fichiers `.env.integ`. Le contenu de ces fichiers (en particulier celui de `apps/server`) est donc clé.
+
+**Commandes de lancement :**
+
+```bash
+# Option 1 : Tout conteneurisé, branché sur l'environnement d'intégration
+pnpm docker:integ
+
+# Option 2 : Seulement l'infra en Docker (postgres, pgadmin), server et client en local avec mode integ
+pnpm integ
+# Puis dans d'autres terminaux :
+pnpm --filter server run dev
+pnpm --filter client run dev
+```

README.md

@@ -1,9 +1,9 @@
 # Console Cloud π Native
 
-La console Cloud π Native est une application web ayant pour but de piloter des services web dans un cluster Kubernetes afin de fournir une platefome cloud qui accompagne les produits numériques lors de toutes les phases de leur cycle de vie.
+La console Cloud π Native est une application web ayant pour but de piloter des services dans un cluster Kubernetes afin de fournir une plateforme cloud qui accompagne les produits numériques lors de toutes les phases de leur cycle de vie.
 
-Cette console offre une interface unifiée vers un ensemble de services tout en garantissant une cohérence globale du système avec la création automatique d'un certain nombre de ressources comme par exemple les comptes d'accès, les robots ou encore des ressources Kubernetes.
-En addition du provisionnement automatique, elle garantit aussi le contrôle d'accès aux ressources du projet à l'aide d'une gestion d'équipe, de permissions, de quotas, etc...
+Cette console offre une interface unifiée vers un ensemble de services tout en garantissant une cohérence globale du système avec la création automatique d'un certain nombre de ressources comme les comptes d'accès, les robots ou encore des ressources Kubernetes.
+En addition du provisionnement automatique, elle garantit aussi le contrôle d'accès aux ressources du projet à l'aide d'une gestion d'équipe, de permissions, de quotas, etc.
 
 <img src="./misc/images/projects.png" width="30%"></img> <img src="./misc/images/repositories.png" width="30%"></img> <img src="./misc/images/environments.png" width="30%"></img> <img src="./misc/images/services.png" width="30%"></img> <img src="./misc/images/members.png" width="30%"></img> <img src="./misc/images/status.png" width="30%"></img>
 
@@ -39,7 +39,7 @@ Afin de pouvoir démarrer l'application, il vous faudra également récupérer (
 - `apps/server/.env.docker`
 - `apps/server/.env.integ`
 
-En vous basant sur une infrastructure distante (comme un environnement d'intégration, cf. la section suivante) ou votre infrastructure locale si vous préférez tout héberger en local.
+Si vous ne les avez pas déjà, référez-vous à [./ENVIRONMENTS.md](./ENVIRONMENTS.md) qui est la documentation consacrée au sujet.
 
 ### Lancement rapide utilisant l'application en local et les services sur un environnement distant
 
@@ -68,16 +68,6 @@ Si vous voulez une vue plus approfondie du lancement de l'application, vous pouv
 Ce projet est construit avec [NodeJS](https://nodejs.org/), [VueJS](https://vuejs.org/), [Postgres](https://www.postgresql.org/) et [Keycloak](https://www.keycloak.org/).
 Le serveur et le client sont livrés sous forme d'images [Docker](https://www.docker.com/) et sont déployées à l'aide de [Helm](https://helm.sh/) dans [Kubernetes](https://kubernetes.io/).
 
-### Liste des services kubernetes
-
-| Nom du service | Github project                                                                  | Role                                      | Déployé avec le Helm Chart de production |
-| -------------- | ------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------- |
-| __client__     | [VueJS](https://github.com/vuejs/vue) / [Nginx](https://github.com/nginx/nginx) | Interface graphique de l'application      | Oui                                      |
-| __server__     | [NodeJS](https://github.com/nodejs/node)                                        | API de l'application                      | Oui                                      |
-| __postgres__   | [Postgres](https://github.com/postgres/postgres)                                | Base de données de l'application          | Oui                                      |
-| __keycloak__   | [Keycloak](https://github.com/keycloak/keycloak)                                | Gestionnaire d'authentification / d'accès | -                                        |
-| __pgadmin__    | [Pgadmin](https://github.com/pgadmin-org/pgadmin4)                              | Interface d'administration de Postgres    | -                                        |
-
 ### API
 
 Le serveur est construit selon une architecture __core / plugins__ pour favoriser l'évolutivité et l'ajout de nouvelles fonctionnalités / la gestion de nouveaux services. Pour ce faire, les plugins s'enregistrent auprès de différents `hooks` (qui suivent le cycle de vie d'un projet au sein de l'application), ces derniers seront déclenchés par les contrôleurs de l'application.
@@ -100,7 +90,7 @@ Plusieurs plugins sont nativement enregistrés auprès du serveur pour assurer l
 
 ## Développement
 
-Le développement s'effectue à l'aide de Docker *(le client et le serveur peuvent tourner en local ou dans Docker)* ou encore directement dans un cluster Kubernetes à l'aide de Kind, un outil permettant de créer des noeuds Kubernetes dans des conteneurs Docker.
+Le développement s'effectue à l'aide de Docker *(le client et le serveur peuvent tourner en local ou dans Docker)*.
 
 ### Construire l'application
 
@@ -158,30 +148,7 @@ pnpm run docker:dev:clean
 pnpm run docker:dev:delete
 ```
 
-> Pour lancer le debugger nodejs sur le serveur, dans les fichiers `docker-compose` remplacer la directive  `command: ["dev"]` par `command: ["debug"]`.
-
-__Lancement de la stack complète dans un cluster Kubernetes :__
-
-Nous recommandons l'utilisation de [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) ("Kubernetes in Docker") pour créer un cluster k8s en local.
-
-Vous aurez également besoin d'installer les outils suivants pour des déploiements avancés, plus proche d'une exploitation en mode "Production" :
-
-- [Kubectl](https://kubernetes.io/fr/docs/tasks/tools/install-kubectl/) Interface en ligne de commande pour Kubernetes
-- [Helm](https://helm.sh/docs/intro/install/) Gestionnaire de ressources Kubernetes (manifestes YAML) sous la forme de "charts"
-
-```shell
-# Initialiser Kind (ajoute des noms de domaines dans /etc/hosts, le mot de passe sera demandé)
-pnpm run kube:init
-
-# Lancer l'application
-pnpm run kube:dev
-
-# Supprimer les ressources applicatives sans supprimer le cluster Kind
-pnpm run kube:clean
-
-# Supprimer entièrement le cluster et ses ressources
-pnpm run kube:delete
-```
+> Pour lancer le debugger Node.js sur le serveur, dans les fichiers `docker-compose` remplacer la directive  `command: ["dev"]` par `command: ["debug"]`.
 
 #### Intégration
 
@@ -220,22 +187,6 @@ pnpm run docker:integ:clean
 pnpm run docker:integ:delete
 ```
 
-__Lancement de la stack complète dans un cluster Kubernetes :__
-
-```shell
-# Initialiser Kind (ajoute des noms de domaines dans /etc/hosts, le mot de passe sera demandé)
-pnpm run kube:init
-
-# Lancer l'application en mode développement
-pnpm run kube:integ
-
-# Supprimer les ressources applicatives sans supprimer le cluster Kind
-pnpm run kube:clean
-
-# Supprimer entièrement le cluster et ses ressources
-pnpm run kube:delete
-```
-
 #### Utilitaires
 
 Les commandes utilitaires de l'application :
@@ -262,14 +213,14 @@ Se référer à la [documentation concernée](./playwright/README.md).
 
 ### Accès aux services
 
-Les services sont disponibles via des noms de domaines ajoutés dans le fichier `/etc/hosts` de votre système, l'ajout des domaines se fait automatiquement lors de la commande `pnpm run kube:init`.
+Les services sont disponibles via les ports suivants :
 
-| Service                                        | Url (kubernetes)               | Url (local/docker)      |
-| ---------------------------------------------- | ------------------------------ | ----------------------- |
-| Interface graphique *- (client)*               | <http://console.dso.local>     | <http://localhost:8080> |
-| Serveur *- (api)*                              | <http://console.dso.local/api> | <http://localhost:4000> |
-| Interface d'administration de base de données  | <http://pgadmin.dso.local>     | <http://localhost:8081> |
-| Interface d'administration du serveur keycloak | <http://keycloak.dso.local>    | <http://localhost:8090> |
+| Service                                        | Url (local/docker)      |
+| ---------------------------------------------- | ----------------------- |
+| Interface graphique *- (client)*               | <http://localhost:8080> |
+| Serveur *- (api)*                              | <http://localhost:4000> |
+| Interface d'administration de base de données  | <http://localhost:8081> |
+| Interface d'administration du serveur keycloak | <http://localhost:8090> |
 
 *__Notes:__ ⚠ Il est possible que le navigateur utilisé (particulièrement Brave ou Firefox) bloque les cookies utilisés entre le frontend et keycloak, il est nécessaire de désactiver les protections de ce type dans votre navigateur (ex: Brave Shield).*
 
@@ -294,23 +245,6 @@ __Local / Docker:__
 
 Les variables d'environnements sont gérées localement via des fichiers `.env` (local) / `.env.docker` (docker) dans les dossiers `./apps/server` et `./apps/client`, aux précédents fichiers s'ajoute un fichier `.env.integ` utilisé pour le mode intégration (local et docker).
 
-__Kubernetes :__
-
-Un chart Helm utilitaire est installé pour déployer les services qui ne sont pas inclus dans le chart de la console :
-
-- Pgadmin
-
-> Ces services sont personnalisables [ici](./ci/helm-utils/values.yaml).
-
-Différents fichiers de `values.yml` sont disponibles pour personnaliser le déploiement de l'application dans le cluster Kind:
-
-- Le fichier [./ci/kind/env/dso-values.yaml](./ci/kind/env/dso-values.yaml) contient les variables de base l'application.
-- Le fichier [./ci/kind/env/dso-values-dev.yaml](./ci/kind/env/dso-values-dev.yaml) contient les variables de l'application pour le mode développement.
-- Le fichier [./ci/kind/env/dso-values-int-example.yaml](./ci/kind/env/dso-values-int-example.yaml) contient les variables de l'application pour le mode intégration.
-
-> *__Notes:__*
-> - *Les values du chart de la console sont disponibles [ici](https://github.com/cloud-pi-native/helm-charts/tree/main/charts/dso-console).*
-
 ### Base de données
 
 Pour faciliter les opérations de migrations de base de données via [Prisma](https://www.prisma.io/), un script est disponible :

apps/client/.env-example

@@ -1,10 +1,20 @@
+# Mode d'exécution Node.js (development | production | test)
 NODE_ENV=development
+# Hôte du serveur backend vers lequel le client proxifie les appels API
 SERVER_HOST=localhost
+# Port d'écoute du serveur backend
 SERVER_PORT=4000
+# Domaine (host:port) du serveur Keycloak pour l'authentification
 KEYCLOAK_DOMAIN=localhost:8090
+# Nom du royaume Keycloak utilisé par la console
 KEYCLOAK_REALM=cloud-pi-native
+# Protocole de communication avec Keycloak (http | https)
 KEYCLOAK_PROTOCOL=http
+# Identifiant du client Keycloak côté frontend
 KEYCLOAK_CLIENT_ID=dso-console-frontend
+# URL de redirection après authentification Keycloak
 KEYCLOAK_REDIRECT_URI=http://localhost:8080
+# Active/désactive le module OpenCDS (true | false)
 OPENCDS_ENABLED=false
+# Adresse e-mail de contact affichée dans l'interface
 CONTACT_EMAIL=cloudpinative-relations@interieur.gouv.fr

apps/client/.env.docker-example

@@ -1,10 +1,20 @@
+# Indique que l'application tourne dans un conteneur Docker
 DOCKER=true
+# Mode d'exécution Node.js (development | production | test)
 NODE_ENV=development
+# Hôte du serveur backend (nom du service Docker Compose)
 SERVER_HOST=server
+# Port d'écoute du serveur backend dans le réseau Docker
 SERVER_PORT=8080
+# Domaine (host:port) du serveur Keycloak pour l'authentification
 KEYCLOAK_DOMAIN=localhost:8090
+# Nom du royaume Keycloak utilisé par la console
 KEYCLOAK_REALM=cloud-pi-native
+# Protocole de communication avec Keycloak (http | https)
 KEYCLOAK_PROTOCOL=http
+# Identifiant du client Keycloak côté frontend
 KEYCLOAK_CLIENT_ID=dso-console-frontend
+# URL de redirection après authentification Keycloak
 KEYCLOAK_REDIRECT_URI=http://localhost:8080
+# Adresse e-mail de contact affichée dans l'interface
 CONTACT_EMAIL=cloudpinative-relations@interieur.gouv.fr