Backup, plugin, requisiti di PHP e database, traduzioni, temi e firewall: la checklist prima, durante e dopo per aggiornare Moodle senza fermare la didattica.
Perché un aggiornamento di Moodle può andare storto
Moodle 5.2 è uscito ad aprile 2026 e la 5.3, la prossima versione LTS (Long Term Support), è prevista per ottobre 2026. Per molti amministratori è il momento di pianificare un aggiornamento. Sulla carta è un'operazione documentata e ripetibile; in pratica i problemi raramente arrivano dal core di Moodle. Arrivano da tutto ciò che sta intorno: plugin aggiuntivi, temi commerciali, traduzioni personalizzate, configurazione del server, integrazioni con altri sistemi.
In questa guida raccogliamo le lezioni apprese in aggiornamenti reali, organizzate in una checklist "prima, durante, dopo" e in una tabella dei problemi più frequenti con sintomo e soluzione. L'obiettivo è semplice: arrivare al giorno dell'aggiornamento sapendo già cosa può rompersi.
Prima: backup e ambiente di staging
Il primo punto non è negoziabile: un backup completo e verificato. In Moodle "completo" significa tre componenti distinte, che vanno salvate tutte e nello stesso momento.
Cosa salvare:
- Database: un dump coerente, eseguito con l'opzione single-transaction (per MariaDB e MySQL con tabelle InnoDB), così da ottenere una fotografia consistente senza bloccare il sito.
- moodledata: la cartella con file caricati, cache, language pack e dati dei plugin. Senza di essa il database da solo non basta.
- Codice: l'intera cartella di Moodle, compreso config.php e tutti i plugin aggiuntivi installati.
Il secondo punto è lo staging: una copia del sito di produzione su cui provare l'aggiornamento prima di toccare il sito vero. Clonare database e moodledata, aggiornare la copia e testarla è il modo più economico per scoprire i problemi. Ogni insidia descritta in questo articolo si può intercettare in staging.
Prima: plugin, compatibilità e pacchetti dei temi
Se aggiorni il core via git, seguendo il branch stabile della versione (ad esempio MOODLE_502_STABLE per la 5.2), tieni presente un punto che sorprende spesso: i plugin aggiuntivi non sono nel repository di Moodle. Il comando git aggiorna il core, ma ogni plugin di terze parti va aggiornato a parte, scaricando la versione corretta.
Come verificare la compatibilità:
- Fai un inventario dei plugin aggiuntivi (Amministrazione del sito, Plugin, Panoramica plugin, filtro "Aggiuntivi").
- Per ciascuno, controlla sul Plugins directory di moodle.org quali versioni di Moodle sono dichiarate supportate.
- Considera che alcuni sviluppatori dichiarano il supporto in ritardo: un plugin può funzionare ma non essere ancora certificato. In questi casi va testato con attenzione in staging, oppure conviene aspettare.
- Identifica i plugin non più mantenuti e valuta alternative o la dismissione.
Un'attenzione particolare va ai temi commerciali. Spesso il pacchetto acquistato contiene, oltre al tema, anche alcuni plugin accessori in più versioni, pensate per Moodle diversi. L'errore tipico è installare quella con il numero di versione più alto credendo sia la più recente, quando in realtà è destinata a un altro ramo di Moodle. Leggi sempre la documentazione del pacchetto e verifica il campo dei requisiti nel file version.php del plugin.
Prima: requisiti di PHP e database
Ogni versione di Moodle alza i requisiti minimi dell'ambiente. Moodle 5.2 richiede PHP 8.3, e per la 5.3 è già annunciato MariaDB 11.4 come versione minima. Prima di pianificare l'aggiornamento controlla la pagina di verifica dell'ambiente (Amministrazione del sito, Server, Ambiente) e le release notes della versione di destinazione.
Aggiornare PHP è di solito gestibile. Aggiornare il database è un'altra storia, soprattutto su server condivisi con altri siti: WordPress, gestionali o applicazioni che usano lo stesso server di database potrebbero non essere pronti per la nuova versione. In questi casi l'aggiornamento del database è un progetto a sé, con un proprio piano di test e di backup, da affrontare prima e separatamente dall'aggiornamento di Moodle.
Prima: traduzioni personalizzate
Molte piattaforme modificano le stringhe dell'interfaccia: "Corso" diventa "Percorso", "Docente" diventa "Formatore" e così via. Il punto critico è dove vengono salvate queste modifiche.
La regola da seguire:
- Le personalizzazioni vanno in moodledata/lang/it_local, oppure si gestiscono con lo strumento Personalizzazione lingua di Moodle, che scrive proprio lì.
- Mai modificare i file del language pack in moodledata/lang/it: vengono sostituiti quando il pacchetto lingua si aggiorna.
- Mai modificare le cartelle lang dentro i plugin: vengono sovrascritte a ogni aggiornamento del plugin.
Prima di aggiornare, verifica dove si trovano le personalizzazioni esistenti e, se necessario, spostale in it_local.
Durante: modalità manutenzione e aggiornamento da CLI
Il giorno dell'aggiornamento conviene lavorare da riga di comando. È più affidabile del browser, non subisce timeout del web server e mostra chiaramente eventuali errori.
- 1Attiva la modalità manutenzione con lo script admin/cli/maintenance.php e l'opzione di attivazione.
- 2Esegui un ultimo backup di database, moodledata e codice.
- 3Aggiorna il codice del core (git o pacchetto ufficiale) e sostituisci i plugin aggiuntivi con le versioni compatibili già testate in staging.
- 4Lancia admin/cli/upgrade.php e leggi con attenzione l'output: avvisi e errori vanno risolti, non ignorati.
- 5Controlla le impostazioni nuove o modificate che l'aggiornamento propone.
- 6Esegui i test essenziali con il sito ancora in manutenzione (gli amministratori possono accedere).
- 7Disattiva la modalità manutenzione solo quando i test sono superati.
Dopo: cache, cron e integrazioni
Un aggiornamento non finisce quando lo script termina. La fase di verifica è quella in cui emergono i problemi che gli utenti noterebbero il giorno dopo.
Controlli post-aggiornamento:
- Svuota tutte le cache (Amministrazione del sito, Sviluppo, Svuota tutte le cache, oppure lo script CLI purge_caches.php).
- Verifica che il cron giri regolarmente e controlla le attività pianificate, comprese quelle fallite.
- Controlla web service e token: le integrazioni esterne, come le iscrizioni automatiche ai corsi dopo un acquisto su e-commerce, devono continuare a funzionare. Fai un acquisto di prova end-to-end.
- Testa i flussi principali: login, iscrizione, accesso a un corso, consegna di un compito, svolgimento di un quiz, invio di email e notifiche.
- Controlla il catalogo corsi e la homepage del tema, non solo le pagine interne.
Le insidie meno ovvie: tema, date e firewall
Alcuni problemi non producono errori: semplicemente qualcosa sparisce o smette di salvarsi. Sono i più insidiosi perché li segnalano gli utenti, non i log.
Impostazioni del tema con nuovi default. Dopo l'aggiornamento un tema può introdurre impostazioni con valori predefiniti diversi. Un caso tipico è il set di icone impostato su una versione "minimal": le icone non incluse nel set ridotto spariscono dalle pagine che le usavano. Confronta le impostazioni del tema prima e dopo.
Date di fine corso. Alcuni temi nascondono dal catalogo i corsi con data di fine nel passato. Se dopo l'aggiornamento il catalogo sembra vuoto, controlla le date di fine dei corsi prima di cercare un bug.
Page builder dei temi. Se il tema include un editor visuale per homepage e pagine, verifica che i contenuti esistenti si carichino correttamente nell'editor prima di salvare: salvare un editor caricato a metà può sovrascrivere la pagina. Distingui sempre tra bozza e versione pubblicata.
Firewall applicativo. Un firewall come ModSecurity può imporre limiti alla dimensione delle richieste. Salvataggi grandi, come una pagina complessa del page builder o un modulo con molti campi, vengono bloccati con un errore 400. La soluzione è alzare il limite in modo mirato per gli URL interessati, non disattivare il firewall.
Problemi frequenti: sintomo e soluzione
| Problema | Sintomo | Soluzione |
|---|---|---|
| Plugin non aggiornato insieme al core | Errore di versione o plugin mancante durante l'upgrade | Scaricare la versione compatibile dal Plugins directory e sostituirla |
| Plugin del tema per un Moodle diverso | Errori o funzioni rotte dopo l'installazione | Usare la versione indicata per il proprio ramo di Moodle, non quella con il numero più alto |
| Requisiti di ambiente non soddisfatti | La verifica ambiente blocca l'aggiornamento | Aggiornare PHP o database, pianificando a parte i server condivisi |
| Traduzioni nel language pack | Le stringhe personalizzate tornano quelle originali | Spostarle in moodledata/lang/it_local o nella Personalizzazione lingua |
| Set di icone ridotto | Icone sparite da pagine e menu | Ripristinare il set di icone completo nelle impostazioni del tema |
| Corsi con data di fine passata | Corsi assenti dal catalogo | Aggiornare le date di fine o le impostazioni del catalogo |
| Page builder caricato male | Contenuti persi dopo il salvataggio | Verificare il caricamento prima di salvare, ripristinare la versione pubblicata |
| Limite richieste del firewall | Errore 400 al salvataggio | Alzare il limite in modo mirato per gli URL interessati |
| Integrazioni interrotte | Iscrizioni automatiche non eseguite | Verificare web service, token e attività pianificate |
Aggiornamenti gestiti da ITN
Aggiornare Moodle è un'attività che richiede metodo più che coraggio: inventario, staging, test, e una lista precisa di cose da controllare. ITN gestisce piattaforme Moodle dal 2004 e si occupa di aggiornamenti completi: analisi di plugin e temi, adeguamento dell'ambiente server, aggiornamento in staging e in produzione, verifica delle integrazioni e assistenza nei giorni successivi.
Stai pianificando il passaggio a Moodle 5.2 o vuoi preparare la piattaforma in vista della 5.3 LTS? Contattaci per una consulenza gratuita di 30 minuti: analizziamo insieme la tua installazione e ti indichiamo cosa serve per aggiornare senza sorprese.
Ti è piaciuto questo articolo?
Contattaci per una consulenza gratuita sul tema trattato.
Prenota una consulenza gratuita
