Cómo actualizar Moodle 5.1 a 5.2 sin romper producción

La versión corta

Actualizar Moodle 5.1 a 5.2 suele ser tranquilo cuando el servidor está preparado antes de tocar el código. Los fallos que parecen misteriosos después de la actualización suelen venir de cinco sitios: el directorio public introducido en Moodle 5.1, la configuración del router, las dependencias de Composer, plugins que todavía esperan rutas antiguas y cachés que no se regeneraron bien.

No lo trates como una sustitución de archivos. Trátalo como un despliegue controlado: clona producción, revisa requisitos, mueve plugins con intención, ejecuta la actualización en un entorno de pruebas y repite los mismos pasos en producción.

Por qué Moodle 5.2 está pillando a tanta gente

El foro Installing and Upgrading Help de Moodle.org está lleno de síntomas de Moodle 5.x: checks de router fallando, menús desaparecidos, imágenes rotas, cajas de subida que se quedan cargando, problemas en bancos de preguntas, Class "Mustache_Engine" not found y errores de Composer.

No son seis problemas aislados. Moodle 5.1 movió el código web a public y añadió el router al camino de las peticiones. Moodle 5.2 elevó requisitos como PHP 8.3 y exige venir desde Moodle 4.4 o posterior. Las notas de Moodle 5.2 y la guía de actualización son la fuente de verdad.

Antes de tocar producción

Prepara una lista con servidor, código y datos.

El objetivo no es hacer papeleo. Es que la actualización sea aburrida.

1. Comprueba el camino de actualización

En el sitio actual, ve a Administración del sitio > Servidor > Entorno y cambia la versión objetivo a Moodle 5.2. Corrige todos los avisos antes de empezar.

Moodle 5.2 solo acepta actualización desde Moodle 4.4 o posterior. Si estás en 4.3, 4.2 o anterior, actualiza primero a una versión intermedia soportada.

Comprueba también extensiones como sodium, intl, mbstring, soap, zip y fileinfo.

2. Haz copia de las tres cosas reales

Copia el código Moodle, el directorio moodledata y la base de datos. Una copia solo de archivos no es un plan de vuelta atrás. Los archivos de cursos viven en moodledata; los registros de aprendizaje viven en la base.

En producción, hazlo en modo mantenimiento o en una ventana tranquila. Si cron está corriendo, espera a que terminen las tareas activas.

3. Sustituye el código limpiamente

No copies Moodle 5.2 encima del directorio antiguo. Aparta el código viejo, descomprime la versión nueva y copia solo lo que corresponde.

mv moodle moodle.backup
tar xvzf moodle-latest-5.2.tgz
cp moodle.backup/config.php moodle/

Después copia plugins ya verificados en las rutas correctas de Moodle 5.x. Muchos deben vivir bajo public.

cp -pr moodle.backup/theme/mytheme moodle/public/theme/mytheme
cp -pr moodle.backup/mod/mymod moodle/public/mod/mymod

Si usas Git, sigue la guía Git for Administrators y apunta a la rama estable correcta.

4. Trata los plugins como bloqueantes

Que una carpeta se copie no significa que el plugin sea compatible.

Si aparece Class "Mustache_Engine" not found, sospecha de un tema o plugin que llama al nombre antiguo de Mustache.

5. Apunta el servidor web a public

Desde Moodle 5.1, la raíz web debe ser el directorio public, no la carpeta padre.

Apache:

DocumentRoot /var/www/moodle/public
 
<Directory /var/www/moodle/public>
    AllowOverride None
    Require all granted
</Directory>

Nginx:

root /var/www/moodle/public;

En cPanel o hosting compartido quizá necesites un subdominio, symlink o alias. Si tu host no permite nada de eso, el problema no es Moodle: es que el plan no te da el control que Moodle 5.x necesita.

Para ese tema, lee ¿Puede Moodle 5.2 funcionar en hosting compartido?.

6. Configura el router

El router envía peticiones que no corresponden a un archivo real hacia r.php.

Apache:

FallbackResource /r.php

Nginx:

try_files $uri $uri/ /r.php$is_args$args;

Si Moodle dice que una ruta .php falsa devuelve 404 en vez de 302, consulta Moodle 5.2: el router no está configurado correctamente.

7. Instala dependencias Composer

Si aparece Composer vendor directory not found, ejecuta Composer desde la raíz Moodle, no desde public.

composer install --no-dev --classmap-authoritative

Si tu hosting no tiene Composer o shell, construye el artefacto en otro sitio y sube el árbol completo con vendor. El diagnóstico completo está en Moodle: Composer vendor directory not found.

8. Ejecuta la actualización y purga cachés

En producción, mejor CLI:

php admin/cli/upgrade.php

Después purga:

Administración del sitio > Desarrollo > Purgar todas las cachés

Si el selector de archivos sigue girando, lee el selector de archivos de Moodle se queda cargando tras actualizar a 5.2.

Prueba los flujos reales

No des la actualización por terminada porque carga el dashboard. Prueba login, administración, páginas de curso, edición, subidas, entrega de tareas, cron, plugins e integraciones.

FAQ

¿Puedo actualizar directamente de Moodle 5.1 a 5.2?

Sí. Moodle 5.2 soporta actualización desde Moodle 4.4 o posterior.

¿Debo mover la raíz web a public?

Sí, si no se hizo ya al pasar a Moodle 5.1.

¿Navegador o CLI?

Usa CLI en producción cuando puedas. Evita timeouts de navegador, proxy y servidor web.