# Versions et environnements

> La bibliothèque de thèmes de connexion propre à chaque environnement, le nommage des versions, leur application et les états affichés.

Un thème de connexion vit en deux temps : il entre d'abord dans la bibliothèque d'un environnement, puis il est appliqué dans ce même environnement. Chaque environnement a sa propre bibliothèque : tester une version sur dev ne touche ni à staging ni à la prod.

## Définition

- Une **version** est un thème de connexion empaqueté, figé. Elle ne se modifie pas : un changement produit une nouvelle version.
- La **bibliothèque** (**Thèmes de l'app** dans la console) regroupe les versions de l'application **dans un environnement**. Dev, staging et prod ont chacun la leur.
- **Appliquer** une version de la bibliothèque d'un environnement la rend active sur l'instance Keycloak de cet environnement, pour **tous les realms** de l'application : un realm par [réseau](/v1.0/glossaire#réseau).

Chaque environnement porte sa propre version appliquée. Dev peut servir la version de la semaine, pendant que prod sert celle du mois dernier.

## Une bibliothèque par environnement

Une version téléversée ou importée dans un environnement n'existe que dans celui-ci. Il n'existe ni copie ni promotion d'une bibliothèque vers une autre :

- pour utiliser le même thème en dev, en staging et en prod, la version est **ajoutée trois fois**, une fois dans chaque environnement ;
- une version ne peut être appliquée que dans un environnement dont la bibliothèque la contient ;
- supprimer une version ne la retire que de la bibliothèque de l'environnement choisi. La suppression est refusée tant que cette version est appliquée, ou en cours de publication, dans cet environnement.

Comme le nom d'une version dérive de son contenu (voir la section suivante), ajouter le même thème dans chaque environnement produit le même nom partout. C'est ce qui vous permet de vérifier que la prod sert exactement la version validée sur dev.

:::note[Reprise des bibliothèques existantes]
À la mise en production des bibliothèques par environnement, la bibliothèque existante de chaque application est reprise **en prod uniquement**. Celles de dev et de staging repartent vides. Les thèmes déjà appliqués en dev et en staging restent actifs ; pour les réappliquer, ou en appliquer un autre, la version doit d'abord être de nouveau ajoutée dans l'environnement concerné.
:::

## Le nom d'une version

Wakastart nomme la version à partir de son contenu, sous la forme `<application>-<WID>-<empreinte>` : par exemple `clinique-exemple-EXAPP1-a3f9c1d2`.

- La première partie dérive du nom de l'application, en 20 caractères au plus.
- Le WID rattache la version à votre application.
- L'empreinte est calculée sur le contenu du thème.

Vous ne choisissez jamais ce nom. Deux imports d'un contenu identique produisent la même version ; une seule modification d'un fichier en produit une nouvelle. Pour un import depuis GitHub, la console affiche aussi la **provenance** : dépôt, branche et commit importés.

## Les types de thème

Un thème de connexion peut contenir un ou plusieurs types, chacun dans son sous-dossier :

| Type | Ce qu'il habille |
|---|---|
| `login` | les pages de connexion, d'inscription et de mot de passe oublié |
| `email` | les e-mails envoyés par Keycloak (réinitialisation du mot de passe, vérification d'adresse) |
| `account` | la console de compte Keycloak de l'utilisateur |
| `admin` | la console d'administration Keycloak |
| `welcome` | la page d'accueil de l'instance |

L'application d'une version modifie le thème de connexion et le thème des e-mails des realms de l'application.

## Le cycle d'une publication

```mermaid
stateDiagram-v2
  state "Appliqué" as Applique
  [*] --> Disponible : version dans la bibliothèque de l'environnement
  Disponible --> Publication : appliquée sur un environnement
  state Publication {
    state "Déposé" as Depose
    state "Redémarrage" as Redemarrage
    state "Vérification" as Verification
    [*] --> Depose : thème déposé sur l'environnement
    Depose --> Redemarrage : Keycloak redémarre
    Redemarrage --> Verification : 3 vérifications consécutives
  }
  Publication --> Applique : thème appliqué à la page de login
  Applique --> Disponible : une autre version est appliquée
```

Quand Keycloak connaît déjà la version, elle s'applique immédiatement. Sinon, l'instance doit redémarrer pour la charger : comptez **1 à 3 minutes**. Pendant ce temps, la console affiche le suivi **Étapes de la publication** :

1. **Thème déposé sur l'environnement**
2. **Redémarrage de Keycloak (habituellement 1 à 3 min)**
3. **Thème chargé par Keycloak**, avec le compteur **vérification n/3**
4. **Thème appliqué à la page de login**

Le suivi indique aussi si la durée est normale :

| Durée écoulée | Message |
|---|---|
| moins de 5 minutes | « En cours, c'est normal. » |
| de 5 à 15 minutes | « Plus long que d'habitude. Rien à faire, l'application se fera automatiquement. » |
| plus de 15 minutes | « La publication semble bloquée. Contactez l'équipe Wakastart… » |

La publication continue même si vous quittez la page.

## Les états d'une version

| État affiché | Signification |
|---|---|
| **Appliqué** | Keycloak sert cette version sur l'environnement. |
| **Publication en cours** | La version est en cours d'application ; elle sera active dans 1 à 3 minutes. |
| **Disponible** | La version est déposée sur l'environnement, mais une autre est appliquée. |
| **Non publiée** | La version n'a jamais été déposée sur cet environnement. |
| **État inconnu** | Keycloak est injoignable : l'état ne peut pas être confirmé. |

## Rétention

Wakastart conserve, dans la bibliothèque de chaque environnement, les versions en service et les **deux versions les plus récentes**. Les plus anciennes sont supprimées automatiquement à chaque nouvel ajout. Une version appliquée ou en cours de publication n'est jamais supprimée.

## Pour aller plus loin

- [Préparer un thème de connexion](/v1.0/page-de-connexion/preparer-un-theme)
- [Publier un thème de connexion](/v1.0/page-de-connexion/publier-un-theme)
- [Référence du thème de connexion](/v1.0/page-de-connexion/reference)
