Build, base de donnees, NSIS, Docker, deploiement

Cake (build.cake)

Le build est orchestre par Cake (build.cake, ~2900 lignes), lance via le bootstrapper PowerShell build.ps1. Variables principales (defauts) :

• target = Default
• configuration = dev (valeurs : dev, release)
• skin = starterkitv3 (le client a builder ; doit exister dans doc/StarterKitv3_InfosTechniques.json)
• buildmode = single (vs batch pour builder toutes les images Docker)
• umbracoVersion = 7.15.10
• versionUcommerce = 8.4.1.19353

Au demarrage, le build valide doc/StarterKitv3_InfosTechniques.json contre doc/StarterKitv3_InfosTechniques_Schema.json et leve une exception si invalide. La config du skin (langues, URL, shop on/off, modules, widgets) est lue depuis ce JSON via CustomerClientConfig.

Cibles principales

Cible	Role
Review-App	Reconstruction complete locale : check env, clean, changelog, build base+shop+customer, download Umbraco, restore DB, create IIS site, install uCommerce, install packages, postbuild
Make	Build rapide : Build + Build-Shop + Build-Customer + Postbuild-Files (+ customer) + Touch
MakeAndPost	Make + Postbuild complet
Build	Compile StarterKitv3_base.sln
Build-Shop	Compile StarterKitv3_shop.sln si IsShopEnabled()
Build-Customer	Compile StarterKitv3_<skin>.sln (si la solution existe)
Build-All-Customers	Compile toutes les StarterKitv3_*.sln clients
Postbuild / Postbuild-Files	Copie vues, templates email, Umbraco Forms, JS, ressources, parties shop et customer vers website/
CI-Build	Produit un website/ deployable SANS DB / IIS / appels API (utilise par la CI)
GitLab-Pipeline	Check + clean + changelog + build base/shop/customer (test de compilation)
Restore-Database	Create-Virgin-Umbraco-Database + Recreate-User-Database + Execute-ScratchSQL-Database
Download-Umbraco	Recupere / prepare les binaires Umbraco
Create-Website	Cree le site dans IIS
Install-uCommerce	Installe uCommerce (packages + SQL + config)
NSIS	Genere l'installeur Windows (voir ../modules/nsis-installer.md)
Release / Release-Spk	Publish + build image Docker
Review-Customer	Restaure un site depuis Customer/<skin>/current (website + db)

Piege : ecrasement des vues Umbraco Forms par Umbraco-Packages-Extract

Dans la chaine CI-Build, Umbraco-Packages-Extract s'execute APRES Postbuild-Files-UmbracoForms et ecrase les vues Forms avec les templates vanilla : UmbracoForms.Package.7.5.9.zip livre TOUT Views/Partials/Forms/ vanilla (theme default complet inclus), et Umbraco_Forms_on_Perplex_Steroids_1.8.3.zip les 5 fieldtypes Perplex vanilla. Fix-Missing-PerplexConfig s'execute en dernier et re-copie tout le dossier theme depuis Nanoxi.Cms.Base.Contour.Providers + le FieldType.PerplexRecaptcha.cshtml de Nanoxi.Cms.Resources (avant 2026-09, il ne re-copiait que Form/Render/Submitted + 4 fieldtypes Perplex : les CheckBoxList/RadioButtonList vanilla passaient en prod -> checkboxes natives non skinnees, incident diabetevalais 2026-09-01). Le theme Forms s'appelle default et est partage par tous les clients ; les templates skinnes utilisent le markup .radioCheckbox style par form-theme.less de chaque skin.

Probleme connu non resolu : 4 skins ont des overrides Forms client (prodconfig/<skin>/cake/<skin>_postbuild-files-umbracoforms-customerspecific.cake : apol et biofruits Form.cshtml, cotemin FieldType.PerplexTextarea.cshtml, differens FieldType.DatePicker.cshtml). Cette tache client s'execute AVANT Umbraco-Packages-Extract, donc leurs overrides sont ecrases (par les extracts puis par Fix-Missing-PerplexConfig) et n'atteignent jamais la prod via CI-Build -- deja le cas avant le fix de 2026-09. Fix envisageable : rejouer la tache customer-specific apres Fix-Missing-PerplexConfig.

Base de donnees

• SQL Server. Connexion via CI_SQL_CONNECTION_STRING (definie par cake/Set-EnvironmentVariable.ps1).
• Schemas de base versionnes : db/u7_base-<version>.sql (un par version Umbraco, jusqu'a 7.15.10).
• Restore-Database (cible Review-App) : cree une base Umbraco vierge depuis le schema, recree le login/user applicatif, execute les scripts de seed (data/).
• Donnees / structure additionnelle : data/, migrations migrations-spk/ et Nanoxi.Cms.Base.App.Migrations.
• Mots de passe DB par client : doc/StarterKitv3_InfosTechniques.json (saPassword, customerPassword).

Generation de scripts DB (mssql-scripter)

Pour regenerer un script complet (schema + data) d'une base de prod (utilise pour NSIS) :

mssql-scripter -S 127.0.0.1 -d umbraco-starterkitv3-prd-db -U sa --schema-and-data --target-server-version 2017 > ./umbraco-starterkitv3-prd-db.sql

Adapter les chemins physiques .mdf/.ldf selon le serveur cible (voir Readme.md).

NSIS

Installeur Windows genere par la cible NSIS (nsis/StarterKitv3.nsi). Sert au deploiement on-premise historique. Voir ../modules/nsis-installer.md.

Docker

Deux Dockerfiles (image Windows ServerCore .NET Framework 4.8) :

• Dockerfile : image complete. Installe VC++ Redistributables + URL Rewrite 2.1, importe la region fr-CH (RegionSettings_frCH.reg), copie docker/containerdata/ puis website/ dans C:\inetpub\wwwroot, applique les permissions.
• Dockerfile-spk : variante Spektrum (meme base ; partie copie website differente).

FROM mcr.microsoft.com/dotnet/framework/aspnet:4.8-windowsservercore-ltsc2022

docker/maintenancescript/ contient les scripts de maintenance des conteneurs.

CI/CD (GitLab)

.gitlab-ci.yml. Deploiement pull-based : un runner windows compile, un runner installe sur chaque serveur IIS applique l'artifact via robocopy. Aucun secret GitLab requis (tout derive de $SKIN + branche).

Workflow (branches autorisees)

Le workflow: n'autorise un pipeline QUE si :

• branche develop (push) -> build AUTO (test de compilation, aucun deploy), OU
• $CI_PIPELINE_SOURCE == "web" -> declenchement manuel "Run pipeline" (en choisissant la branche + le SKIN).

Donc master/staging ne declenchent un pipeline que via "Run pipeline" (web). Un push direct sur master/staging ne lance rien.

Stages

• build (runner windows) : build.ps1 -Target CI-Build -Configuration release --skin=$SKIN, ecrit version.txt/pipeline.txt. Artifact website/ + deploy/App_Offline.htm (2 semaines).
  • Piege workspace pollue -> artifact pollue : website/ est gitignore (.gitignore: website*/), donc git ne le recree/nettoie pas au checkout, et le runner reutilise son workspace entre pipelines. CleanDirectory(website) de build.cake ne suffit pas en pratique -> website/bin accumule les DLL des builds de skins precedents (uCommerce, autres clients) et l'artifact sort pollue. Consequence observee (actiondiabete, 2026-07-02) : un site non-shop herite d'un ShopApplicationEventHandler + uCommerce orphelins -> crash au boot (Castle.MicroKernel ConverterException / NRE sur UCommerce.IQuery\2[...], Castle.Windsor 5.0.1 incompatible avec uCommerce 8.4.1) -> « Runtime Error ». Le --skin=ne pilote que ce que le build **ajoute** (copies fichier-par-fichier surskinName, cf build.cake~809-843), pas ce qui traine deja dans lewebsite/reutilise. **Fix** :GIT_CLEAN_FLAGS: -ffdxsur le jobbuild(le-xsupprime aussi les fichiers ignores ->website/reparti propre a chaque build). Meme classe de bug que lerobocopysans/MIR` cote serveur (dossier jamais purge).
• deploy (.deploy_iis_local, runner sur l'IIS) : pose App_Offline.htm, stoppe l'app pool umb_<skin>_<env>, robocopy /E (copie/mise a jour seulement, PAS de /MIR/purge) vers E:\<skin>\website en excluant Config, App_Data, Media, Customer, umbraco\Logs, Web.config, App_Offline.htm ; redemarre le pool.
  • Pourquoi pas de /MIR : l'artifact CI-Build ne contient pas les fichiers installes au runtime cote serveur (Umbraco\ucommerce\Apps dont RavenDB25, dossier Raven\, *.lic, local.config, Plugins, Analyzers...). Un mode miroir les effacerait (ils apparaissent en *EXTRA dans le log robocopy) et casserait le site au boot (ex. IRavenDbStoreProvider which was not registered). On ne supprime donc jamais les fichiers extra cote serveur.
  • uCommerce en CI n'est pas garanti complet : CI-Build reconstruit uCommerce via Ucommerce-Extract-Package (extraction .umb + telechargement de nupkgs depuis nuget.org + actions MoveDirectory), pas via le vrai installeur (Install-uCommerce, reserve a Review-App/Release). Un download rate -> Warning + skip silencieux, build vert mais Umbraco\ucommerce\Apps\*\bin lacunaire. En cas de shop casse apres deploy, restaurer Umbraco\ucommerce depuis backup et/ou deployer en portee partielle.
  • DEPLOY_SCOPE (deploiement partiel) : variable de pipeline. Vide = deploiement complet (defaut). Sinon liste (espaces/virgules) parmi bin (= /bin), views (= /Views), site (= /Site, styles/design) -> ne copie QUE ces sous-dossiers (toujours sans purge). Utile pour pousser un correctif de code/vues/styles sans toucher au reste (ex. ne pas remplacer un uCommerce sain par un package CI lacunaire). Ex. DEPLOY_SCOPE="bin views".
  • Detection de l'app pool sous pwsh : le runner tourne en pwsh, ou WebAdministration est charge en WinPSCompatSession -> le lecteur IIS:\ n'existe pas. On detecte/arrete/redemarre donc le pool via Get-WebAppPoolState/Stop-WebAppPool/Start-WebAppPool (et pas Test-Path "IIS:\AppPools\...", qui renverrait toujours $false, laissant le pool actif et les DLL verrouillees -> robocopy code 8+ sur bin\*.dll).
  • deploy:staging (tag windows-staging-iis, branche staging, manuel) -> E:\<skin>\website, pool umb_<skin>_staging.
  • deploy:production (tag windows-prod-iis, branche master, manuel) -> E:\<skin>\website, pool umb_<skin>_prod.
• docs (composant sync-claude-docs) : rsync de .claude/docs/**/*.md vers le serveur de doc interne + trigger du build du site VitePress. Voir plus bas.

Synchronisation de la doc agent (sync-claude-docs)

Le bloc docs est gate par changements (changes: .claude/docs/**/*) sur les branches main/master/staging, ou sur declenchement web manuel. Branche par defaut du depot : master.

Note : le workflow: actuel n'autorise les pipelines que sur develop (push) et la source web. Donc la synchro de doc sur master/staging ne se declenchera que via "Run pipeline" (web), pas sur un push direct. C'est coherent avec le modele de deploiement manuel du projet. Si on veut une synchro auto sur push master/staging, il faudrait elargir le workflow:.

Gotchas dev

• Tout build cible UN skin (--skin=). Le shop n'est compile que si le client l'active.
• Ne pas editer website/ (genere par postbuild) ni les CSS (generes par Grunt).
• Reappliquer les patches Umbraco a chaque update (voir patterns.md).
• DB et media doivent matcher pour les index custom (IEDS / IchMedia).

Contributors

No contributors

Changelog

No recent changes