Migrazione Moodle 3 → 4 → 5: checklist tecnica

La migrazione da Moodle 3.x a Moodle 4.x è la più comune che gestiamo. Moodle 3.11 è uscito dal supporto esteso, e molte organizzazioni sono ancora su versioni 3.9 o 3.11 che non riceveranno più patch di sicurezza.

Questa non è una guida teorica: è il processo che seguiamo quando prendiamo in carico una migrazione per un cliente. Adattatela al vostro contesto.

Perché non si salta da 3 a 5 in un colpo solo

Moodle ha un processo di upgrade incrementale. Lo script admin/cli/upgrade.php gestisce solo upgrade a versione immediatamente successiva. Saltare step porta a corruzione dati o errori fatali nel database.

Il percorso corretto per un'installazione su Moodle 3.9:

3.9 → 3.11 → 4.1 (LTS) → 4.5 (LTS) → 5.x (quando stabile)

Ogni freccia è un upgrade separato, testato in staging prima di applicarlo in produzione. Non è possibile comprimere questi step — il database schema cambia in modo incrementale tra versioni adiacenti.

Una nota sulle LTS (Long Term Support): Moodle ha un ciclo di release di 6 mesi, ma le versioni LTS (attualmente 4.1 e 4.5) ricevono bugfix e patch di sicurezza per 3 anni. Quando pianificate la migrazione, puntate sempre a una versione LTS come destinazione intermedia.

Pre-flight: l'inventario dei plugin è il passo più critico

Questa è la fase che determina quanto durerà la migrazione. Prima di toccare qualsiasi cosa:

# Esporta la lista di tutti i plugin installati con versione
php admin/cli/upgrade.php --non-interactive 2>&1 | head -5
 
# Oppure, direttamente dal database:
mysql -u moodle_user -p moodle_db -e "
  SELECT plugin, version, release
  FROM mdl_config_plugins
  WHERE name = 'version'
  ORDER BY plugin;"

Per ogni plugin nella lista, verificate:

1. Plugin directory Moodle.org: ha una versione per Moodle 4.x? Quando è stata rilasciata?
2. Plugin custom (sviluppati internamente): il codice usa API deprecate in Moodle 4? (vedi lista deprecations in docs.moodle.org/dev/Moodle_4.0_release_notes)
3. Plugin commerciali: il vendor ha rilasciato aggiornamenti? Il contratto di licenza include gli aggiornamenti?

I plugin che più frequentemente causano problemi nella migrazione a Moodle 4:

• Plugin che usano $PAGE->requires->js() senza moduli AMD
• Plugin che usano l'API di theming di Moodle 2.x/3.x (deprecated)
• Plugin con renderer HTML hardcoded senza usare i template Mustache
• Plugin che modificano direttamente le tabelle mdl_user o mdl_course via SQL custom

Migration test in staging: il processo step-by-step

Avere un ambiente di staging identico a produzione è non negoziabile. Se non avete già una copia di staging aggiornata, createla prima di fare qualsiasi altra cosa.

# 1. Dump completo del database di produzione
mysqldump -u root -p --single-transaction moodle_prod > moodle_prod_backup_$(date +%Y%m%d).sql
 
# 2. Copia moodledata (file uploads, cache)
rsync -av --progress /var/moodledata/ /var/moodledata_staging/
 
# 3. Abilita maintenance mode su staging
php /var/www/moodle/admin/cli/maintenance.php --enable
 
# 4. Upgrade a versione successiva
php /var/www/moodle/admin/cli/upgrade.php --non-interactive
 
# 5. Verifica errori nel log
tail -100 /var/www/moodle/admin/cli/upgrade.log

Ripetete i passi 3-5 per ogni versione intermedia. Dopo ogni upgrade, eseguite il check dei plugin:

php /var/www/moodle/admin/cli/upgrade.php --non-interactive --allow-unstable 2>&1 | grep "plugin"

Qualsiasi plugin che mostra FAILED o requires una versione superiore di Moodle deve essere aggiornato o disabilitato prima di procedere.

Performance regression dopo upgrade: cosa monitorare

Moodle 4.x ha introdotto cambiamenti significativi al sistema di caching e al motore di template (Mustache). Le performance regression più comuni che osserviamo:

Query lente sul database. Moodle 4 ha aggiunto indici su alcune tabelle critiche, ma alcune query personalizzate nei plugin custom possono diventare più lente per via di cambiamenti nello schema. Abilitate $CFG->debugsqltrace in staging e monitorate le query che superano i 100ms.

Cache invalidation massiva al primo load. Al primo avvio dopo la migrazione, Moodle invalida tutta la cache. Le prime 30 minuti di produzione post-upgrade vedono load elevato sul server. Pianificate la finestra di upgrade in orario di basso traffico e precalcolate la cache con:

php admin/cli/purge_caches.php && php admin/cli/rebuild_course_cache.php

Consumo di memoria PHP aumentato. I template Mustache in Moodle 4 consumano più memoria per i corsi con molte attività. Se avete memory_limit = 128M in php.ini, portatelo a minimo 256M prima dell'upgrade.

Differenze chiave tra Moodle 3, 4 e 5

Rollback plan: cosa fare se qualcosa va storto

Ogni migrazione in produzione deve avere un rollback testato prima dell'upgrade. Il rollback di Moodle non è banale — non si può tornare a una versione precedente applicando uno script automatico.

Il processo di rollback che usiamo:

1. Ripristino del database. Avere il dump completo del database di produzione pre-upgrade, pronto per il ripristino in meno di 15 minuti. Per database grandi, tenere il dump su storage locale (non solo cloud) per velocità di accesso.

2. Versioning del codice. Il codice Moodle in produzione deve essere su git (o almeno in un tar.gz datato). Rollback = git checkout o estrazione dell'archivio.

3. Test del rollback in staging. Prima di fare la migrazione in produzione, testate il rollback in staging: fate l'upgrade, poi ripristinate il database e riportate il codice alla versione precedente. Verificate che tutto funzioni. Se il rollback non funziona in staging, non fate la migrazione in produzione.

# Script rollback (da avere pronto, non da scrivere sotto pressione)
#!/bin/bash
set -e
 
echo "=== Avvio rollback Moodle ==="
php /var/www/moodle/admin/cli/maintenance.php --enable
 
echo "Ripristino database..."
mysql -u root -p moodle_prod < /backup/moodle_prod_backup_YYYYMMDD.sql
 
echo "Ripristino codice..."
cd /var/www
tar -xzf /backup/moodle_code_YYYYMMDD.tar.gz
 
echo "Purge cache..."
php /var/www/moodle/admin/cli/purge_caches.php
 
php /var/www/moodle/admin/cli/maintenance.php --disable
echo "=== Rollback completato ==="

Per scenari di hosting Moodle e le considerazioni infrastrutturali per la migrazione, leggi il nostro approfondimento su Moodle hosting. Per i plugin custom che potrebbero necessitare di porting durante la migrazione, leggi l'articolo su plugin Moodle vs sviluppo custom.

La documentazione ufficiale delle release notes è disponibile su docs.moodle.org/dev/Releases.

Conclusione: tre punti da portare via

1. Il pre-flight sui plugin è il 70% del lavoro. Una migrazione che fallisce quasi sempre fallisce per un plugin non compatibile scoperto a metà dell'operazione.

2. Mai saltare versioni intermedie. Il percorso 3.9 → 3.11 → 4.1 → 4.5 non è opzionale — è l'unico percorso supportato.

3. Il rollback plan va testato prima dell'upgrade, non dopo. Un rollback che non è stato testato non è un rollback — è una speranza.

Ti serve la checklist tecnica completa che usiamo internamente per le migrazioni Moodle? Scrivi a info@coodle.it: te la mandiamo in PDF, senza form di mezzo.