Aller au contenu
JoeCMS Télécharger 3.1.5
Manuel · 14

Environnements, installation et déploiement

Où se trouvent les configurations, ce qui change entre développement et production, comment on met en ligne une modification et comment on empaquette une version.

1. Prérequis d'exploitation

  • PHP ≥ 8.1 avec mysqli, mbstring, json, curl, openssl (critiques) et gd (conseillée)
  • MySQL 8 / MariaDB, y compris avec le sql_mode strict par défaut (voir 07). Port non standard (Aiven, bases de données managées) : FF_DATABASE_PORT dans la config, que l'assistant écrit tout seul, ou bien host:porta dans FF_DATABASE_HOST
  • Apache avec mod_rewrite — le .htaccess fait partie intégrante de l'architecture, ce n'est pas un accessoire : sans lui, le front controller ne reçoit rien
  • droits d'écriture sur themes/site/conf/, uploads/, cache/ et sur la docroot (pour le .htaccess)
  • exec() et shell_exec() ne sont pas nécessaires : sur les hébergements qui les placent dans disable_functions (beaucoup d'hébergements mutualisés, tous les gratuits), le site fonctionne tout de même, car la syntaxe des caches et des jobs est vérifiée à l'aide de l'analyseur interne de PHP (vendor/wolfgan/filemanager/services/fs_php.php, vendor/hcore/jobs/Jobs.php). Sans eux, seuls les programmes externes sont absents : l'aperçu des PDF (convert d'ImageMagick, remplacé par une icône générique) et les optimiseurs externes d'images, CSS et JS qu'ffMedia::optimize() utilise s'il les trouve (jpegoptim, optipng, cssnano, uglifyjs…). La garde est présente dans les deux copies de ffMedia et ffThumb : les sites installés via l'assistant chargent celles de vendor/phpformsframework/, et non ff/classes/
  • s'il faut des jobs : un planificateur (cron du panneau, via curl) — voir 05
  • s'il faut un worker : accès shell et systemd — tous les hébergements mutualisés ne le permettent pas

2. Les deux fichiers de configuration d'environnement

themes/site/conf/config.local.php     développement (hôte se terminant par .local)
themes/site/conf/config.remote.php    production    (écrit par l'installeur, chmod 0640)

C'est HTTP_HOST qui décide lequel est chargé. Aucun des deux n'est suivi dans git : le dépôt ne contient que les .dist. C'est là que se trouvent les secrets — identifiants BD, SMTP, JC_APP_SECRET, JC_AUTH_SALT, SENTRY_DSN, clés des fournisseurs. Voir IGIENE_SEGRETI.md.

⚠️ JC_APP_SECRET et JC_AUTH_SALT sont uniques par installation (64 hex issus de random_bytes). Régénérer config.remote.php invalide les sessions et rend illisible tout ce qui a été chiffré avec ce secret. Le fichier va dans la sauvegarde, et on ne le régénère pas.

Constantes qu'un projet touche souvent :

ConstanteEffet
JC_SITE_DOMAINle domaine de l'installation, d'où hook.php tire DOMAIN_PROD et WWW_LINK (voir l'encadré au §3). L'installeur l'écrit
AREA_SEO_SHOW_MODIFY, AREA_PUBLISHING_SHOW_PREVIEW, MOD_SEC_PROFILING, MAX_UPLOADvaleurs que hook.php ne fixe que si le config ne les a pas déjà définies (08 §4)
JC_REGISTRATION_ENABLEactive/désactive l'inscription
JC_USER_AREA_PATHchemin de l'espace personnel (/area-utente n'est qu'un repli)
ADMIN_TOOLBAR_HIDDENbarre d'édition sur le front-end (par défaut true = masquée)
AI_MD_ENABLEDversion Markdown des contenus pour les LLM
MOD_AUTH_COOKIE_SECURE, MOD_AUTH_COOKIE_SAMESITEcookie de session (08 §6)
SENTRY_DSNsuivi des erreurs (13 §4)
AUTH_2FAsecond facteur à la connexion : '' désactivé, email ou sms (08 §5bis). L'installeur l'écrit vide
DEBUG_MODE, DISABLE_CACHE, CACHE_LAST_VERSIONcache des ressources (12)

3. Première installation : l'assistant

La garde est dans config.php : si l'hôte ne se termine pas par .local et que config.remote.php manque, il inclut install/index.php et sort. La seule présence de la config désactive l'assistant.

Dix étapes : requirements → database → application → billing → localization → admin → registration → layout → services → done. Le détail est dans PANORAMICA_JOECMS.md §7 et dans INSTALLER_PIANO.md.

Les parties qui comptent en pratique :

  • Interface en quatre langues (IT, EN, ES, FR). Tous les textes de l'assistant, messages d'erreur compris, se trouvent dans le dictionnaire de install/i18n.php et se lisent avec jc_t('chiave', …) (marqueurs sprintf) ; install/lib.php, install/icons.php et install/cleanup.php passent aussi par là. À la première visite, la langue vient d'Accept-Language (celle prise en charge avec le q le plus élevé ; l'anglais s'il n'y en a aucune), puis elle reste en session et dans le cookie jc_install_lang. Le sélecteur en haut à droite ouvre ?step=<step>&lang=xx : le contrôleur enregistre le choix et redirige sans le paramètre, ainsi les POST suivants ne répètent pas le changement (les données non envoyées du formulaire en cours sont perdues). La langue de l'installeur est la langue par défaut du site : tant que l'étape localization n'a pas été envoyée, c'est aussi la seule active ; ensuite, changer de langue déplace la langue par défaut et l'ajoute à celles choisies. L'étape localization a le dernier mot. La langue sert aussi de valeur par défaut pour le fuseau horaire et le pays. Une nouvelle chaîne s'ajoute au dictionnaire dans les quatre langues, avec les mêmes marqueurs.
  • CREATE DATABASE avec repli en douceur : si l'hébergement le refuse, l'assistant dit « créez-la depuis le panneau » et ne retente que la connexion. Il se dégrade, il ne se bloque pas.
  • Envoi d'un email de test pendant l'installation : le courrier se vérifie avant de terminer. Le Chiffrement se choisit en paire avec le port — SSL/TLS avec 465, STARTTLS avec 587, aucun avec 25 — et c'est la même valeur qui finit dans A_SMTP_SECURE : une mauvaise paire donne un timeout, et l'erreur suggère la bonne. Le mot de passe laissé vide conserve celui déjà saisi.
  • Étape services : consentement aux cookies, Sentry et les identifiants des fournisseurs de notifications — JoeSMTP et Twilio pour les SMS (avec l'expéditeur, sans lequel ils ne partent pas), OneSignal pour le push. Ils finissent dans l'espace Services, pas dans la config ; on peut les laisser vides et les saisir plus tard (06 §4).
  • .htaccess généré à partir du domaine de l'assistant (jc_write_htaccess()), avec le domaine saisi dans toutes les conditions HTTP_HOST (points échappés, www. et nu, sous-domaines media./static., CORS, cache statique), ancrées aux deux bouts pour que celles de l'hôte principal ne vaillent pas aussi pour media. (11 §5). Sans domaine connu → aucune contrainte HTTP_HOST, ainsi le site reste accessible.
  • Fichiers internes fermés au navigateur : juste après la redirection HTTPS, le .htaccess répond 404 aux PHP (et aux .sql, .log, .sh, .ini, .lock…) de library/, vendor/, ff/, conf/, applets/, contents/, cache/, uploads/, migrations/, à tout cache/logs/ et, à la racine, à database.sql et aux .md. Apache sert de lui-même tout fichier qui existe (index.php n'intervient que pour les autres) : jusqu'à la 3.1.0 n'importe qui téléchargeait les logs du CMS et le dump, et exécutait les PHP que le CMS se contente d'inclure. Restent ouverts les fichiers statiques (CKEditor est dans vendor/), cm/ (showfiles.php, static.php, error.php sont de vraies adresses), themes/ (kcfinder) et modules/ : chaque module se protège lui-même, parce que le Package Manager ouvre /modules/<id>/installer/wizard.php. La condition sur REDIRECT_STATUS laisse passer les réécritures internes (/static → cm/static.php, l'ErrorDocument).
  • Durcissement : install.lock, chmod 0640 sur la config, install/cleanup.php (POST uniquement, seulement si la config existe) qui supprime récursivement /install.

⚠️ Le .htaccess ne voyage pas dans le ZIP. Le fichier suivi dans git contenait les domaines de développement, et la garde « je n'écrase pas s'il existe » le laissait intact → site mort. C'est l'installeur qui le génère.

⚠️ Les constantes du domaine se lisent toujours avec defined(). hook.php définit WWW_LINK, WWW_LINK_ABSOLUTE, DOMAIN_PROD et LOCAL_DOMAIN dans tous les cas, avec une comparaison de l'hôte tolérante au préfixe www. et au port. Les anciennes installations les définissaient dans un switch ($_SERVER["HTTP_HOST"]) : servi sur un hôte différent de celui listé, rien n'était défini, et en PHP 8 lire une constante inexistante est une Error fatale — page blanche, et non plus le warning avec repli sur le nom de PHP 7. Comme sur un site hook.php peut être plus ancien que le code qui le lit, le CMS ne le tient jamais pour acquis : library/gallery/common/set_header_page.php passe par set_header_page_is_canonical_host() et par la garde defined("DOMAIN_PROD"). Même règle pour les applets et pour le code du site.

⚠️ Le domaine se trouve dans le config, pas dans hook.php. L'installeur écrit define('JC_SITE_DOMAIN', 'esempio.it') dans config.remote.php, et hook.php le lit de là ; sans lui, la production est supposée et les liens se construisent à partir de l'hôte de la requête (sur une préproduction, pas de noindex). Jusqu'à la 3.0.3, l'installeur l'écrivait dans hook.php à la place du placeholder [DOMINIO], et chaque mise à jour, qui remplace hook.php, l'effaçait. hook.php est désormais entièrement de la plateforme : ce qui appartient au site se trouve dans le config (valeurs) et dans hook.local.php (code), que la mise à jour ne touche pas (10 §1). Avec un déploiement manuel, la ligne JC_SITE_DOMAIN va dans le config avant d'envoyer le nouveau hook.php.

4. Déploiement : mettre en ligne la branche active

Régénérer le paquet à chaque correctif est trop lent, et l'envoi fichier par fichier depuis un client FTP est le moyen le plus efficace de casser un site en exploitation : la production garde un mélange de versions — un vieux hook.php avec un nouveau module donne un Fatal error — et cette combinaison n'existe dans aucun commit, donc on ne la reproduit pas en local.

Le CMS apporte l'outil qui évite tout cela : bin/deploy.sh, qui envoie via SSH le HEAD de la branche git sur laquelle vous êtes, et seulement les fichiers modifiés depuis le dernier déploiement.

cp bin/deploy.conf.example bin/deploy.conf    # une fois par installation
./bin/deploy.sh controlla                     # qui je suis sur le serveur, où est la docroot, à quel commit
./bin/deploy.sh                               # essai à blanc : liste ce qu'il enverrait
./bin/deploy.sh --vai                         # envoie pour de vrai

Le premier passage, sur un site né de l'assistant ou d'envois manuels, doit être complet — il ne correspond à aucun commit, et l'incrémental ne saurait pas d'où partir :

./bin/deploy.sh --vai --completo --svuota-cache

Si le shell répond permission denied: ./bin/deploy.sh, le fichier a perdu son droit d'exécution (cela arrive en le copiant à la main, depuis un client FTP, depuis Windows ou dans un dépôt avec core.fileMode=false, ou dans un nouveau projet créé en copiant les fichiers de cms). On le lance une fois avec bash : le script s'aperçoit qu'il a perdu le bit, le remet sur le disque et dans l'index de git, et dès lors un commit suffit pour qu'il ne se perde plus au prochain checkout :

bash bin/deploy.sh controlla
git commit -m "bin/deploy.sh exécutable" bin/deploy.sh

Comment il sait d'où repartir

À la fin du déploiement il écrit le commit sur le serveur dans $HOME/.joecms-deploy-rev-<site> : dans la home de l'utilisateur SSH, pas dans la docroot, parce qu'il ne doit pas être accessible depuis le web. Le suffixe avec le nom du site sert quand plusieurs installations vivent sur le même serveur, avec le même utilisateur (souvent root) : avec un seul fichier chaque déploiement repartirait du commit d'un autre site.

On déploie toujours le HEAD : les fichiers modifiés et non commités ne partent pas, pas plus que ceux jamais ajoutés à git — le script les liste avant de bouger, et si vous avez demandé --vai avec un working tree sale, il s'arrête.

Configuration

Elle est dans bin/deploy.conf, hors de git : elle est propre à chaque installation et à chaque machine. Le dépôt ne contient que bin/deploy.conf.example.

Un site avec plusieurs environnements (production, staging) garde un fichier pour chacun, bin/deploy.<environnement>.conf, et le choisit avec --ambiente :

./bin/deploy.sh --vai                         # bin/deploy.conf
./bin/deploy.sh --ambiente produzione --vai   # bin/deploy.produzione.conf

Avec --ambiente le fichier doit exister : le script ne se rabat pas sur bin/deploy.conf, ce qui voudrait dire déployer sur le mauvais environnement. Il vaut mieux que le fichier par défaut soit le staging, ainsi on n'atteint la production qu'en la demandant par son nom.

CléÀ quoi elle sert
DEPLOY_HOST, DEPLOY_USER, DEPLOY_PORTconnexion SSH ; hôte et utilisateur obligatoires
DEPLOY_ROOTdocroot vue depuis SSH — la même valeur que FF_DISK_PATH dans config.remote.php
DEPLOY_CHOWN'utilisateur:groupe' du site, obligatoire si vous vous connectez en root
DEPLOY_PHPle PHP CLI du conteneur du site, pour le contrôle de version final
DEPLOY_URL, DEPLOY_SMOKEsmoke test HTTP de fin de déploiement ; sur un site multilingue, une page par langue

⚠️ Déploiement en root sans DEPLOY_CHOWN : les fichiers envoyés restent à root et avec suexec ou suPHP le site répond 500 sur tout. Le script refuse de démarrer, et l'avertissement ne se contourne pas avec --forza. ./bin/deploy.sh controlla montre le bon propriétaire.

Les options

OptionEffet
controlladiagnostic : utilisateur, docroot trouvée seule, binaires PHP avec mysqli/mbstring, permissions de cache/ et uploads/, commit enregistré
(aucune)essai à blanc — ne touche pas le serveur
--vaiexécute
--completotous les fichiers versionnés du HEAD (premier déploiement, ou réalignement)
--rimuovisupprime du serveur les fichiers retirés du dépôt (sans elle, ils restent où ils sont)
--svuota-cachevide cache/ sur le serveur, en gardant cache/logs/ et cache/.thumbs/
--da <sha>part d'un commit indiqué à la main au lieu de celui enregistré
--solo <path>limite à un sous-arbre
--forzacontinue avec un working tree sale
--niente-smokesaute la vérification HTTP finale

Ce qui ne voyage pas, et pourquoi

ExcluPourquoi
themes/*/conf/config.remote.php, config.local.phpidentifiants BD et JC_APP_SECRET : on les modifie à la main sur le serveur
.htaccess racineen production c'est celui généré par l'installeur avec le vrai domaine ; l'écraser avec celui de développement éteint le site
install/l'installeur a déjà été supprimé par install/cleanup.php : le remettre en ligne n'est qu'une surface d'attaque en plus
database.sqlle schéma ne s'applique jamais par copie de fichiers
cache/contenu généré par le site
docs/, tests/, *.md de travail, .idea/, .claude/, .githooks/matériel de développement ; un docs/sql publié serait une invitation à lire les migrations
modules/*/tests/les tests des modules : destructifs sur la base de données qu'on leur passe, et inutiles sur le serveur

Quand l'une de ces choses change et que la modification doit quand même arriver en production, le script le dit au lieu de l'envoyer en douce : il liste les migrations de docs/sql/ en rappelant qu'elles doivent être appliquées avant le code (le nouveau code sur un vieux schéma fait SHOW COLUMNS et se désactive tout seul ; le vieux code sur un nouveau schéma, non), les nouvelles define() apparues dans config.remote.php.dist, et les modifications du .htaccess.

Le cache

Templates, contenus et ressources passent par le cache sur disque : à peine envoyés, le site continue de servir l'ancienne version. Si le déploiement touche applets/, contents/ ou themes/<thème>/{layouts,contents,css,javascript} le script le signale et on ajoute --svuota-cache, qui nettoie cache/ en laissant cache/logs/ (le journal des erreurs, la première chose à regarder si quelque chose a cassé) et sans recréer le dossier, pour que les permissions restent les bonnes. Il laisse aussi cache/.thumbs/, les copies des images que media.<domaine> sert telles quelles : les effacer toutes d'un coup, c'est une vague de régénérations, et avec un .htaccess qui envoie aussi à index.php les requêtes de media., c'est un 500 sur chaque image (11 §5). Sur un site multilingue il y a aussi ici cache/locale.php, l'instantané des langues actives.

⚠️ Avec un opcache.revalidate_freq élevé sur le serveur, le cache se vide après, pas tout de suite. PHP revérifie la date d'un fichier déjà compilé au plus toutes les revalidate_freq secondes (par défaut 2) : avec une valeur comme 60, dans la première minute après l'envoi il peut encore exécuter l'ancienne version d'un fichier utilisé récemment, alors qu'il lit déjà les templates neufs sur le disque. Les pages régénérées pendant cette minute — y compris par la vérification finale du script — sortent avec l'ancien code, ou avec le nouveau template et l'ancien PHP, et le cache de page les garde pendant des heures. Avec une valeur élevée, on vide cache/ à la main une fois ce délai passé (le script, s'il n'y a rien à envoyer, s'arrête sans y toucher), ou on redémarre le PHP-FPM du site avant de le vider.

Les corrections au .htaccess généré (par l'assistant, jc_write_htaccess() dans install/lib.php, ou par le modèle de l'ancien installeur, conf/gallery/install/.htaccess-cms.tpl) n'arrivent pas aux sites déjà installés, parce que ce fichier ne voyage pas : il faut les reporter à la main, comme pour le sous-domaine media. (11 §5). Après la 3.1.0 elles sont deux : le bloc des fichiers internes (§3) et ExpiresByType text/html "access plus 0 seconds" (12) ; les lignes exactes sont dans jc_write_htaccess() et jc_htaccess_static_tail(), et depuis la 3.1.1 aussi dans les trois modèles conf/gallery/install/.htaccess-*.tpl de l'ancien installeur.

La vérification finale

Le smoke test tourne depuis votre ordinateur, pas depuis le serveur : il appelle les routes en HTTP comme le ferait un navigateur, et c'est le contrôle qui intercepte le fichier oublié. Avec DEPLOY_SMOKE on liste les chemins ; sur un site multilingue on en met un par langue, et c'est ainsi qu'on découvre la langue restée en arrière. Si le projet a tests/run.php avec tests/smoke.config.php, le script utilise cette suite au lieu des appels curl.

Ce qui reste à la main

Migrations SQL, nouvelles constantes dans config.remote.php, .htaccess, cron du panneau.

Une installation au schéma < 4 doit être alignée une fois, avant l'envoi du code de la 1.6.0 : le nouveau code écrit NULL dans les dates vides, ce qu'un schéma 3 refuse même sur un serveur non strict (#1048), alors que le schéma 4 supporte aussi le code 1.5.x. On envoie seulement bin/db-allinea-schema.php, on le lance en essai à blanc puis avec --vai, et ensuite seulement on fait le déploiement. Pour ce fichier, scp convient, pas deploy.sh --solo : il enregistre tout le HEAD comme envoyé, et le déploiement suivant n'apporterait pas le reste.

Et, seulement la première fois, les permissions des dossiers accessibles en écriture :

chmod -R 775 cache uploads && find cache uploads -type d -exec chmod g+s {} +

bin/ ne doit pas être accessible depuis le web : le paquet contient bin/.htaccess avec Require all denied. Sur nginx la règle doit être reproduite dans la configuration du serveur.

5. Paquet et versions

./build-zip.sh [version]      # → joecms-<version>.zip

Il empaquette les fichiers suivis par git dans l'état du working tree (pas git archive, qui ignorerait les modifications non commitées), et exclut : configs d'environnement (les .dist restent), .htaccess de développement, docs/ (sauf le manuel), les *.md racine, les hooks de développement (.githooks/, .claude/), les source maps, les dossiers test/doc/example des vendors. Il vide cache/ et ne garde de uploads/ que loghi.

Exceptions à la règle « pas de markdown » : CHANGELOG.md et docs/manuale/ (depuis la 1.3.0), qui voyagent avec le paquet.

Exception à la règle « pas de scripts shell » : bin/ — deploy.sh et deploy.conf.example — voyage aussi. C'est avec lui que le site tout juste installé se met à jour à partir de là (§4), et bin/.htaccess le garde hors du web. Les vérifications de fin de build contrôlent sa présence, et cherchent les autres .sh, qui n'ont rien à faire dans la docroot.

Le script vérifie tout seul qu'aucun secret ne finit dans le paquet et que seed, installeur, changelog et chapitres du manuel sont présents.

Le manuel dans le paquet est un instantané

Le manuel qui arrive sur un site décrit la version installée sur ce site et ne se met pas à jour quand le CMS principal avance : la version suivante apporte le sien. La build :

  • ajoute en tête de chaque chapitre une ligne avec version et date du paquet ;
  • ajoute docs/manuale/VERSIONE.txt (version, date, commit d'origine) ;
  • met les fichiers en lecture seule ;
  • écrit docs/.htaccess avec Require all denied : le manuel décrit l'intérieur de la plateforme (chemins, pièges) et ne doit pas être servi au public. Il se lit depuis le ZIP ou via FTP/panneau. Sur nginx la règle doit être reproduite dans la configuration du serveur.

Le manuel se met à jour avec le code (seulement dans le dépôt principal)

Dans le dépôt du CMS le manuel suit le code automatiquement. .githooks/manuale-check.sh compare les fichiers modifiés avec les chemins que chaque chapitre cite entre backticks — la table fichier → chapitre n'est pas écrite à la main, elle se déduit du manuel lui-même — et liste les chapitres touchés mais non mis à jour.

Point de contrôleCe qu'il fait
Hook Stop de Claude Code (.claude/settings.json)en fin de tour, s'il y a des chapitres à revoir, il arrête la clôture et fait mettre à jour le manuel ; chaque paire chapitre/fichier est signalée une fois par contenu (.git/manuale-ack)
Hook git pre-commit (.githooks/pre-commit)sur les fichiers indexés il bloque une fois par paire chapitre/fichier et contenu (.git/manuale-ack-commit) : si le manuel n'est pas à toucher, il suffit de refaire le même commit. MANUALE_WARN_ONLY=1 le réduit à un avertissement
À la main.githooks/manuale-check.sh sur le working tree ; --commit <sha> sur un commit déjà fait

Le hook git doit être activé une fois par clone : git config core.hooksPath .githooks. Pour garder la table fiable, dans les chapitres les fichiers se citent par chemin, entre backticks. Le numéro de ligne accolé (library/gallery/system/cache.php:957) est toléré. Deux règles fixes complètent la table : les migrations de docs/sql/ vont au chapitre 07, et hook.php, cité dans presque tous les chapitres, ne compte pour un chapitre que si la modification touche une fonction que ce chapitre nomme (par exemple registerUser()).

⚠️ Le contrôle ne protège que les modifications qui passent par lui. Le hook Stop ne voit que les modifications non commitées d'une session de Claude Code dans ce dépôt. Le pre-commit bloque au lieu de simplement avertir parce que les clients graphiques (Sourcetree, PhpStorm) n'affichent la sortie d'un hook que quand il échoue : tant qu'il se contentait d'avertir, un travail rapporté d'un autre projet et commité aussitôt (c'est arrivé avec la préférence de langue) est arrivé sans manuel et sans que personne ne le voie. Un commit fait avec Bypass commit hooks dans Sourcetree, ou avec --no-verify, saute le contrôle : dans ce cas on lance ensuite .githooks/manuale-check.sh --commit <sha>.

Versionnage

ConstanteOùQuand on l'incrémente
JC_VERSIONinstall/lib.phpà chaque paquet
JC_SCHEMA_VERSIONinstall/lib.phpchaque fois que database.sql change

Les modifications se notent dans CHANGELOG.md sous [Non publié] au fur et à mesure, et deviennent la section de la version quand on crée le paquet (build-zip.sh avertit si la section de la version en build manque).

Le schéma dans le CHANGELOG : ce que lit joecms.it

La page de téléchargement et le changelog de joecms.it déduisent du CHANGELOG.md du paquet si une version change le schéma de la base de données, et dans ce cas ils préviennent qu'il faut appliquer les migrations avant le code. Pour le site, le schéma d'une version est le premier nombre en gras (un chiffre) à moins de 40 caractères du mot « schema », cherché dans le résumé puis dans l'en-tête ; une version sans nombre hérite de celui de la précédente ; une version change le schéma si elle a le groupe ### Schema ou un nombre différent de celui de la précédente. La section d'une version porte donc :

  • dans l'en-tête, ## [X.Y.Z] — AAAA-MM-JJ · schema **N**, avec N = JC_SCHEMA_VERSION ;
  • le groupe ### Schema seulement si N a changé : ce qui change, la migration de docs/sql/ et l'ordre, d'abord le schéma puis le code (§4) ;
  • dans le résumé, aucun autre schéma en gras avant N, parce que le site lirait celui-là.

C'est vérifié par .githooks/changelog-schema.php, qui lit la section comme le site et la compare à JC_SCHEMA_VERSION, au schéma de la version précédente (celui de install/lib.php au commit qui a porté JC_VERSION à ce numéro) et à database.sql, lignes vides et commentaires -- exclus. build-zip.sh s'arrête si ça ne colle pas. Le pre-commit fait le même contrôle sur le commit de version, c'est-à-dire celui qui change JC_VERSION, et pas sur les autres : pendant le développement JC_SCHEMA_VERSION peut déjà monter alors que la section de la version courante déclare encore le schéma avec lequel elle est sortie. À la main : php .githooks/changelog-schema.php [version], ou --commit <sha> sur un commit déjà fait.

⚠️ Le nombre a un seul chiffre parce que c'est ainsi que le lit JoeSitoChangelog::versione() dans le projet du site : le schéma 10 doit d'abord être appris au site, et jusque-là le build s'arrête. Dans l'histoire la règle a sauté une fois : la 1.0.5 a ajouté à database.sql les lignes de ff_international des textes de logout et d'inscription, en laissant le schéma à 2.

Mises à jour automatiques et migrations (depuis la v3.0.2)

JoeCMS inclut un moteur intégré (library/updater/JoeCmsUpdater.php) pour mettre à jour les sites déjà en service de façon automatique, sûre et non destructive.

  • CLI (bin/update.php) :
    • php bin/update.php --status : diagnostic de l'environnement et état des migrations
    • php bin/update.php --file <pacchetto.zip> [--vai] : exécute la mise à jour depuis une archive ZIP
    • php bin/update.php --migrations-only [--vai] : n'exécute que les migrations de BD en attente
    • php bin/update.php --maintenance on|off : active/désactive le mode maintenance
  • Backend web (/restricted/updater) :
    • Géré dans conf/gallery/manage/updater/index.php, avec état de santé, envoi de ZIP, console des journaux en temps réel et alignement de la base de données.
  • Système de migrations (migrations/) :
    • Migrations séquentielles .sql ou .php (base schema_0004_v302_baseline.php).
    • Suivi automatique dans la table jc_migrations, géré par MigrationsRunner.
    • schema_0005_testi_multilingua.php (schéma 5) apporte au dictionnaire les textes du bandeau des cookies, des emails du compte et de la récupération du mot de passe : tant qu'elle manque, ces textes sortent comme des codes (svc_cookie_title). L'updater l'exécute de lui-même dans la même opération, le site en maintenance. Avec un déploiement manuel, on envoie d'abord le fichier de la migration, on exécute les migrations (php bin/update.php --migrations-only --vai, ou les migrations en attente dans /restricted/updater, conf/gallery/manage/updater/index.php) et seulement ensuite le reste du code.
  • hook.php et hook.local.php (library/updater/JoeCmsUpdater.php) :
    • hook.php appartient à la plateforme et la mise à jour le remplace ; avant, la sauvegarde en garde une copie, ainsi une restauration le ramène avec le reste.
    • hook.local.php, le code du site, est dans la liste protégée (avec le config, .htaccess, uploads/) et build-zip.sh le retire du paquet. Sont aussi protégés les fichiers PWA que l'installeur génère pour le site (manifest.json, site.webmanifest, browserconfig.xml) : dans le paquet de mise à jour, manifest.json est le fichier des métadonnées, et jusqu'à la 3.0.3 il finissait à la place du manifeste du site.
    • Une seule fois, avant d'extraire les fichiers : si le config n'a pas JC_SITE_DOMAIN et que l'ancien hook.php a un domaine écrit ($jc_site_domain = "…"), l'updater le copie dans le config.
  • Mode maintenance (.maintenance) :
    • Géré par cm/maintenance.php en tête de index.php. Répond 503 Service Unavailable, avec un jeton de contournement pour l'administrateur.
    • Textes dans la langue du visiteur (préfixe de l'adresse ou navigateur) et exit après la page, voir 13 §1bis.
  • Deux paquets de build (build-zip.sh) :
    • joecms-<versione>.zip : paquet complet à décompresser pour une nouvelle installation.
    • joecms-update-<versione>.zip : paquet léger avec manifest.json, sans installeur ni dumps destructifs, qui préserve toujours config.remote.php, uploads/, cache/ et .htaccess.

6. Checklist de mise en ligne

  • [ ] migrations appliquées et reportées dans database.sql, JC_SCHEMA_VERSION incrémentée
  • [ ] lint PHP propre sur tous les fichiers touchés
  • [ ] marqueurs des templates vérifiés (aucun avec des espaces, aucun perdu)
  • [ ] routing_table.xml modifiés effectivement envoyés (ils ne donnent pas d'erreur : simplement rien ne se passe)
  • [ ] envoi fait avec ./bin/deploy.sh --vai, pas à la main (pas de mélange de versions)
  • [ ] cache/ vidé après l'envoi (--svuota-cache)
  • [ ] crons planifiés et vérifiés (une ligne de log pour chacun)
  • [ ] webhooks configurés chez les fournisseurs, avec le bon secret
  • [ ] email : un vrai envoi de test, pas seulement l'aperçu
  • [ ] robots.txt, sitemap.xml, canonical : cohérents avec le domaine de production
  • [ ] ?__debug__ ne laisse rien fuiter à un utilisateur quelconque (fermé par défaut : aucun SetEnv JC_DEBUG_ALLOWED 1 resté allumé, voir 13 §2)
  • [ ] CHANGELOG.md mis à jour
  • [ ] chapitres de docs/manuale/ alignés (.githooks/manuale-check.sh ne signale rien)

7. Les documents « vivants » du dépôt

La connaissance est à côté du code, pas dans les tickets. Ils doivent être mis à jour à chaque intervention :

FichierPérimètre
MIGRAZIONE_PHP7_PHP8.mdmigration et cas PHP 8
FIX_FUNZIONAMENTO.mdcorrectifs qui changent le comportement
MIGLIORIE_ESTETICHE.mdinterventions CSS/UI uniquement (marquées /* INTERVENTO CSS - GP AAAA-MM */)
CHANGELOG.mdhistorique des versions
PANORAMICA_JOECMS.mdarchitecture et histoire des décisions
INSTALLER_PIANO.md, VGALLERY_NEXT_PIANO.mdplans de travail
IGIENE_SEGRETI.mdgestion des secrets
GUIDA_INDICIZZAZIONE_AI.md, GUIDA_SITEMAP.mdréglages par défaut réutilisables pour l'indexation et la sitemap
docs/manuale/ce manuel : ce que permet la plateforme — contrôlé automatiquement, voir §5