Mettre à jour un StarterKit

Les sites StarterKit v2 (Umbraco 6) et v3 (Umbraco 7), tous deux en .NET Framework 4.8 sur IIS, partagent le même pipeline GitLab, à quelques détails près. Pas de copie de fichiers à la main, pas de FTP : tu merges ton code, et un pipeline compile le site puis l'installe sur le serveur. Cette page explique comment déclencher une mise à jour, ce que fait le job de build, et ce qui se passe au déploiement. Les rares différences entre les deux versions sont regroupées en bas de page.

L'idée en deux mots

Le déploiement est pull-based et tourne en deux temps :

1. Un runner de build compile le projet pour un skin donné et publie le dossier website/ comme artefact.
2. Un runner installé directement sur le serveur IIS récupère cet artefact et l'applique en local.

Deux choses à retenir, qui expliquent toute la mécanique :

• Un pipeline = un seul site. Le site à déployer est choisi via la variable SKIN au moment de lancer le pipeline. C'est pour ça que le déploiement est toujours manuel : on cible un client précis à chaque fois.
• Aucun secret n'est nécessaire. Tout est déduit du SKIN et de la branche. Le runner étant sur le serveur, il n'a pas besoin d'identifiants pour s'y connecter.

La branche détermine l'environnement : staging déploie en staging, master déploie en production.

Mettre à jour un site, étape par étape

1. Merge ton code sur la bonne branche : staging pour la recette, master pour la production.

2. Va sur le projet dans GitLab, puis dans Build => Pipelines => New pipeline.

   

3. Choisis la branche (staging ou master).

4. Renseigne la variable SKIN : c'est le nom du dossier client (sous src/Nanoxi.Cms.Custom/<skin> en v3, src/Nanoxi.Customization/<skin> en v2). Par défaut elle pointe sur le skin de démo du starterkit, donc pense bien à mettre le bon skin (par exemple cvdp, comme sur la capture ci-dessous).

5. Lance le pipeline. Le build démarre tout seul et produit l'artefact du site.

   

6. Une fois le build au vert, déclenche manuellement le job de déploiement (deploy:staging ou deploy:production) en cliquant sur le bouton "play" du job. Tant que tu ne cliques pas, rien n'est touché sur le serveur.

Pourquoi ce clic manuel

Le job de déploiement ne part jamais automatiquement, même sur master. C'est volontaire : ça te laisse vérifier que le build est bon avant d'écraser un site en production, et ça évite qu'un simple push parte en prod par accident.

Le job build

Le job build est la première étape du pipeline et tourne sur le runner taggué windows (celui qui a .NET, MSBuild et NuGet). Il fait trois choses :

1. Il compile le site pour le skin demandé, via Cake : build.ps1 -Target CI-Build -Configuration release --skin=<skin>. Le résultat est publié dans un dossier website/.
2. Il estampille le build : il écrit le commit (version.txt) et l'identifiant du pipeline (pipeline.txt) dans website/, pour qu'on puisse toujours retrouver ce qui a été compilé.
3. Il publie l'artefact : le dossier website/, nommé <skin>-<branche>-<sha>, conservé deux semaines.

Avant et après la compilation, le job tue les processus de compilation qui traîneraient (VBCSCompiler, MSBuild, csc, vbc). Le runner Windows est partagé entre les builds, et un compilateur resté en mémoire verrouille des fichiers ou pollue le build suivant : ce nettoyage évite les erreurs aléatoires du genre "fichier utilisé par un autre processus".

Pas besoin de base de données pour builder

Le pipeline passe une variable CI_SQL_CONNECTION_STRING bidon. Elle est exigée par build.cake, mais la cible CI-Build ne touche jamais à une base : c'est juste pour que le script ne râle pas. N'y mets pas une vraie chaîne de connexion.

Builder sans déployer

Comme le déploiement est manuel, lancer un pipeline sans cliquer sur le job de déploiement te donne juste un build. C'est exactement ce qu'il faut quand tu veux :

• vérifier qu'une branche compile bien, sans rien envoyer sur un serveur ;
• récupérer un site compilé pour l'installer ou l'inspecter à la main.

Dans ce cas, va sur le pipeline, ouvre le job build et télécharge son artefact (le dossier website/). Aucun serveur n'est touché tant que tu ne déclenches pas un job deploy.

Ce que fait le déploiement

Quand tu déclenches le job de déploiement, le runner sur le serveur enchaîne, pour le bon site (E:\<skin>\website) et le bon pool applicatif (umb_<skin>_<env>) :

1. Il pose une page de maintenance (App_Offline.htm) pour que les visiteurs voient un message propre plutôt qu'un site à moitié mis à jour.
2. Il arrête le pool IIS du site.
3. Il synchronise les fichiers du nouveau build vers le dossier du site (un miroir, donc ce qui n'existe plus dans le build est retiré).
4. Il redémarre le pool et retire la page de maintenance.

L'indisponibilité se compte en quelques secondes, le temps de la synchronisation et du redémarrage du pool.

Les dossiers et fichiers qui ne sont jamais écrasés

La synchronisation protège délibérément tout ce qui est géré côté serveur ou alimenté par le client. En v3, ne sont pas touchés par un déploiement :

• Config, App_Data (configuration et données runtime)
• Media et Customer (médias et contenus uploadés)
• umbraco\Logs (les logs)
• le Web.config

Autrement dit, un déploiement met à jour le code du site, jamais les données ni la config propre à l'environnement. C'est ce qui rend l'opération sûre à répéter.

Modifier un fichier de config : à faire à la main sur le serveur

Le revers de cette protection vaut pour tous les anciens sites StarterKit (v2 et v3) : comme Config, le Web.config et les autres fichiers protégés ne sont jamais écrasés, une modification que tu apportes à ces fichiers dans le code ne partira jamais au déploiement. Le pipeline les ignore au moment de la synchro.

Concrètement, si tu dois changer une valeur de config (chaîne de connexion, clé d'app, réglage IIS, app setting...), il faut le faire à la main directement sur le serveur, dans E:\<skin>\website\Config ou le Web.config. Modifier uniquement le fichier dans le dépôt et relancer un pipeline ne suffit pas : le serveur gardera l'ancienne valeur.

Revenir à une version précédente (rollback)

Comme un déploiement ne fait que recopier un artefact de build sur le serveur, sans jamais toucher aux données ni à la config (voir l'encadré ci-dessus), revenir en arrière revient simplement à redéployer une version antérieure. Deux cas :

• L'ancien pipeline est encore là (moins de deux semaines). Retrouve le dernier pipeline "bon" (celui du commit qui marchait, pour le même SKIN), ouvre-le et relance son job deploy avec le bouton "play". Il réinstalle son propre artefact, donc l'état d'avant. C'est le chemin le plus rapide.
• L'artefact a expiré, ou tu préfères repartir du code. Fais un git revert du commit fautif sur la branche, merge, puis relance un pipeline normal (étapes ci-dessus) et déploie. L'historique Git reste la source de vérité.

Un rollback est aussi sûr qu'un déploiement

Rien de spécial à prévoir : c'est un déploiement comme un autre, avec la même mise hors ligne de quelques secondes et les mêmes dossiers protégés. Tu peux le répéter sans risque pour les médias, la base de données ou la config.

Si un déploiement échoue en cours

Le job de déploiement pose App_Offline.htm et arrête le pool avant de synchroniser. S'il plante entre les deux (réseau, fichier verrouillé, runner coupé), le site peut rester hors ligne : page de maintenance affichée et/ou pool arrêté.

Pour repartir, dans l'ordre :

1. Relance le job deploy. Il est idempotent : il repose la page de maintenance, resynchronise, puis redémarre le pool et retire App_Offline.htm. Dans la grande majorité des cas, ça suffit.
2. Si le job ne peut plus tourner (runner indisponible), remets le site en ligne à la main sur le serveur IIS : supprime E:\<skin>\website\App_Offline.htm et démarre le pool umb_<skin>_<env>.

Prérequis et points d'attention

• Le site doit déjà exister dans IIS. Le déploiement met à jour un site en place ; il ne le crée pas. Si le dossier E:\<skin>\website n'existe pas, le job s'arrête avec un message explicite. La première installation d'un site (site IIS, pool applicatif, virtual directories, base de données) est une opération distincte : voir Mise en place d'un site.
• Le nommage suit la convention. Pool applicatif umb_<skin>_<env>, chemin E:\<skin>\website : c'est la convention de nommage appliquée à IIS.
• Les runners sont taggués. Le build tourne sur le runner windows, le déploiement sur windows-staging-iis ou windows-prod-iis. Si un job reste "en attente" sans démarrer, c'est souvent qu'aucun runner avec le bon tag n'est disponible.
• Tracer la version déployée. Le build dépose dans le site un version.txt (le commit déployé) et un pipeline.txt (l'identifiant du pipeline). Pratique pour vérifier d'un coup d'œil ce qui tourne réellement sur un serveur.

Différences entre v2 et v3

Le pipeline est le même. Seuls trois détails changent, parce que les deux starterkits ne reposent pas sur la même version d'Umbraco :

	StarterKit v2	StarterKit v3
Version Umbraco	6.2.6	7.15.3+
Dossier de customisation du skin	src/Nanoxi.Customization/<skin>	src/Nanoxi.Cms.Custom/<skin>
Dossiers protégés au déploiement	Config, App_Data, media	Config, App_Data, Media, Customer, umbraco\Logs

La v2 protège moins de dossiers : il n'y a pas de dossier Customer, et sous Umbraco 6 les logs vivent dans App_Data (déjà protégé), donc pas de umbraco\Logs à part. Tout le reste (étapes, job de build, déploiement manuel par skin, mise hors ligne pendant la synchro) est rigoureusement identique.

Contributors

Clément Favre

Changelog

Last edited about 2 months ago

View full history

b07d2bb-docs: add Crans-Montana headless and police intranets to parc inventory