# Environnements

> Développement, staging, production : où tourne votre application, sur quelle instance Keycloak se connectent ses utilisateurs, et ce qui change.

Un [environnement](/v1.0/glossaire#environnement) est un lieu d'exécution de votre application : ses services, ses bases, ses buckets et ses URLs y ont leurs propres instances. Son type, développement, staging ou production, décide aussi de l'instance Keycloak sur laquelle ses utilisateurs se connectent.

## Définition

Chaque environnement a un **type** choisi à la création et qui ne change plus :

| Type (console) | Code | Instance Keycloak | Usage |
|---|---|---|---|
| **Development** | `dev` | `https://auth-dev.wakastart.app` | développer et tester sans risque |
| **Staging** | `staging` | `https://auth-staging.wakastart.app` | recetter une version avant la production |
| **Production** | `prod` | `https://auth.wakastart.app` | servir vos utilisateurs |

```mermaid
flowchart LR
  subgraph APP["Application EXAPP1"]
    DEV["Environnement dev<br/>app.dev.monapp.…"]
    STG["Environnement staging<br/>app.staging.monapp.…"]
    PRD["Environnement prod<br/>app.monapp.…"]
  end
  DEV --> KD["Keycloak dev<br/>auth-dev.wakastart.app"]
  STG --> KS["Keycloak staging<br/>auth-staging.wakastart.app"]
  PRD --> KP["Keycloak prod<br/>auth.wakastart.app"]
  KD & KS & KP --- R["Realm du réseau<br/>présent sur les trois instances"]
```

Une application peut avoir plusieurs environnements du même type, par exemple deux environnements de développement pour deux équipes. Chacun a son **nom de l'instance**, un **nom court** (12 caractères au plus) et un identifiant dérivé, de la forme `<nom court>-<type>`.

## Pourquoi ça existe

Une modification doit pouvoir être essayée sans toucher aux utilisateurs réels, puis promue. Les environnements séparent donc tout ce qui peut casser : les conteneurs, les données, les secrets, et jusqu'aux comptes des utilisateurs. Un mot de passe de test n'ouvre jamais la production, et un droit ajouté en développement n'existe pas en production tant qu'il n'y a pas été promu.

## Comment ça marche

### Côté hébergement

- **Ses instances.** Chaque environnement reçoit ses services déployés, ses bases, ses buckets et ses routes, à partir des définitions de l'architecture (voir [Définitions et instances](/v1.0/concepts/definitions-et-instances)).
- **Sa référence Git.** Il suit une branche, un tag ou un commit. Sur une branche, il peut construire à chaque push (**Build automatique**) et déployer chaque build réussi (**Auto-deploy on new build**).
- **Son préfixe d'URL.** Le préfixe s'insère dans les URLs publiques : `api.staging.monapp.<domaine>` en staging, `api.monapp.<domaine>` sans préfixe. Une application n'a qu'un seul environnement sans préfixe, en général la production.
- **Sa configuration.** Variables et secrets sont propres à l'environnement : la même variable attendue reçoit une valeur différente en dev et en prod.

### Côté identité

- **Une instance Keycloak par type.** Le realm de chaque réseau existe sur les trois instances.
- **Un référentiel d'utilisateurs par environnement.** Une fiche utilisateur appartient à un seul environnement : identité, WID, statut, profil, préférences et compte Keycloak lui sont propres. La même adresse peut avoir une fiche en dev, en staging et en prod, trois fiches indépendantes. Rien n'est copié ni promu d'un environnement à l'autre : on crée ou on invite la personne dans l'environnement voulu. Voir [Comptes et environnements](/v1.0/utilisateurs/comptes-et-environnements).
- **Des droits communs, une matrice par environnement.** La liste des droits et les profils (avec leur WID) existent dans les trois environnements. Seule la **Matrice** profils × droits est propre à chacun, et elle se règle séparément, sans promotion.
- **Des invitations dans l'environnement de l'inviteur.** Une invitation appartient à l'environnement de celui qui l'envoie ; l'invité reçoit une fiche et un compte sur l'instance correspondante.
- **Des clés API par environnement.** Une clé API appartient à un environnement, et ses droits se lisent dans la matrice de cet environnement.
- **Des réglages par environnement.** La bibliothèque de thèmes de la page de connexion, le thème actif et la configuration d'envoi des e-mails se règlent dans chaque environnement, sans propagation.
- **Des hôtes IAM par environnement.** Chaque nom d'hôte de votre front est rattaché à un type d'environnement. C'est ce rattachement qui permet à [Discovery](/v1.0/concepts/discovery) de renvoyer la bonne instance.

### L'environnement est déduit, jamais fourni

Pour toutes les opérations sur les utilisateurs, les profils, les invitations et les clés, Wakastart déduit l'environnement de l'appelant : le claim `wenv` du jeton d'un utilisateur, l'environnement d'une clé API, ou, pour Discovery, l'hôte IAM qui correspond au nom d'hôte envoyé. Les paramètres d'environnement envoyés à l'API publique sont refusés en `400`, et un appelant dont l'environnement ne peut pas être déduit est refusé : il n'y a pas de repli sur la production. Conséquence directe : chaque build de votre front doit appeler Discovery avec son propre nom d'hôte, sinon un build de dev se connecte sur les fiches de production.

### `KEYCLOAK_URL`, une valeur par environnement

Quand votre code a besoin de l'adresse de Keycloak, il la lit dans sa variable `KEYCLOAK_URL`, jamais dans une constante. Déclarez `KEYCLOAK_URL` comme variable attendue de votre service, puis donnez-lui dans l'onglet **Configuration** de chaque environnement la valeur de l'instance correspondante. Le même build fonctionne alors partout. La réponse de Discovery contient déjà la bonne instance : `KEYCLOAK_URL` sert aux cas où votre code construit lui-même une adresse Keycloak, comme la connexion par e-mail.

### Les gestes réservés à la production

Pour un environnement de type Production, chaque action d'hébergement demande, en plus du droit de l'action, le droit d'accès à la production. Le profil Infra le porte ; le profil Développeur, non.

## Exemples

**Une équipe de quatre développeurs.** L'application a trois environnements : `dev` suit la branche `develop` avec build et déploiement automatiques, `staging` suit `main`, `prod` suit des tags. Les testeurs ont un compte sur l'instance staging ; les clients n'existent que sur l'instance production.

**Une agence avec une recette par client.** L'agence crée un environnement de staging par grand client, chacun avec son préfixe (`recette-a`, `recette-b`). Le même code est déployé partout ; seules les variables changent.

## Ce qui change d'un environnement à l'autre

| Élément | Partagé par tous les environnements | Propre à chaque environnement |
|---|---|---|
| Architecture (services, bases, buckets, URLs déclarés) | ✔ | |
| Images construites | ✔ | |
| Services déployés, bases, buckets, routes | | ✔ |
| Variables et secrets | | ✔ |
| Réseaux, clients, propriétaires | ✔ | |
| Liste des droits de l'application, profils et leur WID | ✔ | |
| Instance Keycloak, fiches et comptes utilisateurs | | ✔ |
| Matrice profils × droits | | ✔ |
| Profils attribués aux utilisateurs | | ✔ |
| Clés API et leurs droits | | ✔ |
| Thèmes de la page de connexion, envoi des e-mails | | ✔ |

## Pour aller plus loin

- [Applications et environnements](/v1.0/applications) : créer, configurer et supprimer un environnement.
- [Définitions et instances](/v1.0/concepts/definitions-et-instances) : comment l'architecture devient des ressources.
- [Discovery](/v1.0/concepts/discovery) : comment le nom d'hôte désigne l'environnement.
- [Variables et secrets](/v1.0/variables-et-secrets) : fournir `KEYCLOAK_URL` et le reste de la configuration.
