Actualizar Uptime Kuma de la versión 1 a la 2 con Docker, sin perder nada
Cómo pasé de Uptime Kuma 1.23 a 2.x: la copia previa que no te puedes saltar, la etiqueta correcta, cómo volver atrás y lo mismo con Portainer fuera del compose.
Uptime Kuma 2 trae bastantes mejoras (entre ellas, soporte para otras bases de datos y un montón de arreglos), pero es una versión mayor: cambia la estructura de la base de datos. Así que no vale con cambiar un número y rezar.
Así lo hice yo en la Raspberry Pi. Al final cuento cómo actualicé Portainer, que tiene su propia gracia porque no va en el compose.
1. Mira qué versión tienes
Antes de nada, apunta de dónde partes. Te hará falta si tienes que volver atrás:
docker inspect uptime-kuma --format '{{.Config.Image}}'
docker exec uptime-kuma node -e "console.log(require('./package.json').version)"
El primero te dice la etiqueta con la que lo lanzaste (por ejemplo louislam/uptime-kuma:1). El segundo, la versión exacta que está corriendo. Yo estaba en la 1.23. La versión también sale abajo del todo en la web, en Ajustes → Acerca de.
2. Copia de seguridad antes de nada
Kuma guarda todo (monitores, historial, notificaciones) en una carpeta de datos. Para la copia, para el contenedor primero, así no hay escrituras a medias:
docker compose stop uptime-kuma
tar czf ~/backup/uptime-kuma-antes-de-v2.tar.gz -C ~/servicios uptime-kuma
Comprueba que la copia se puede leer (un tar con errores no te salva de nada):
tar tzf ~/backup/uptime-kuma-antes-de-v2.tar.gz | head
La trampa del SQLite en modo WAL
Kuma usa SQLite en modo WAL. En ese modo, los cambios recientes no están en kuma.db, sino en kuma.db-wal hasta que se vuelcan. Si alguna vez copias la base de datos «en caliente» para consultarla, copia los tres archivos juntos:
kuma.db kuma.db-wal kuma.db-shm
Si copias solo kuma.db, te faltarán los últimos cambios y pensarás que algo se ha perdido. Con el contenedor parado, como arriba, no hay problema: copias la carpeta entera.
3. Cambiar la imagen
En el docker-compose.yml:
uptime-kuma:
image: louislam/uptime-kuma:2
Uso la etiqueta 2, no latest. Así recibo las actualizaciones de la versión 2, pero el día que salga una 3 no me la instala sin avisar.
docker compose pull uptime-kuma
docker compose up -d uptime-kuma
docker logs -f uptime-kuma
El primer arranque tarda más de lo normal: está migrando la base de datos. No lo interrumpas. En los registros verás el progreso de la migración; cuando termine, la web vuelve a responder. En una Raspberry Pi, con unos cuantos monitores y semanas de historial, ten paciencia.
4. Comprobar
- Entra en la web y revisa que están todos los monitores.
- Mira que el historial sigue ahí.
- Revisa las notificaciones y lanza una prueba.
5. Si sale mal: volver atrás
Aquí está la razón de ser de la copia. Volver a poner louislam/uptime-kuma:1 en el compose no basta: la base de datos ya está migrada y la versión 1 no la entiende. Hay que restaurar también los datos:
docker compose stop uptime-kuma
mv ~/servicios/uptime-kuma ~/servicios/uptime-kuma-v2-fallida
tar xzf ~/backup/uptime-kuma-antes-de-v2.tar.gz -C ~/servicios
# en el compose, vuelve a: image: louislam/uptime-kuma:1
docker compose up -d uptime-kuma
Fíjate en que no borro la carpeta de la versión 2: la renombro. Si luego resulta que el problema era otro, no he perdido nada.
Lo que se rompió: la librería de Python
Yo había creado los monitores por programa con una librería de Python no oficial que habla con la API de Kuma. Con Kuma 2 dejó de funcionar: la API interna cambió.
Si automatizas Kuma con scripts, compruébalo antes de actualizar. En mi caso, para consultar cosas «por detrás» ahora leo directamente la base de datos SQLite (copiando los tres archivos, como arriba), y los cambios los hago desde la web.
Bonus: Portainer, que no va en el compose
En mi Pi, Portainer está lanzado con un docker run suelto, no en el docker-compose.yml. Eso significa que no hay docker compose pull que valga: para actualizarlo hay que parar, renombrar y volver a lanzarlo con la etiqueta nueva. Así pasé de la 2.39.1 a la 2.45.1.
Primero, la copia del volumen de datos (con Portainer parado):
docker stop portainer
docker run --rm -v portainer_data:/data -v ~/backup:/backup alpine \
tar czf /backup/portainer_data-pre-2.45.1.tar.gz -C /data .
Luego, renombrar el viejo y lanzar el nuevo con los mismos puertos y volúmenes que tenía:
docker rename portainer portainer-viejo
docker run -d --name portainer --restart=always \
-p 8000:8000 -p 9443:9443 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v portainer_data:/data \
portainer/portainer-ce:2.45.1
Si no recuerdas con qué opciones lo lanzaste, docker inspect portainer-viejo te las dice (puertos en PortBindings, volúmenes en Mounts). Cuando compruebes que el nuevo funciona, borra el viejo con docker rm portainer-viejo. Si no funciona, paras el nuevo, le devuelves el nombre al viejo y lo arrancas: vuelves a estar como antes.
Aquí uso la versión exacta (
2.45.1) y no una etiqueta genérica, porque Portainer no se actualiza solo con unpull: decido yo cuándo subir.
Lo que no hay que hacer
- Actualizar sin copia «porque es solo una imagen». En una versión mayor, la imagen cambia los datos.
- Usar
latest: un día hacespullpara otra cosa y te salta una versión mayor sin enterarte. - Interrumpir la primera arrancada de Kuma 2 porque tarda. Es la migración.
- Borrar el contenedor o la carpeta antigua antes de comprobar que lo nuevo funciona.
Resumen
- Apunta tu versión actual.
- Para el contenedor, copia la carpeta de datos y comprueba la copia.
- Cambia a la etiqueta
2, no alatest, y deja que la migración termine. - Comprueba monitores, historial y avisos.
- Si sale mal, imagen antigua y datos antiguos.
- Si tienes scripts que usan su API, revisa que sigan funcionando.
Una actualización mayor con copia es un trámite de diez minutos. Sin copia, es una apuesta.
¿Te has quedado con la idea?
Tres preguntas rápidas. Cada acierto suma 10 XP.