Aller au contenu

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

  1. 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.
  2. 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 :

  1. Ouvrez Settings → Repository → Protected tags, puis Add new.
  2. 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.
  3. Dans Allowed to create, choisissez Developers + Maintainers.
  4. 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

  1. Dans le tableau de bord deploybase, ajoutez le domaine www.kirexo.app au projet. La clé d'API ne peut pas le faire.
  2. deploybase affiche deux enregistrements. Créez-les dans la zone DNS de kirexo.app chez OVH :

    Type Nom Valeur
    CNAME www la cible fournie par deploybase, de la forme ….b-cdn.net.
    TXT _deploybase-verify.www le jeton de vérification fourni par deploybase
  3. 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 :

dig +short CNAME www.kirexo.app
curl -sI https://www.kirexo.app/

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/.

curl -sI https://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 :

curl -s https://www.kirexo.app/ | grep kirexo:version

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 :

curl -sI https://www.kirexo.app/ | grep -i content-security-policy

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 :

castor site:build
castor site:deploy --dry-run

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 :

  1. Ouvrez Build → Pipelines et retrouvez la pipeline du tag précédent.
  2. Ouvrez son job release:site-deploy et 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 :

curl -s https://www.kirexo.app/ | grep kirexo:version

La version lue sur le domaine public est le seul garde-fou qui atteste ce qu'il sert.

10. Basculer vers le repli OVH

  1. Déclarez les variables OVH_FTP_HOST, OVH_FTP_USER et OVH_FTP_PASSWORD (étape 3) si ce n'est pas déjà fait.
  2. Passez SITE_DEPLOY_PROVIDER à ovh.
  3. Dans la zone DNS, faites pointer www vers l'hébergement OVH lié au domaine, avec l'enregistrement qu'OVH indique pour cet hébergement, à la place du CNAME deploybase.
  4. Relancez release:site-deploy sur 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.