Publier le site vitrine¶
Vous êtes mainteneur·se de Kirexo et vous voulez que le site vitrine soit publié sur https://www.kirexo.app/ à chaque tag de release. Ce guide couvre la configuration manuelle à faire une seule fois (clé deploybase, variables CI, tags protégés, DNS chez OVH), la publication elle-même, le retour à une version précédente et la bascule vers le repli OVH.
La publication est faite par le job release:site-deploy, qui appelle castor site:deploy. Le fournisseur par défaut est deploybase (SiteBuilder::DEFAULT_PROVIDER, dans castor/src/Site/SiteBuilder.php) ; l'hébergement OVH lié au domaine sert de repli.
1. Prérequis¶
- Le rôle Maintainer sur le projet GitLab.
- L'accès au compte OVH qui gère le domaine
kirexo.app(zone DNS et redirections). - Un compte deploybase avec le rôle Admin sur l'organisation qui portera le projet (nécessaire pour créer une clé d'API).
2. Créer le projet et la clé deploybase¶
- Dans le tableau de bord deploybase, créez le projet du site vitrine, puis relevez son identifiant : c'est la valeur de
DEPLOYBASE_PROJECT_ID. - Ouvrez Settings → API keys et créez une clé.
La clé a la forme dbk_ suivi de 64 caractères hexadécimaux. Elle est affichée une seule fois : copiez-la immédiatement dans la variable CI de l'étape suivante. Elle n'expire pas et sa révocation est immédiate.
Ses droits sont ceux d'un membre (Member) : elle peut déployer et promouvoir, mais ne peut ni supprimer un projet ni gérer les domaines. C'est pour cette raison que le rattachement de www.kirexo.app (étape 5) se fait à la main dans le tableau de bord.
3. Déclarer les variables CI¶
Dans GitLab, ouvrez Settings → CI/CD → Variables et ajoutez :
| Variable | Visibilité | Protégée | Remarque |
|---|---|---|---|
DEPLOYBASE_API_KEY |
Masked and hidden | Oui | Format dbk_…, compatible avec le masquage. |
DEPLOYBASE_PROJECT_ID |
Visible (ou Masked) | Oui | Identifiant relevé à l'étape 2. |
OVH_FTP_HOST |
Visible | Oui | Repli OVH. |
OVH_FTP_USER |
Visible (ou Masked) | Oui | Repli OVH. |
OVH_FTP_PASSWORD |
Masked and hidden | Oui | Au moins 8 caractères, une seule ligne, sans espace. Décochez Expand variable reference. |
SITE_DEPLOY_PROVIDER |
Visible | Non | deploybase ou ovh. Absente : deploybase. |
OVH_FTP_REMOTE_DIR |
Visible | Non | Facultative, défaut www. |
Les variables OVH ne servent qu'en cas de bascule vers le repli : vous pouvez les déclarer plus tard.
SITE_DEPLOY_PROVIDER reste non protégée : castor site:build la lit aussi dans le job quality:site-check des merge requests, pour citer le bon hébergeur dans les mentions légales de la preview. Elle n'existe que côté CI : elle est absente de .env.
Une variable protégée n'existe que sur une ref protégée
GitLab ne transmet une variable Protected qu'aux pipelines des branches et des tags protégés. Sans l'étape 4, le job release:site-deploy d'un tag ne voit pas les secrets et sort en 2 en nommant la variable manquante.
Rôle de chaque variable : Variables CI/CD GitLab.
4. Protéger les tags semver¶
Le tag protégé est déjà en place sur le projet. Pour le vérifier, ou le recréer sur une autre instance :
- Ouvrez Settings → Repository → Protected tags, puis Add new.
- Saisissez le motif
*.*.*. GitLab n'accepte que le joker*, pas d'expression régulière. Les anciens tags horodatés (YYYYMMDDHHMM, sans point) ne sont pas concernés. - Dans Allowed to create, choisissez Developers + Maintainers.
- Validez.
Ce réglage permet au jeton GITLAB_TOKEN utilisé par le job tag:create de continuer à poser les tags. Effet secondaire : seuls ces rôles peuvent créer ou supprimer un tag X.Y.Z.
5. Rattacher www.kirexo.app¶
- Dans le tableau de bord deploybase, ajoutez le domaine
www.kirexo.appau projet. La clé d'API ne peut pas le faire. -
deploybase affiche deux enregistrements. Créez-les dans la zone DNS de
kirexo.appchez OVH :Type Nom Valeur CNAMEwwwla cible fournie par deploybase, de la forme ….b-cdn.net.TXT_deploybase-verify.wwwle jeton de vérification fourni par deploybase -
Attendez la vérification. Le certificat TLS est émis automatiquement ensuite ; d'ici là,
https://www.kirexo.app/répond par une erreur TLS.
Contrôle :
6. Rediriger le domaine nu¶
Créez chez OVH une redirection web permanente (301) de kirexo.app vers https://www.kirexo.app/.
Le domaine nu doit lui aussi avoir un certificat
Le TLD .app figure dans la liste HSTS preload des navigateurs : ils n'interrogent kirexo.app qu'en HTTPS. Une redirection servie seulement en HTTP n'est donc jamais atteinte, et le visiteur voit une erreur de certificat. La redirection de https://kirexo.app/ exige un certificat valide sur kirexo.app lui-même : choisissez chez OVH un mode de redirection qui en fournit un (redirection avec SSL, ou hébergement OVH lié au domaine avec son certificat et une règle de redirection), puis notez ici le mode retenu.
Contrôle : la réponse doit être une 301 dont l'en-tête location vaut https://www.kirexo.app/.
7. Publier¶
Posez un tag de release, de préférence avec le skill /creer-tag (cf. Créer un tag de release). Dans la pipeline du tag, le job release:site-deploy démarre après docker:build-dev et release:create, puis enchaîne castor site:build, castor site:check et castor site:deploy --expect-version="$CI_COMMIT_TAG".
Le déploiement se termine par une vérification : le script relit https://www.kirexo.app/ jusqu'à y trouver la version du tag. Le job n'est vert que si le domaine public sert bien ce build. Contrôle manuel :
site/data/release.json doit porter la version du tag
La version affichée par le site vient de site/data/release.json. Si ce fichier est absent ou porte une autre version, le build annonce dev (ou l'ancienne version) et castor site:deploy refuse de publier : Le build porte la version « dev » au lieu de « X.Y.Z », sortie 2. Le job est alors rouge alors que la release GitLab est déjà créée.
Avec le skill /creer-tag, le fichier est écrit par castor site:refresh, que prepare.sh appelle avec la version calculée, puis commité avec CHANGELOG.md sur la branche release-<version> mergée avant la pose du tag. Si vous posez le tag par une autre méthode (A, B ou C de Créer un tag de release), lancez d'abord castor site:refresh --name=<X.Y.Z> et faites merger le fichier produit sur main. En cas d'échec, corrigez, puis posez un nouveau tag.
Au premier tag, vérifiez aussi que le CDN applique les en-têtes de _headers :
Si l'en-tête est absent, voir le dépannage.
8. Simuler depuis le conteneur¶
Le déploiement réel ne tourne qu'en CI. Dans le conteneur de dev, castor site:deploy n'accepte que --dry-run, qui n'envoie rien et ne fait aucun appel réseau :
La sortie liste les fichiers qui seraient envoyés (_headers inclus, .htaccess exclu pour deploybase), leur taille, l'état ✓/✗ de chaque variable requise et l'URL de vérification. Les secrets n'existent pas dans le conteneur : la commande sort en 2, c'est le résultat attendu.
Pour voir une simulation complète qui sort en 0, passez des valeurs factices :
DEPLOYBASE_API_KEY=dbk_x DEPLOYBASE_PROJECT_ID=p castor site:deploy --dry-run
castor site:deploy --dry-run --provider=ovh # .htaccess inclus, _headers exclu
Sans --dry-run, la cible refuse et sort en 3, depuis le conteneur comme depuis l'hôte.
9. Revenir à une version précédente¶
Relancez le déploiement du tag précédent :
- Ouvrez Build → Pipelines et retrouvez la pipeline du tag précédent.
- Ouvrez son job
release:site-deployet cliquez sur Retry.
C'est un redéploiement complet : le job reconstruit le site de ce tag, le vérifie, le publie puis contrôle que https://www.kirexo.app/ sert bien cette version. Une promotion d'un ancien déploiement depuis le tableau de bord deploybase ne suffit pas : le domaine personnalisé ne suit pas une promotion.
Contrôle :
La version lue sur le domaine public est le seul garde-fou qui atteste ce qu'il sert.
10. Basculer vers le repli OVH¶
- Déclarez les variables
OVH_FTP_HOST,OVH_FTP_USERetOVH_FTP_PASSWORD(étape 3) si ce n'est pas déjà fait. - Passez
SITE_DEPLOY_PROVIDERàovh. - Dans la zone DNS, faites pointer
wwwvers l'hébergement OVH lié au domaine, avec l'enregistrement qu'OVH indique pour cet hébergement, à la place duCNAMEdeploybase. - Relancez
release:site-deploysur la pipeline du dernier tag (Retry).
Le dépôt passe par lftp mirror --reverse --delete en FTPS : .htaccess est envoyé, _headers exclu, et tout ce qui n'est plus dans le build est supprimé de OVH_FTP_REMOTE_DIR (y compris la page « site en construction » d'OVH). Le marqueur d'hébergeur des mentions légales suit, puisque castor site:build lit la même variable.
FTPS imposé
Le script impose le FTPS explicite (ftp:ssl-force true) pour que le mot de passe ne circule jamais en clair. Si l'hébergement OVH le refuse, lftp échoue et le job sort en 1. Ne retirez pas cette option pour faire passer le déploiement : un FTP en clair exposerait OVH_FTP_PASSWORD sur le réseau. Signalez le blocage dans le ticket du site vitrine.
Pour revenir à deploybase : remettez SITE_DEPLOY_PROVIDER à deploybase (ou supprimez-la), rétablissez le CNAME de l'étape 5 et relancez le job.
11. Dépannage¶
| Symptôme | Cause | Remède |
|---|---|---|
Sortie 3 |
castor site:deploy lancé sans --dry-run dans le conteneur de dev ou depuis l'hôte. |
Le déploiement réel ne tourne qu'en CI. Simuler avec --dry-run. |
Sortie 2, Variable(s) manquante(s) : DEPLOYBASE_API_KEY … |
Tag non protégé (variables Protected non transmises), ou variable absente. | Vérifier le motif *.*.* (étape 4) et les variables (étape 3), puis Retry. |
Sortie 2, Le build porte la version « … » au lieu de « X.Y.Z » |
site/data/release.json absent ou pas à jour pour ce tag. |
Voir l'encart de l'étape 7. |
Sortie 2, Fournisseur d'hébergement inconnu |
SITE_DEPLOY_PROVIDER ne vaut ni deploybase ni ovh. |
Corriger la variable. |
Sortie 2, OVH_FTP_REMOTE_DIR dangereux pour mirror --delete |
Valeur vide, /, ., .. ou contenant ... |
Mettre le dossier racine web de l'hébergement (www par défaut). |
Sortie 1, (HTTP 401) |
Clé deploybase révoquée ou erronée. | Créer une nouvelle clé (étape 2) et remplacer DEPLOYBASE_API_KEY. |
Sortie 1, (HTTP 402) |
Quota de l'offre gratuite deploybase atteint. | Consulter le quota dans le tableau de bord, ou basculer vers OVH (étape 10). |
Sortie 1, Envoi de … refusé (HTTP 409) |
Le contenu reçu par deploybase n'a pas le hash annoncé dans le manifeste. | Relancer le job (Retry) : il reconstruit le site et ouvre une nouvelle session. |
Sortie 1, Déploiement … en statut failed |
deploybase a rejeté le déploiement ; la catégorie d'erreur est affichée entre parenthèses. | Lire la catégorie, corriger, relancer. |
Sortie 1, www.kirexo.app ne sert pas X.Y.Z (lu : « … ») |
Le domaine sert encore l'ancienne version : cache CDN, CNAME pas encore propagé, ou CNAME qui pointe ailleurs. |
Vérifier dig +short CNAME www.kirexo.app, attendre la propagation, puis Retry. |
Sortie 1, lftp en échec. |
Identifiants FTP erronés ou FTPS refusé par l'hébergement. | Vérifier les variables OVH_FTP_* ; pour le FTPS, voir l'encart de l'étape 10. |
Pas d'en-tête Content-Security-Policy sur https://www.kirexo.app/ |
Le CDN n'applique pas _headers. |
Basculer vers OVH (étape 10), qui applique les mêmes en-têtes par .htaccess. |
Codes de sortie, options et ordre des contrôles : castor site:deploy.