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) etgd(conseillée) - MySQL 8 / MariaDB, y compris avec le
sql_modestrict par défaut (voir 07). Port non standard (Aiven, bases de données managées) :FF_DATABASE_PORTdans la config, que l'assistant écrit tout seul, ou bienhost:portadansFF_DATABASE_HOST - Apache avec
mod_rewrite— le.htaccessfait 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()etshell_exec()ne sont pas nécessaires : sur les hébergements qui les placent dansdisable_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 (convertd'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 deffMediaetffThumb: les sites installés via l'assistant chargent celles devendor/phpformsframework/, et nonff/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_SECRETetJC_AUTH_SALTsont uniques par installation (64 hex issus derandom_bytes). Régénérerconfig.remote.phpinvalide 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 :
| Constante | Effet |
|---|---|
JC_SITE_DOMAIN | le 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_UPLOAD | valeurs que hook.php ne fixe que si le config ne les a pas déjà définies (08 §4) |
JC_REGISTRATION_ENABLE | active/désactive l'inscription |
JC_USER_AREA_PATH | chemin de l'espace personnel (/area-utente n'est qu'un repli) |
ADMIN_TOOLBAR_HIDDEN | barre d'édition sur le front-end (par défaut true = masquée) |
AI_MD_ENABLED | version Markdown des contenus pour les LLM |
MOD_AUTH_COOKIE_SECURE, MOD_AUTH_COOKIE_SAMESITE | cookie de session (08 §6) |
SENTRY_DSN | suivi des erreurs (13 §4) |
AUTH_2FA | second facteur à la connexion : '' désactivé, email ou sms (08 §5bis). L'installeur l'écrit vide |
DEBUG_MODE, DISABLE_CACHE, CACHE_LAST_VERSION | cache 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.phpet se lisent avecjc_t('chiave', …)(marqueurssprintf) ;install/lib.php,install/icons.phpetinstall/cleanup.phppassent 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 cookiejc_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 DATABASEavec 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).
.htaccessgénéré à partir du domaine de l'assistant (jc_write_htaccess()), avec le domaine saisi dans toutes les conditionsHTTP_HOST(points échappés,www.et nu, sous-domainesmedia./static., CORS, cache statique), ancrées aux deux bouts pour que celles de l'hôte principal ne vaillent pas aussi pourmedia.(11 §5). Sans domaine connu → aucune contrainteHTTP_HOST, ainsi le site reste accessible.- Fichiers internes fermés au navigateur : juste après la redirection HTTPS, le
.htaccessrépond 404 aux PHP (et aux.sql,.log,.sh,.ini,.lock…) delibrary/,vendor/,ff/,conf/,applets/,contents/,cache/,uploads/,migrations/, à toutcache/logs/et, à la racine, àdatabase.sqlet aux.md. Apache sert de lui-même tout fichier qui existe (index.phpn'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 dansvendor/),cm/(showfiles.php,static.php,error.phpsont de vraies adresses),themes/(kcfinder) etmodules/: chaque module se protège lui-même, parce que le Package Manager ouvre/modules/<id>/installer/wizard.php. La condition surREDIRECT_STATUSlaisse passer les réécritures internes (/static→cm/static.php, l'ErrorDocument). - Durcissement :
install.lock,chmod 0640sur la config,install/cleanup.php(POST uniquement, seulement si la config existe) qui supprime récursivement/install.
⚠️ Le
.htaccessne 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.phpdéfinitWWW_LINK,WWW_LINK_ABSOLUTE,DOMAIN_PRODetLOCAL_DOMAINdans tous les cas, avec une comparaison de l'hôte tolérante au préfixewww.et au port. Les anciennes installations les définissaient dans unswitch ($_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 uneErrorfatale — page blanche, et non plus le warning avec repli sur le nom de PHP 7. Comme sur un sitehook.phppeut être plus ancien que le code qui le lit, le CMS ne le tient jamais pour acquis :library/gallery/common/set_header_page.phppasse parset_header_page_is_canonical_host()et par la gardedefined("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 écritdefine('JC_SITE_DOMAIN', 'esempio.it')dansconfig.remote.php, ethook.phple 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 denoindex). Jusqu'à la 3.0.3, l'installeur l'écrivait danshook.phpà la place du placeholder[DOMINIO], et chaque mise à jour, qui remplacehook.php, l'effaçait.hook.phpest désormais entièrement de la plateforme : ce qui appartient au site se trouve dans le config (valeurs) et danshook.local.php(code), que la mise à jour ne touche pas (10 §1). Avec un déploiement manuel, la ligneJC_SITE_DOMAINva dans le config avant d'envoyer le nouveauhook.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_PORT | connexion SSH ; hôte et utilisateur obligatoires |
DEPLOY_ROOT | docroot 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_PHP | le PHP CLI du conteneur du site, pour le contrôle de version final |
DEPLOY_URL, DEPLOY_SMOKE | smoke 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 controllamontre le bon propriétaire.
Les options
| Option | Effet |
|---|---|
controlla | diagnostic : 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 |
--vai | exécute |
--completo | tous les fichiers versionnés du HEAD (premier déploiement, ou réalignement) |
--rimuovi | supprime du serveur les fichiers retirés du dépôt (sans elle, ils restent où ils sont) |
--svuota-cache | vide 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 |
--forza | continue avec un working tree sale |
--niente-smoke | saute la vérification HTTP finale |
Ce qui ne voyage pas, et pourquoi
| Exclu | Pourquoi |
|---|---|
themes/*/conf/config.remote.php, config.local.php | identifiants BD et JC_APP_SECRET : on les modifie à la main sur le serveur |
.htaccess racine | en 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.sql | le 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 contientbin/.htaccessavecRequire 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/.htaccessavecRequire 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ôle | Ce 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
| Constante | Où | Quand on l'incrémente |
|---|---|---|
JC_VERSION | install/lib.php | à chaque paquet |
JC_SCHEMA_VERSION | install/lib.php | chaque 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
### Schemaseulement si N a changé : ce qui change, la migration dedocs/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 migrationsphp bin/update.php --file <pacchetto.zip> [--vai]: exécute la mise à jour depuis une archive ZIPphp bin/update.php --migrations-only [--vai]: n'exécute que les migrations de BD en attentephp 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.
- Géré dans
- Système de migrations (
migrations/) :- Migrations séquentielles
.sqlou.php(baseschema_0004_v302_baseline.php). - Suivi automatique dans la table
jc_migrations, géré parMigrationsRunner. 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.
- Migrations séquentielles
hook.phpethook.local.php(library/updater/JoeCmsUpdater.php) :hook.phpappartient à 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/) etbuild-zip.shle 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.jsonest 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_DOMAINet que l'ancienhook.phpa un domaine écrit ($jc_site_domain = "…"), l'updater le copie dans le config.
- Mode maintenance (
.maintenance) :- Géré par
cm/maintenance.phpen tête deindex.php. Répond503 Service Unavailable, avec un jeton de contournement pour l'administrateur. - Textes dans la langue du visiteur (préfixe de l'adresse ou navigateur) et
exitaprès la page, voir 13 §1bis.
- Géré par
- 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 avecmanifest.json, sans installeur ni dumps destructifs, qui préserve toujoursconfig.remote.php,uploads/,cache/et.htaccess.
6. Checklist de mise en ligne
- [ ] migrations appliquées et reportées dans
database.sql,JC_SCHEMA_VERSIONincré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.xmlmodifié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 : aucunSetEnv JC_DEBUG_ALLOWED 1resté allumé, voir 13 §2) - [ ]
CHANGELOG.mdmis à jour - [ ] chapitres de
docs/manuale/alignés (.githooks/manuale-check.shne 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 :
| Fichier | Périmètre |
|---|---|
MIGRAZIONE_PHP7_PHP8.md | migration et cas PHP 8 |
FIX_FUNZIONAMENTO.md | correctifs qui changent le comportement |
MIGLIORIE_ESTETICHE.md | interventions CSS/UI uniquement (marquées /* INTERVENTO CSS - GP AAAA-MM */) |
CHANGELOG.md | historique des versions |
PANORAMICA_JOECMS.md | architecture et histoire des décisions |
INSTALLER_PIANO.md, VGALLERY_NEXT_PIANO.md | plans de travail |
IGIENE_SEGRETI.md | gestion des secrets |
GUIDA_INDICIZZAZIONE_AI.md, GUIDA_SITEMAP.md | ré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 |