Vai al contenuto
JoeCMS Scarica 3.1.5
Manuale · 14

Ambienti, installazione e deploy

Dove stanno le configurazioni, cosa cambia fra sviluppo e produzione, come si porta in linea una modifica e come si impacchetta una versione.

1. Requisiti d'esercizio

  • PHP ≥ 8.1 con mysqli, mbstring, json, curl, openssl (critici) e gd (consigliata)
  • MySQL 8 / MariaDB, anche col sql_mode strict di default (vedi 07). Porta non standard (Aiven, database gestiti): FF_DATABASE_PORT in config, che il wizard scrive da solo, oppure host:porta in FF_DATABASE_HOST
  • Apache con mod_rewrite — il .htaccess è parte integrante dell'architettura, non un accessorio: senza, il front controller non riceve nulla
  • scrivibilità di themes/site/conf/, uploads/, cache/ e della docroot (per il .htaccess)
  • exec() e shell_exec() non servono: sugli hosting che li mettono nelle disable_functions (molti dei condivisi, tutti i gratuiti) il sito gira lo stesso, perché la sintassi delle cache e dei job si verifica col parser di PHP (vendor/wolfgan/filemanager/services/fs_php.php, vendor/hcore/jobs/Jobs.php). Senza, mancano solo i programmi esterni: l'anteprima dei PDF (convert di ImageMagick, al suo posto l'icona) e gli ottimizzatori di immagini, CSS e JS che ffMedia::optimize() usa se li trova (jpegoptim, optipng, cssnano, uglifyjs…). La guardia sta in tutte e due le copie di ffMedia e ffThumb: i siti del wizard caricano quelle di vendor/phpformsframework/, non ff/classes/
  • se servono job: uno schedulatore (cron del pannello, via curl) — vedi 05
  • se serve un worker: accesso shell e systemd — non tutti gli hosting condivisi lo permettono

2. I due file di configurazione d'ambiente

themes/site/conf/config.local.php     sviluppo   (host che finisce in .local)
themes/site/conf/config.remote.php    produzione (scritto dall'installer, chmod 0640)

È HTTP_HOST a decidere quale viene caricato. Nessuno dei due è tracciato in git: nel repo ci sono solo i .dist. È qui che stanno i segreti — credenziali DB, SMTP, JC_APP_SECRET, JC_AUTH_SALT, SENTRY_DSN, chiavi dei provider. Vedi IGIENE_SEGRETI.md.

⚠️ JC_APP_SECRET e JC_AUTH_SALT sono unici per installazione (64 hex da random_bytes). Rigenerare config.remote.php invalida le sessioni e rende illeggibile tutto ciò che è stato cifrato con quel segreto. Il file va nel backup, e non si rigenera.

Costanti che un progetto tocca spesso:

CostanteEffetto
JC_SITE_DOMAINil dominio dell'installazione, da cui hook.php ricava DOMAIN_PROD e WWW_LINK (vedi il riquadro in §3). La scrive l'installer
AREA_SEO_SHOW_MODIFY, AREA_PUBLISHING_SHOW_PREVIEW, MOD_SEC_PROFILING, MAX_UPLOADvalori che hook.php fissa solo se il config non li ha già definiti (08 §4)
JC_REGISTRATION_ENABLEaccende/spegne la registrazione
JC_USER_AREA_PATHpercorso dell'area personale (/area-utente è solo un fallback)
ADMIN_TOOLBAR_HIDDENbarra di modifica sul frontend (default true = nascosta)
AI_MD_ENABLEDversione Markdown dei contenuti per gli LLM
MOD_AUTH_COOKIE_SECURE, MOD_AUTH_COOKIE_SAMESITEcookie di sessione (08 §6)
SENTRY_DSNerror tracking (13 §4)
AUTH_2FAsecondo fattore al login: '' spento, email o sms (08 §5bis). L'installer la scrive vuota
DEBUG_MODE, DISABLE_CACHE, CACHE_LAST_VERSIONcache degli asset (12)

3. Prima installazione: il wizard

Il guard è in config.php: se l'host non finisce in .local e manca config.remote.php, include install/index.php ed esce. La sola presenza del config disattiva il wizard.

Dieci step: requirements → database → application → billing → localization → admin → registration → layout → services → done. Il dettaglio è in PANORAMICA_JOECMS.md §7 e in INSTALLER_PIANO.md.

Le parti che contano operativamente:

  • Interfaccia in quattro lingue (IT, EN, ES, FR). Tutti i testi del wizard, messaggi d'errore compresi, stanno nel dizionario di install/i18n.php e si leggono con jc_t('chiave', …) (segnaposto sprintf); anche install/lib.php, install/icons.php e install/cleanup.php passano da lì. Alla prima visita la lingua viene da Accept-Language (la supportata con il q più alto; inglese se non ce n'è nessuna), poi resta in sessione e nel cookie jc_install_lang. Il selettore in alto a destra apre ?step=<step>&lang=xx: il controller salva la scelta e reindirizza senza parametro, così i POST successivi non ripetono il cambio (i dati non inviati del form corrente si perdono). La lingua dell'installer è la lingua predefinita del sito: finché lo step localization non è stato inviato è anche l'unica attiva; dopo, cambiare lingua sposta la predefinita e la aggiunge a quelle scelte. Lo step localization resta l'ultima parola. La lingua fa da default anche per fuso orario e nazione. Una stringa nuova si aggiunge al dizionario in tutte e quattro le lingue, con gli stessi segnaposto.
  • CREATE DATABASE con fallback graceful: se l'hosting la nega, il wizard dice "crealo dal pannello" e ritenta la sola connessione. Degrada, non si blocca.
  • Invio email di prova durante l'installazione: la posta si verifica prima di finire. La Cifratura va scelta in coppia con la porta — SSL/TLS con 465, STARTTLS con 587, nessuna con 25 — ed è la stessa che finisce in A_SMTP_SECURE: una coppia sbagliata dà un timeout, e l'errore suggerisce quella giusta. La password lasciata vuota mantiene quella già inserita.
  • Step services: consenso cookie, Sentry e le credenziali dei provider di notifica — JoeSMTP e Twilio per gli SMS (con il mittente, senza il quale non partono), OneSignal per il push. Finiscono nell'area Servizi, non nel config; si possono lasciare vuote e inserire dopo (06 §4).
  • .htaccess generato dal dominio del wizard (jc_write_htaccess()), con il dominio inserito in tutte le condizioni HTTP_HOST (punti escapati, www. e nudo, sotto-domini media./static., CORS, cache statica), ancorate ai due lati perché quelle dell'host principale non valgano anche per media. (11 §5). Senza dominio noto → nessun vincolo HTTP_HOST, così il sito resta raggiungibile.
  • File interni chiusi al browser: subito dopo il redirect HTTPS il .htaccess risponde 404 ai PHP (e a .sql, .log, .sh, .ini, .lock…) di library/, vendor/, ff/, conf/, applets/, contents/, cache/, uploads/, migrations/, a tutto cache/logs/ e, alla radice, a database.sql e ai .md. Apache serve da sé ogni file che esiste (index.php scatta solo per gli altri): fino alla 3.1.0 chiunque scaricava i log del CMS e il dump, ed eseguiva i PHP che il CMS include e basta. Restano aperti i file statici (CKEditor sta in vendor/), cm/ (showfiles.php, static.php, error.php sono indirizzi veri), themes/ (kcfinder) e modules/: ogni modulo si protegge da sé, perché il Package Manager apre /modules/<id>/installer/wizard.php. La condizione su REDIRECT_STATUS lascia passare le riscritture interne (/static → cm/static.php, l'ErrorDocument).
  • Hardening: install.lock, chmod 0640 sul config, install/cleanup.php (solo POST, solo se il config esiste) che cancella ricorsivamente /install.

⚠️ Il .htaccess non viaggia nello ZIP. Il file tracciato in git conteneva i domini di sviluppo, e il guard "non sovrascrivo se esiste" lo lasciava intatto → sito morto. Lo genera l'installer.

⚠️ Le costanti del dominio si leggono sempre con defined(). hook.php definisce WWW_LINK, WWW_LINK_ABSOLUTE, DOMAIN_PROD e LOCAL_DOMAIN in ogni condizione, col confronto host tollerante su prefisso www. e porta. Le installazioni vecchie le definivano dentro una switch ($_SERVER["HTTP_HOST"]): servito su un host diverso da quello elencato non definivano nulla, e su PHP 8 leggere una costante inesistente è un Error fatale — pagina bianca, non più il warning col fallback sul nome di PHP 7. Siccome su un sito hook.php può essere più vecchio del codice che lo legge, il CMS non lo dà mai per scontato: library/gallery/common/set_header_page.php passa da set_header_page_is_canonical_host() e dal gate defined("DOMAIN_PROD"). Stessa regola per gli applet e per il codice di sito.

⚠️ Il dominio sta nel config, non in hook.php. L'installer scrive define('JC_SITE_DOMAIN', 'esempio.it') in config.remote.php, e hook.php lo legge da lì; senza, si assume produzione e i link si costruiscono dall'host della richiesta (su uno staging niente noindex). Fino alla 3.0.3 l'installer lo scriveva dentro hook.php al posto del segnaposto [DOMINIO], e ogni aggiornamento, che sostituisce hook.php, lo cancellava. hook.php ora è tutto della piattaforma: ciò che è del sito sta nel config (valori) e in hook.local.php (codice), che l'aggiornamento non tocca (10 §1). Con un deploy a mano, la riga JC_SITE_DOMAIN va aggiunta al config prima di caricare il nuovo hook.php.

4. Deploy: portare in linea il ramo attivo

Rigenerare il pacchetto a ogni fix è troppo lento, e l'upload a file singoli dal client FTP è il modo più efficace di rompere un sito in esercizio: in produzione resta un misto di versioni — hook.php vecchio con un modulo nuovo dà Fatal error — e quella combinazione non esiste in nessun commit, quindi non la si riproduce in locale.

Il CMS porta con sé lo strumento che evita tutto questo: bin/deploy.sh, che carica via SSH l'HEAD del ramo git su cui sei, e solo i file cambiati dall'ultimo deploy.

cp bin/deploy.conf.example bin/deploy.conf    # una volta per installazione
./bin/deploy.sh controlla                     # chi sono sul server, dov'è la docroot, a che commit è
./bin/deploy.sh                               # prova a vuoto: elenca cosa caricherebbe
./bin/deploy.sh --vai                         # carica davvero

Il primo giro, su un sito nato dal wizard o da upload manuali, va fatto per intero — non corrisponde a nessun commit, e l'incrementale non saprebbe da dove partire:

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

Se la shell risponde permission denied: ./bin/deploy.sh, il file ha perso il permesso di esecuzione (succede copiandolo a mano, da un client FTP, da Windows o in un repository con core.fileMode=false, oppure in un progetto nuovo nato copiando i file di cms). Lo si lancia una volta con bash: lo script si accorge di aver perso il bit, lo rimette su disco e nell'indice di git, e da lì basta un commit perché non si perda più al prossimo checkout:

bash bin/deploy.sh controlla
git commit -m "bin/deploy.sh eseguibile" bin/deploy.sh

Come sa da dove ripartire

A fine deploy scrive il commit sul server in $HOME/.joecms-deploy-rev-<sito>: nella home dell'utente SSH, non nella docroot, perché non deve essere raggiungibile dal web. Il suffisso col nome del sito serve quando sullo stesso server, con lo stesso utente (spesso root), stanno più installazioni: con un file solo ogni deploy ripartirebbe dal commit di un altro sito.

Si deploya sempre l'HEAD: i file modificati e non committati non partono, e nemmeno quelli mai aggiunti a git — lo script li elenca prima di muoversi, e se hai chiesto --vai con il working tree sporco si ferma.

Configurazione

Sta in bin/deploy.conf, che è fuori da git: è per-installazione e per-macchina. Nel repo c'è solo bin/deploy.conf.example.

Un sito con più ambienti (produzione, staging) tiene un file per ciascuno, bin/deploy.<ambiente>.conf, e lo sceglie con --ambiente:

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

Con --ambiente il file deve esistere: lo script non ripiega su bin/deploy.conf, che vorrebbe dire deployare sull'ambiente sbagliato. Conviene che il file di difetto sia lo staging, così la produzione si raggiunge solo chiedendola per nome.

ChiaveA cosa serve
DEPLOY_HOST, DEPLOY_USER, DEPLOY_PORTconnessione SSH; obbligatorie host e utente
DEPLOY_ROOTdocroot vista da SSH — lo stesso valore di FF_DISK_PATH in config.remote.php
DEPLOY_CHOWN'utente:gruppo' del sito, obbligatoria se entri come root
DEPLOY_PHPil PHP CLI del container del sito, per il controllo di versione finale
DEPLOY_URL, DEPLOY_SMOKEsmoke test HTTP di fine deploy; su un sito multilingua, una pagina per lingua

⚠️ Deploy come root senza DEPLOY_CHOWN: i file caricati restano di root e con suexec o suPHP il sito risponde 500 su tutto. Lo script si rifiuta di partire, e l'avviso non è aggirabile con --forza. ./bin/deploy.sh controlla mostra il proprietario giusto.

Le opzioni

OpzioneEffetto
controlladiagnostica: utente, docroot trovata da sola, binari PHP con mysqli/mbstring, permessi di cache/ e uploads/, commit registrato
(nessuna)prova a vuoto — non tocca il server
--vaiesegue
--completotutti i file versionati dell'HEAD (primo deploy, o riallineamento)
--rimuovicancella dal server i file rimossi dal repo (senza, restano dove sono)
--svuota-cachesvuota cache/ sul server, tenendo cache/logs/ e cache/.thumbs/
--da <sha>parte da un commit indicato a mano invece che da quello registrato
--solo <path>limita a un sottoalbero
--forzaprocede con il working tree sporco
--niente-smokesalta la verifica HTTP finale

Cosa non viaggia, e perché

EsclusoPerché
themes/*/conf/config.remote.php, config.local.phpcredenziali DB e JC_APP_SECRET: si toccano a mano sul server
.htaccess di radicein produzione è quello generato dall'installer col dominio vero; sovrascriverlo con quello di sviluppo spegne il sito
install/l'installer è già stato rimosso da install/cleanup.php: rimetterlo online è solo superficie in più
database.sqllo schema non si applica mai per copia di file
cache/contenuto generato dal sito
docs/, tests/, *.md di lavoro, .idea/, .claude/, .githooks/materiale di sviluppo; docs/sql pubblicato sarebbe un invito a leggersi le migration
modules/*/tests/i collaudi dei moduli: distruttivi sul database che gli si passa, e sul server non servono

Quando una di queste cose cambia e la modifica deve comunque arrivare in produzione, lo script lo dice invece di caricarla di nascosto: elenca le migration di docs/sql/ ricordando che vanno applicate prima del codice (il codice nuovo su schema vecchio fa SHOW COLUMNS e si spegne da solo; il codice vecchio su schema nuovo no), le define() nuove comparse in config.remote.php.dist, e le modifiche al .htaccess.

La cache

Template, contenuti e asset passano dalla cache su disco: caricati e basta, il sito continua a servire la versione vecchia. Se il deploy tocca applets/, contents/ o themes/<tema>/{layouts,contents,css,javascript} lo script lo segnala e si aggiunge --svuota-cache, che pulisce cache/ lasciando cache/logs/ (il diario degli errori, la prima cosa da guardare se qualcosa si è rotto) e senza ricreare la cartella, così i permessi restano quelli buoni. Lascia anche cache/.thumbs/, le copie delle immagini che media.<dominio> serve così come sono: cancellarle tutte insieme è un'ondata di rigenerazioni, e con un .htaccess che manda a index.php anche le richieste di media. sono 500 su ogni immagine (11 §5). Su un sito multilingua qui c'è anche cache/locale.php, l'istantanea delle lingue attive.

⚠️ Con opcache.revalidate_freq alto sul server la cache va svuotata dopo, non subito. PHP ricontrolla la data di un file già compilato al più ogni revalidate_freq secondi (default 2): con un valore come 60, nel primo minuto dopo il caricamento può ancora eseguire la versione vecchia di un file usato da poco, mentre i template li legge già nuovi dal disco. Le pagine rigenerate in quel minuto — anche dalla verifica finale dello script — escono col codice vecchio, o col template nuovo e il PHP vecchio, e la cache di pagina le tiene per ore. Con un valore alto si svuota cache/ a mano quando quel tempo è passato (lo script, se non c'è niente da caricare, esce senza toccarla), oppure si riavvia PHP-FPM del sito prima di svuotarla.

Le correzioni al .htaccess generato (dal wizard, jc_write_htaccess() in install/lib.php, o dal modello del vecchio installer, conf/gallery/install/.htaccess-cms.tpl) non arrivano ai siti già installati, perché quel file non viaggia: vanno riportate a mano, come per il sotto-dominio media. (11 §5). Dopo la 3.1.0 sono due: il blocco dei file interni (§3) e ExpiresByType text/html "access plus 0 seconds" (12); le righe esatte sono in jc_write_htaccess() e jc_htaccess_static_tail(), e dalla 3.1.1 anche nei tre modelli conf/gallery/install/.htaccess-*.tpl del vecchio installer.

La verifica finale

Lo smoke test gira dal tuo computer, non dal server: chiama le rotte via HTTP come farebbe un browser, ed è il controllo che intercetta il file dimenticato. Con DEPLOY_SMOKE si elencano i percorsi; su un sito multilingua se ne mette uno per lingua, ed è così che si scopre la lingua rimasta indietro. Se il progetto ha tests/run.php con tests/smoke.config.php, lo script usa quella suite invece delle chiamate curl.

Restano a mano

Migration SQL, costanti nuove in config.remote.php, .htaccess, cron del pannello.

Un'installazione con schema < 4 va allineata una volta, prima di caricare il codice della 1.6.0: il codice nuovo scrive NULL nelle date vuote, che uno schema 3 rifiuta anche su un server non strict (#1048), mentre lo schema 4 regge anche il codice 1.5.x. Si carica il solo bin/db-allinea-schema.php, lo si lancia a vuoto e poi con --vai, e solo dopo si fa il deploy. Per quel file va bene scp, non deploy.sh --solo: registra come caricato tutto l'HEAD, e il deploy successivo non porterebbe il resto.

E, solo la prima volta, i permessi delle cartelle scrivibili:

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

bin/ non deve essere raggiungibile dal web: nel pacchetto c'è bin/.htaccess con Require all denied. Su nginx la regola va replicata nella configurazione del server.

5. Pacchetto e versioni

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

Impacchetta i file tracciati da git nello stato del working tree (non git archive, che ignorerebbe le modifiche non committate), ed esclude: config d'ambiente (restano i .dist), .htaccess di sviluppo, docs/ (tranne il manuale), i *.md di root, gli hook di sviluppo (.githooks/, .claude/), i source map, le directory di test/doc/example dei vendor. Svuota cache/ e di uploads/ tiene solo loghi.

Eccezioni alla regola "niente markdown": CHANGELOG.md e docs/manuale/ (dalla 1.3.0), che viaggiano col pacchetto.

Eccezione alla regola "niente script shell": bin/ — deploy.sh e deploy.conf.example — viaggia anch'esso. È con quello che il sito appena installato si aggiorna da lì in avanti (§4), e bin/.htaccess lo tiene fuori dal web. Le verifiche di fine build lo controllano per presenza, e cercano gli altri .sh, che nella docroot non ci fanno nulla.

Lo script verifica da sé che non finiscano segreti nel pacchetto e che seed, installer, changelog e capitoli del manuale siano presenti.

Il manuale nel pacchetto è un'istantanea

Il manuale che arriva su un sito descrive la versione installata su quel sito e non si aggiorna quando il CMS principale va avanti: la versione successiva porta il proprio. La build:

  • antepone a ogni capitolo una riga con versione e data del pacchetto;
  • aggiunge docs/manuale/VERSIONE.txt (versione, data, commit di origine);
  • mette i file in sola lettura;
  • scrive docs/.htaccess con Require all denied: il manuale descrive l'interno della piattaforma (percorsi, trappole) e non va servito al pubblico. Si legge dallo ZIP o via FTP/pannello. Su nginx la regola va replicata nella configurazione del server.

Il manuale si aggiorna col codice (solo nel repo principale)

Nel repository del CMS il manuale segue il codice in automatico. .githooks/manuale-check.sh confronta i file modificati con i percorsi che ogni capitolo cita tra backtick — la mappa file → capitolo non è scritta a mano, si ricava dal manuale stesso — ed elenca i capitoli toccati ma non aggiornati.

Punto di controlloCosa fa
Hook Stop di Claude Code (.claude/settings.json)a fine turno, se ci sono capitoli da rivedere, ferma la chiusura e fa aggiornare il manuale; ogni coppia capitolo/file si segnala una volta per contenuto (.git/manuale-ack)
Hook git pre-commit (.githooks/pre-commit)sui file in stage blocca una volta per coppia capitolo/file e contenuto (.git/manuale-ack-commit): se il manuale non va toccato, basta ripetere lo stesso commit. MANUALE_WARN_ONLY=1 lo riduce a un avviso
A mano.githooks/manuale-check.sh sul working tree; --commit <sha> su un commit già fatto

L'hook git va attivato una volta per clone: git config core.hooksPath .githooks. Per tenere affidabile la mappa, nei capitoli i file si citano per percorso, tra backtick. Il numero di riga attaccato (library/gallery/system/cache.php:957) è tollerato. Due regole fisse completano la mappa: le migration di docs/sql/ vanno al capitolo 07, e hook.php, citato in quasi tutti i capitoli, conta per un capitolo solo se la modifica tocca una funzione che quel capitolo nomina (per esempio registerUser()).

⚠️ Il controllo protegge solo le modifiche che passano da lui. L'hook Stop vede solo le modifiche non committate di una sessione di Claude Code in questo repository. Il pre-commit blocca invece di limitarsi ad avvisare perché i client grafici (Sourcetree, PhpStorm) mostrano l'output di un hook solo quando fallisce: finché si limitava ad avvisare, un lavoro portato da un altro progetto e committato subito (è successo con la preferenza di lingua) è arrivato senza manuale e senza che nessuno lo vedesse. Un commit fatto con Bypass commit hooks in Sourcetree, o con --no-verify, salta il controllo: in quel caso si lancia dopo .githooks/manuale-check.sh --commit <sha>.

Versionamento

CostanteDoveQuando si incrementa
JC_VERSIONinstall/lib.phpa ogni pacchetto
JC_SCHEMA_VERSIONinstall/lib.phpogni volta che cambia database.sql

Le modifiche si annotano in CHANGELOG.md sotto [Non rilasciato] mano a mano, e diventano la sezione della versione quando si crea il pacchetto (build-zip.sh avvisa se la sezione della versione in build non c'è).

Lo schema nel CHANGELOG: cosa legge joecms.it

La pagina Download e il changelog di joecms.it ricavano dal CHANGELOG.md del pacchetto se una versione cambia lo schema del database, e in quel caso avvisano che prima del codice vanno applicate le migration. Per il sito lo schema di una versione è il primo numero in grassetto (una cifra) entro 40 caratteri dalla parola «schema», cercato nel riepilogo e poi nell'intestazione; una versione senza numero eredita quello della precedente; una versione cambia lo schema se ha il gruppo ### Schema o un numero diverso dalla precedente. La sezione di un rilascio quindi:

  • porta in intestazione ## [X.Y.Z] — AAAA-MM-GG · schema **N**, con N = JC_SCHEMA_VERSION;
  • ha il gruppo ### Schema solo se N è cambiato: cosa cambia, la migration di docs/sql/ e l'ordine, prima lo schema e poi il codice (§4);
  • nel riepilogo non nomina in grassetto un altro schema prima di N, perché il sito leggerebbe quello.

Lo verifica .githooks/changelog-schema.php, che legge la sezione come il sito e la confronta con JC_SCHEMA_VERSION, con lo schema del rilascio precedente (quello di install/lib.php al commit che ha portato JC_VERSION a quel numero) e con database.sql, righe vuote e commenti -- esclusi. build-zip.sh si ferma se non torna. Il pre-commit fa lo stesso controllo sul commit di rilascio, cioè quello che cambia JC_VERSION, e non sugli altri: durante lo sviluppo JC_SCHEMA_VERSION può già salire mentre la sezione della versione corrente dichiara ancora lo schema con cui è uscita. A mano: php .githooks/changelog-schema.php [versione], oppure --commit <sha> su un commit già fatto.

⚠️ Il numero è di una cifra perché così lo legge JoeSitoChangelog::versione() nel progetto del sito: lo schema 10 va prima insegnato al sito, e fino ad allora la build si ferma. Nella storia la regola è saltata una volta: la 1.0.5 ha aggiunto a database.sql le righe di ff_international dei testi di logout e registrazione, lasciando lo schema a 2.

Aggiornamenti automatici e Migrazioni (dalla v3.0.2)

JoeCMS include un motore integrato (library/updater/JoeCmsUpdater.php) per aggiornare siti già in esercizio in modo automatico, sicuro e non distruttivo.

  • CLI (bin/update.php):
    • php bin/update.php --status: diagnostica ambiente e stato migrazioni
    • php bin/update.php --file <pacchetto.zip> [--vai]: esegue l'aggiornamento da archivio ZIP
    • php bin/update.php --migrations-only [--vai]: esegue solo le migrazioni DB pendenti
    • php bin/update.php --maintenance on|off: attiva/disattiva la modalità manutenzione
  • Backend Web (/restricted/updater):
    • Gestione in conf/gallery/manage/updater/index.php con stato di salute, caricamento ZIP, console log in tempo reale e allineamento database.
  • Sistema di Migrazioni (migrations/):
    • Migrazioni sequenziali .sql o .php (baseline schema_0004_v302_baseline.php).
    • Tracciamento automatico nella tabella jc_migrations gestito da MigrationsRunner.
    • schema_0005_testi_multilingua.php (schema 5) porta nel dizionario i testi del banner cookie, delle email dell'account e del recupero password: finché manca, quei testi escono come codici (svc_cookie_title). L'updater la esegue da sé nella stessa operazione, a sito in manutenzione. Con un deploy a mano si carica prima il file della migrazione, si eseguono le migrazioni (php bin/update.php --migrations-only --vai, o le migrazioni pendenti in /restricted/updater, conf/gallery/manage/updater/index.php) e solo dopo il resto del codice.
  • hook.php e hook.local.php (library/updater/JoeCmsUpdater.php):
    • hook.php è della piattaforma e l'aggiornamento lo sostituisce; prima, il backup ne tiene una copia, così un ripristino lo riporta indietro con il resto.
    • hook.local.php, il codice del sito, sta nella lista protetta (con il config, .htaccess, uploads/) e build-zip.sh lo toglie dal pacchetto. Protetti anche i file PWA che l'installer genera per il sito (manifest.json, site.webmanifest, browserconfig.xml): nel pacchetto di aggiornamento manifest.json è il file dei metadati, e fino alla 3.0.3 finiva al posto del manifest del sito.
    • Una volta sola, prima di estrarre i file: se il config non ha JC_SITE_DOMAIN e il vecchio hook.php ha un dominio scritto ($jc_site_domain = "…"), l'updater lo copia nel config.
  • Modalità Manutenzione (.maintenance):
    • Gestita da cm/maintenance.php in cima a index.php. Risponde 503 Service Unavailable con token di bypass per l'amministratore.
    • Testi nella lingua del visitatore (prefisso dell'indirizzo o browser) e exit dopo la pagina, vedi 13 §1bis.
  • Due pacchetti di build (build-zip.sh):
    • joecms-<versione>.zip: pacchetto completo da scompattare per una nuova installazione.
    • joecms-update-<versione>.zip: pacchetto leggero con manifest.json, senza installer né dump distruttivi, che preserva sempre config.remote.php, uploads/, cache/ e .htaccess.

6. Checklist di messa in linea

  • [ ] migration applicate e riportate in database.sql, JC_SCHEMA_VERSION bumpata
  • [ ] lint PHP pulito su tutti i file toccati
  • [ ] marker dei template verificati (nessuno con spazi, nessuno perso)
  • [ ] routing_table.xml modificati effettivamente saliti (non danno errore: semplicemente non succede niente)
  • [ ] caricamento fatto con ./bin/deploy.sh --vai, non a mano (niente misto di versioni)
  • [ ] cache/ svuotata dopo il caricamento (--svuota-cache)
  • [ ] cron schedulati e verificati (una riga nel log per ciascuno)
  • [ ] webhook configurati presso i provider, con il secret giusto
  • [ ] email: invio di prova reale, non solo l'anteprima
  • [ ] robots.txt, sitemap.xml, canonical: coerenti col dominio di produzione
  • [ ] ?__debug__ non lascia trapelare nulla a un utente qualunque (chiuso per difetto: nessun SetEnv JC_DEBUG_ALLOWED 1 rimasto acceso, vedi 13 §2)
  • [ ] CHANGELOG.md aggiornato
  • [ ] capitoli di docs/manuale/ allineati (.githooks/manuale-check.sh non segnala nulla)

7. Documenti "vivi" del repo

La conoscenza sta accanto al codice, non nei ticket. Vanno aggiornati a ogni intervento:

FilePiano
MIGRAZIONE_PHP7_PHP8.mdmigrazione e casistica PHP 8
FIX_FUNZIONAMENTO.mdfix che cambiano il comportamento
MIGLIORIE_ESTETICHE.mdinterventi solo CSS/UI (marcati /* INTERVENTO CSS - GP AAAA-MM */)
CHANGELOG.mdstoria delle versioni
PANORAMICA_JOECMS.mdarchitettura e storia delle decisioni
INSTALLER_PIANO.md, VGALLERY_NEXT_PIANO.mdpiani di lavoro
IGIENE_SEGRETI.mdgestione dei segreti
GUIDA_INDICIZZAZIONE_AI.md, GUIDA_SITEMAP.mddefault riusabili per indicizzazione e sitemap
docs/manuale/questo manuale: cosa la piattaforma permette — controllato in automatico, vedi §5