4NK_env/docs/lecoffre-front/ci.md

### CI/CD — Fonctionnement observé et architecture de déploiement

Cette documentation décrit le pipeline CI/CD tel qu’il peut être déduit des artefacts présents dans le dépôt : `Dockerfile`, `package.json`, et les manifestes Kubernetes rendus dans `temp.yaml`. Aucune configuration de pipeline explicite n’est présente dans le dépôt (pas de `.gitea/`, `.github/workflows/`, `.gitlab-ci.yml`, `.drone.yml`). Le flux ci-dessous s’appuie donc sur ces éléments pour décrire le fonctionnement attendu.

### Portée

- **Build applicatif**: Next.js (Node 19-alpine) avec dépendance privée `le-coffre-resources` via SSH.
- **Image Docker**: construction multi-étapes, publication vers le registre Docker hébergé sur `git.4nkweb.com` (accès via clés SSH).
- **Déploiement Kubernetes**: namespace `lecoffre`, intégration Vault Agent pour l’injection d’ENV, `ExternalSecret` pour le secret de pull Docker, `Ingress` TLS via cert-manager, ressources de `Deployment`/`Service`.
 - **Variables front ajoutées**: `NEXT_PUBLIC_4NK_IFRAME_URL` pour distinguer l’URL complète de l’iframe de son origin (`NEXT_PUBLIC_4NK_URL`).

### Chaîne de build

- **Dépendances**
  - `package.json` indique Next.js 14, TypeScript 4.9, ESLint 8.36, etc.
  - La dépendance privée `le-coffre-resources` est récupérée depuis `git.4nkweb.com` via SSH (`git+ssh`).

- **Dockerfile** (multi-étapes, Node 19-alpine)
  - Étape `deps`: installation des dépendances avec `npm install` en utilisant BuildKit et le forward d’agent SSH pour accéder au dépôt privé.
  - Étape `development`: copie du code, exécution sous un utilisateur non-root, commande par défaut `npm run dev` (pour le développement local). Pour la prod, l’image utilisée en cluster exécute `npm run start` (cf. manifeste).

- **Build Next.js**
  - Script `build`: `NEXT_TELEMETRY_DISABLED=1 next build --no-lint`
  - Script `start`: `next start`
  - Le lint n’est pas bloquant au build (flag `--no-lint`).

### Image, registre et version

- **Registre**: Docker registry interne sur `git.4nkweb.com`.
- **Tagging**: contrôlé par la CI via le message de commit (préfixe `ci: docker_tag=<valeur>`), sinon fallback `dev-test`. La branche peut être utilisée comme tag par défaut selon la CI. Recommandation: utiliser un tag non versionné `ext`.

### Déploiement Kubernetes (extrait de `temp.yaml`)

- **Namespace**: `lecoffre`
- **ServiceAccount**: `lecoffre-front-sa` avec `Secret` token associé.
- **ExternalSecret**: création de `imagePullSecret` à partir de Vault via `external-secrets.io` en lisant `secret/data/lecoffre-front-stg/config/dockerpullsecret` (clé `.dockerconfigjson`).
- **Deployment**: `apps/v1` nommé `lecoffre-front` avec:
  - `image`: `rg.fr-par.scw.cloud/lecoffre/front:v0.1.9`
  - `imagePullPolicy`: `Always`
  - `resources`: `requests` (cpu 200m, ram 1Gi), `limits` (ram 2Gi)
  - **Vault Agent Injector**: annotations pour injecter des variables d’environnement depuis `secret/data/lecoffre-front-stg/config/envs` en exportant chaque paire `clé=valeur` dans `/vault/secrets/envs`.
  - **Commande de démarrage**: `['sh','-c', '. /vault/secrets/envs && npm run start']`

- **Service**: type ClusterIP exposant le port 80 vers le `targetPort` 3000 du conteneur Next.js.

- **Ingress**: classe `nginx` avec TLS géré par `cert-manager` (ClusterIssuer `letsencrypt-prod`) pour `app.stg.lecoffre.smart-chain.fr`.

### Flux CI/CD attendu (déduit)

1. **Checkout + préparation**
   - Récupération du code et configuration de l’agent SSH (accès à `git.4nkweb.com`).

2. **Installation des dépendances**
   - `npm install` avec BuildKit (`--mount=type=ssh`) pour la dépendance privée.

3. **Build applicatif**
   - `npm run build` (désactive la télémétrie et le lint bloquant).

4. **Construction de l’image**
   - Réalisée par la CI (BuildKit + forward d’agent SSH) après un `git push` sur `git.4nkweb.com`.
   - Taggage déterminé par le message de commit et/ou la branche.

5. **Push au registre**
   - Réalisé par la CI vers le registre `git.4nkweb.com`.

6. **Déploiement Kubernetes**
   - Application des manifestes (ou rendu Helm) dans le namespace `lecoffre`.
   - Les secrets de pull sont fournis via `ExternalSecret` connecté à Vault.
   - Au runtime, Vault Agent injecte les variables d’environnement nécessaires avant `npm run start`.

### Sécurité et secrets

- **Build**: le forward d’agent SSH évite d’écrire la clé privée dans l’image.
- **Runtime**: aucune variable sensible n’est stockée dans l’image; elles sont injectées à l’exécution par Vault.
- **Pull de l’image**: la config Docker (`.dockerconfigjson`) est fournie par `ExternalSecret` à partir de Vault.

### Secrets CI requis

- **USER**: identifiant du compte CI sur `git.4nkweb.com` disposant des droits requis (lecture repo, push d’image vers le registry).
- **TOKEN**: jeton d’accès (API/registry) associé à `USER`. Utilisé par la CI pour:
  - Authentifier les actions git/HTTP vers `git.4nkweb.com` (si nécessaire)
  - Authentifier le `docker login` vers le registry Gitea si la CI ne repose pas sur des credentials intégrés.

Notes:
- Préférer des tokens à portée restreinte, régénérés périodiquement.
- Stocker `USER` et `TOKEN` dans le gestionnaire de secrets CI et ne jamais les committer.

### Points à confirmer

- Outil CI utilisé (Gitea Actions, Woodpecker/Drone, GitLab CI, autre) et fichiers de pipeline hébergés ailleurs.
- Règles de nommage des tags d’image et gouvernance de version (`vX.Y.Z`, tags d’environnement).
- Stratégie de déploiement (Helm chart source exact, commandes d’apply, gestion multi-env: dev/stg/prod).
- Politique de lint/test avant build (actuellement `--no-lint` au build Next.js).
 - Passage des variables `NEXT_PUBLIC_4NK_URL` et `NEXT_PUBLIC_4NK_IFRAME_URL` à l’étape de build Docker (ARG/ENV) dans la CI.

### Bonnes pratiques recommandées

- Activer un job de lint et tests unitaires avant build d’image.
- Signer les images (Cosign) et activer des scans SCA/Container.
- Gérer explicitement les tags et le changelog en CI.
- Déployer via Helm chart versionné, avec valeurs par environnement (`values.{env}.yaml`).

### Validation de l'image Docker « ext » (intégration des variables)

- Objectif: vérifier que les variables `NEXT_PUBLIC_*` sont bien injectées dans l'image construite par la CI.
- Commande:

```
docker pull git.4nkweb.com/4nk/lecoffre-front:ext
docker run --rm git.4nkweb.com/4nk/lecoffre-front:ext sh -lc "env | grep '^NEXT_PUBLIC_' | sort"
```

- Attendus clés:
  - `NEXT_PUBLIC_4NK_URL` et `NEXT_PUBLIC_4NK_IFRAME_URL` doivent être définies.
  - Les URLs API (`NEXT_PUBLIC_API_URL`, `NEXT_PUBLIC_BACK_API_*`) doivent refléter l'environnement.