Guía Completa de Uptime Kuma con Docker

Si tienes un servidor doméstico, un NAS o un pequeño laboratorio tecnológico, sabrás que un contenedor puede aparecer como activo y, aun así, ofrecer un servicio que no responde. Esperar hasta descubrir el problema manualmente significa acumular interrupciones y, en algunos casos, enterarse demasiado tarde de una caída.

Uptime Kuma permite detectar estos fallos desde un panel centralizado y autoalojado. En esta guía nos centraremos exclusivamente en cómo instalar Uptime Kuma con Docker, conservar sus datos, acceder al panel y actualizar el contenedor sin perder la configuración.

Qué necesitas para instalar Uptime Kuma con Docker

Uptime Kuma es una aplicación de monitorización autoalojada que puede ejecutarse en cualquier equipo compatible con Docker. Puedes instalarla en un servidor con Ubuntu o Debian, un mini-PC, una Raspberry Pi compatible o determinados modelos de NAS.

Antes de comenzar, necesitas:

• Un equipo con Docker Engine instalado y funcionando.
• El complemento Docker Compose, incluido actualmente en la mayoría de instalaciones modernas de Docker.
• Un puerto disponible en el servidor, normalmente el 3001.
• Una carpeta o volumen local donde conservar la configuración.
• Acceso a una terminal con permisos para administrar contenedores.

Puedes comprobar que Docker y Compose están disponibles ejecutando:

docker --version
docker compose version

Si ambos comandos devuelven una versión y no muestran errores, puedes continuar con el despliegue.

Cómo preparar la carpeta persistente de Uptime Kuma

Aunque el contenedor puede eliminarse y crearse de nuevo, la configuración de Uptime Kuma debe conservarse fuera de él. Para hacerlo, crearemos una carpeta dedicada y montaremos un directorio local en /app/data, que es la ruta utilizada por la aplicación para guardar sus datos.

En Linux puedes preparar la estructura con estos comandos:

mkdir -p ~/uptime-kuma/data
cd ~/uptime-kuma

Dentro de data quedarán almacenados los usuarios, monitores, notificaciones y demás ajustes. Por tanto, no debes borrar esta carpeta al actualizar el contenedor.

También conviene evitar que esta ruta se encuentre en una unidad NFS. El proyecto advierte que este sistema de archivos no está soportado para /app/data, por lo que es preferible utilizar un disco local o un volumen administrado por Docker.

Cómo crear el archivo Docker Compose de Uptime Kuma

Dentro de la carpeta uptime-kuma, crea un archivo llamado compose.yaml con este contenido:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: always
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data

Esta configuración utiliza la rama estable 2 de Uptime Kuma, publica el panel en el puerto 3001 y guarda los datos en la carpeta que acabamos de preparar.

Antes de iniciar el servicio, comprueba que la sintaxis del archivo sea válida:

docker compose config

Si el comando muestra la configuración procesada sin errores, ya puedes descargar la imagen y crear el contenedor:

docker compose up -d

Docker ejecutará Uptime Kuma en segundo plano y lo iniciará automáticamente después de reiniciar el servidor.

Alternativa rápida mediante Docker Run

Si no quieres utilizar un archivo Compose, también puedes desplegar Uptime Kuma con el comando oficial de Docker Run:

docker run -d \
  --restart=always \
  -p 3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma \
  louislam/uptime-kuma:2

En este caso, los datos se guardan en el volumen administrado por Docker llamado uptime-kuma. Es una opción válida para una prueba rápida, aunque Docker Compose facilita considerablemente las actualizaciones y el mantenimiento posterior.

No utilices simultáneamente Docker Run y Docker Compose con el mismo nombre de contenedor o puerto, porque ambos despliegues entrarían en conflicto.

Cómo acceder al panel de Uptime Kuma

Para abrir el panel desde el propio servidor, introduce esta dirección en el navegador:

http://localhost:3001

Si accedes desde otro dispositivo conectado a la misma red, sustituye localhost por la dirección IP del servidor:

http://192.168.1.50:3001

Durante el primer acceso tendrás que seleccionar el idioma y crear la cuenta de administrador. Utiliza una contraseña única y suficientemente robusta, ya que esta cuenta controla todos los monitores y canales de notificación.

No expongas directamente el puerto 3001 a Internet. Para acceder desde fuera de casa, lo adecuado es utilizar una VPN, un túnel seguro o un proxy inverso protegido mediante HTTPS.

Cómo comprobar que Uptime Kuma funciona correctamente

Puedes comprobar el estado del contenedor mediante:

docker compose ps

El servicio debería aparecer como activo. Si el panel no carga o el contenedor se reinicia continuamente, consulta sus últimos mensajes:

docker compose logs --tail=100 uptime-kuma

También puedes comprobar desde la terminal que el puerto responde:

curl -I http://127.0.0.1:3001

Una vez validada la instalación, ya puedes monitorizar una página web con Uptime Kuma. La configuración detallada de Telegram, SMTP y otros canales debe tratarse por separado para no mezclar la instalación con la gestión de alertas.

Cómo actualizar Uptime Kuma sin perder los datos

Antes de actualizar, es recomendable detener el servicio y hacer una copia de la carpeta persistente:

docker compose stop uptime-kuma
cp -a data "data-backup-$(date +%F-%H%M)"

Después puedes descargar la imagen más reciente de la rama configurada y recrear el contenedor:

docker compose pull
docker compose up -d

Finalmente, comprueba el estado y revisa los registros:

docker compose ps
docker compose logs --tail=100 uptime-kuma

Docker sustituirá el contenedor anterior, pero conservará la información porque la carpeta local continúa montada en /app/data. Si vas a realizar una actualización entre versiones mayores, revisa previamente las notas de la versión y conserva una copia completa de los datos.

Errores frecuentes al instalar Uptime Kuma con Docker

Uno de los errores más habituales es encontrar el mensaje port is already allocated. Esto significa que otra aplicación está utilizando el puerto 3001. Puedes cambiar únicamente el puerto del host en el archivo Compose:

ports:
  - "3002:3001"

Después accederás mediante http://IP_DEL_SERVIDOR:3002. El puerto interno debe seguir siendo el 3001.

Si Uptime Kuma muestra el asistente inicial después de una actualización, normalmente significa que el volumen persistente no está montado correctamente. Revisa que la ruta termine exactamente en /app/data y que estés ejecutando Compose desde la carpeta adecuada.

Los errores permission denied indican que el contenedor no puede escribir en la carpeta data. Comprueba los permisos del directorio. En distribuciones con SELinux, como Fedora o determinadas instalaciones de Red Hat, puede ser necesario utilizar este montaje:

volumes:
  - ./data:/app/data:Z

Si el panel funciona mediante localhost pero no desde otro equipo, revisa el firewall del servidor y confirma que has utilizado 3001:3001. Una asignación como 127.0.0.1:3001:3001 limita deliberadamente el acceso al propio servidor.

También debes evitar guardar los datos en una ruta NFS. Si necesitas realizar copias en un NAS, mantén primero la base de datos activa en almacenamiento local y copia posteriormente la carpeta de respaldo al servidor de red.

Si la instalación funciona pero las pruebas de aviso fallan, el problema ya no pertenece al despliegue del contenedor. En ese caso, conviene revisar específicamente por qué Uptime Kuma no envía notificaciones, comprobando credenciales, conectividad, SMTP, webhooks y registros del servicio.

Instalar Uptime Kuma mediante Docker permite disponer de un panel de monitorización autoalojado sin modificar directamente el sistema operativo. Una configuración basada en Docker Compose, almacenamiento local persistente y copias de seguridad antes de actualizar proporciona un despliegue sencillo, recuperable y fácil de mantener.