Etiqueta: Docker Compose

Introducción

Cuando administramos un Home Server, no basta con instalar aplicaciones y comprobar que funcionan correctamente. También necesitamos saber si nuestros servicios continúan disponibles, si responden correctamente y cuándo ocurre algún problema.

Imaginemos que tenemos varios servicios funcionando en nuestro servidor: Jellyfin, Nextcloud, WordPress, Home Assistant o incluso una página web alojada en Internet.

¿Qué sucede si alguno deja de funcionar mientras no estamos en casa? ¿Cómo podemos saber si nuestro sitio web está disponible o si un contenedor Docker se ha detenido inesperadamente?

Para solucionar este problema existe Uptime Kuma, una herramienta de monitorización de código abierto que nos permite supervisar servicios, servidores, páginas web y diferentes dispositivos desde un único panel de control.

En este artículo veremos qué es Uptime Kuma, cuáles son sus funcionalidades, cómo instalarlo utilizando Docker Compose y cómo configurarlo para monitorear los servicios de nuestro Home Server.

1. ¿Qué es Uptime Kuma?

Uptime Kuma es una herramienta de monitorización autohospedada (self-hosted), diseñada para comprobar la disponibilidad de servicios y dispositivos de red.

Su principal característica es ofrecer un panel de control desde el cual podemos visualizar el estado de nuestros servicios, consultar tiempos de respuesta, identificar interrupciones y recibir notificaciones cuando algo deja de funcionar.

A diferencia de algunas plataformas comerciales de monitorización, Uptime Kuma puede instalarse directamente en nuestro propio servidor, por lo que mantenemos el control sobre su configuración y los datos de monitorización.

Su interfaz gráfica permite administrar los monitores sin necesidad de escribir comandos constantemente.

2. ¿Para qué sirve Uptime Kuma?

Uptime Kuma permite supervisar prácticamente cualquier servicio que podamos comprobar mediante una conexión de red o un mecanismo compatible.

Algunos ejemplos de uso son:

• Comprobar si una página web está disponible.
• Verificar que un servidor responde a solicitudes HTTP o HTTPS.
• Supervisar puertos TCP de aplicaciones y servidores.
• Comprobar la conectividad de dispositivos mediante Ping.
• Monitorear contenedores Docker.
• Verificar registros DNS.
• Supervisar certificados SSL y sus fechas de expiración.
• Recibir notificaciones cuando un servicio deja de responder.
• Publicar páginas de estado para mostrar la disponibilidad de nuestros servicios.

Por ejemplo, podemos configurar un monitor para comprobar que nuestro sitio web responde correctamente cada cierto intervalo.

Si el sitio deja de responder, Uptime Kuma registra el incidente y puede enviarnos una notificación.

De esta manera podemos identificar problemas sin tener que comprobar manualmente cada aplicación.

3. Principales funcionalidades

Monitorización HTTP y HTTPS

Permite comprobar la disponibilidad de páginas web y aplicaciones accesibles mediante HTTP o HTTPS.

Podemos configurar la URL que queremos supervisar y establecer los códigos de respuesta HTTP que consideramos válidos.

También permite comprobar certificados SSL para identificar cuándo se aproxima su fecha de expiración.

Monitorización TCP

Permite comprobar si un puerto específico de un servidor está aceptando conexiones.

Por ejemplo, podemos supervisar:

• Puerto 22: SSH.
• Puerto 80: HTTP.
• Puerto 443: HTTPS.
• Puerto 3001: Uptime Kuma.

Esta funcionalidad es útil para comprobar que determinados servicios continúan escuchando en sus puertos correspondientes.

Monitorización mediante Ping

Permite comprobar si un dispositivo responde a solicitudes ICMP.

Podemos utilizarlo para supervisar:

• Routers.
• Switches.
• Servidores.
• Computadoras.
• Impresoras de red.
• Otros dispositivos conectados a nuestra infraestructura.

Es importante recordar que un dispositivo puede bloquear ICMP y seguir funcionando correctamente. Por eso, un resultado negativo de Ping no siempre significa que el dispositivo esté completamente fuera de servicio.

Monitorización de contenedores Docker

Una de las funcionalidades más interesantes para quienes utilizamos Docker es la posibilidad de supervisar directamente nuestros contenedores.

Uptime Kuma puede conectarse al motor Docker y comprobar el estado de los contenedores seleccionados.

Esto permite visualizar si un contenedor está ejecutándose o si ha dejado de estar disponible.

Para utilizar esta funcionalidad necesitamos proporcionar acceso al socket de Docker, algo que veremos durante la instalación.

Sistema de notificaciones

Uptime Kuma permite configurar diferentes mecanismos para recibir alertas cuando ocurre algún incidente.

Entre las integraciones disponibles encontramos:

• Telegram.
• Discord.
• Slack.
• Gotify.
• Correo electrónico mediante SMTP.
• Pushover.
• Otros servicios compatibles.

Esto permite recibir notificaciones sin necesidad de mantener abierto el panel de monitorización.

Páginas públicas de estado

Otra funcionalidad interesante es la posibilidad de crear páginas de estado.

Estas páginas permiten mostrar la disponibilidad de determinados servicios sin necesidad de proporcionar acceso al panel administrativo.

Podemos utilizarlas para informar a otras personas si nuestros servicios están funcionando correctamente o si existe alguna interrupción.

4. Requisitos previos

Para instalar Uptime Kuma utilizando Docker necesitamos:

• Un servidor Linux con Docker Engine.
• Docker Compose.
• Acceso administrativo al servidor.
• Conexión a Internet para descargar la imagen.
• Espacio de almacenamiento para conservar la configuración y el historial de monitorización.

En este tutorial utilizaremos Ubuntu Server y Docker Compose.

5. Instalación de Uptime Kuma con Docker Compose

La instalación mediante Docker Compose permite mantener la configuración organizada y facilita las tareas de mantenimiento.

Paso 1. Crear el directorio de instalación

Nos conectamos al servidor mediante SSH y creamos el directorio donde almacenaremos los archivos de configuración:

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

Paso 2. Crear el archivo Docker Compose

Creamos el archivo:

nano docker-compose.yml

Agregamos la siguiente configuración:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: always

    ports:
      - "3001:3001"

    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock

Explicación de los parámetros:

image: especifica la imagen Docker que utilizaremos. En este caso, la rama principal de Uptime Kuma 2.

container_name: establece el nombre del contenedor.

restart: permite que el contenedor vuelva a iniciarse automáticamente cuando sea necesario.

ports: publica el puerto 3001 del contenedor en el servidor.

./data:/app/data: conserva la información de Uptime Kuma fuera del ciclo de vida del contenedor.

/var/run/docker.sock: permite que Uptime Kuma se comunique con el motor Docker para supervisar contenedores.

Paso 3. Iniciar el servicio

Ejecutamos:

docker compose up -d

Comprobamos que el contenedor se encuentre funcionando:

docker ps --filter name=uptime-kuma

También podemos consultar su estado de salud:

docker inspect uptime-kuma \
  --format '{{.State.Status}} | {{if .State.Health}}{{.State.Health.Status}}{{else}}sin healthcheck{{end}}'

Paso 4. Acceder a la interfaz web

Abrimos nuestro navegador y utilizamos la siguiente dirección:

http://IP-DE-TU-SERVIDOR:3001

Por ejemplo:

http://192.168.8.10:3001

En el primer inicio tendremos que completar el asistente de configuración y crear nuestra cuenta administrativa.

Una vez finalizado este proceso, tendremos acceso al panel principal de Uptime Kuma.

Nota: si queremos publicar Uptime Kuma mediante un proxy inverso o Cloudflare Tunnel, debemos configurar correctamente el acceso y proteger el panel administrativo. No es recomendable exponerlo directamente a Internet.

6. Cómo configurar nuestro primer monitor

Una vez dentro de Uptime Kuma, podemos comenzar a supervisar nuestros servicios.

Para crear un monitor:

1. Seleccionamos la opción para agregar un nuevo monitor.
2. Elegimos el tipo de monitorización.
3. Asignamos un nombre descriptivo.
4. Introducimos la dirección IP, dominio o URL correspondiente.
5. Configuramos el intervalo de comprobación.
6. Guardamos los cambios.

Por ejemplo, podemos crear un monitor HTTP(s) para comprobar nuestro sitio web:

Parámetro	Ejemplo
Tipo	HTTP(s)
Nombre	Sitio web
URL	https://dotbugs.com
Intervalo	60 segundos
Reintentos	Según necesidad

Una vez guardado, Uptime Kuma comenzará a realizar comprobaciones periódicas.

El panel mostrará el estado actual, el tiempo de respuesta y el historial de disponibilidad.

También podemos crear monitores TCP para comprobar puertos específicos y monitores Ping para verificar la conectividad de nuestros dispositivos.

7. Cómo supervisar contenedores Docker

Si utilizamos Docker para administrar nuestras aplicaciones, podemos aprovechar la integración de Uptime Kuma con Docker.

Primero debemos asegurarnos de que el contenedor tenga acceso al socket:

/var/run/docker.sock

En nuestra instalación ya tenemos configurado este volumen en Docker Compose.

Después, desde Uptime Kuma:

1. Entramos en Settings.
2. Buscamos la configuración de Docker Hosts.
3. Agregamos un nuevo Docker Host.
4. Seleccionamos la conexión mediante socket local.
5. Indicamos la ruta del socket Docker.
6. Guardamos la configuración.

Una vez establecida la conexión, podemos crear un nuevo monitor de tipo Docker Container y seleccionar el contenedor que queremos supervisar.

Por ejemplo, podemos monitorear:

• Jellyfin.
• Nextcloud.
• WordPress.
• Home Assistant.
• Watchtower.

Esto nos permite centralizar la supervisión de nuestros servicios Docker desde una sola interfaz.

Consideración de seguridad: montar el socket Docker proporciona un acceso muy elevado al servidor. Aunque se monte como un volumen de solo lectura, eso no convierte automáticamente la API de Docker en una API de solo lectura. Debemos proteger el acceso administrativo a Uptime Kuma y evitar exponerlo públicamente sin controles adicionales.

8. Configurar notificaciones

Una de las ventajas de Uptime Kuma es que no necesitamos estar revisando constantemente el panel para detectar problemas.

Podemos configurar notificaciones para recibir alertas cuando un monitor cambia de estado.

Para hacerlo:

1. Entramos en Settings.
2. Seleccionamos Notifications.
3. Agregamos un nuevo mecanismo de notificación.
4. Introducimos los parámetros necesarios.
5. Ejecutamos una prueba de conexión.
6. Guardamos la configuración.

Por ejemplo, podemos integrar Telegram para recibir mensajes cuando un servicio deja de responder y cuando vuelve a estar disponible.

También podemos asociar una misma configuración de notificaciones a varios monitores.

Esto resulta especialmente útil cuando tenemos numerosos servicios funcionando en nuestro Home Server.

9. Consultar registros y diagnosticar problemas

Como Uptime Kuma funciona dentro de Docker, podemos consultar sus registros directamente desde la terminal.

Para visualizar los últimos registros:

docker logs --tail 100 uptime-kuma

Para observarlos en tiempo real:

docker logs -f uptime-kuma

También podemos comprobar el estado del contenedor:

docker inspect uptime-kuma \
  --format '{{.State.Status}}'

Si necesitamos reiniciar el servicio:

cd ~/docker/uptime-kuma
docker compose restart

Y para comprobar que el puerto responde localmente:

curl -I http://127.0.0.1:3001

Estos comandos son útiles para identificar problemas de inicio, conectividad o funcionamiento del contenedor.

10. Respaldos y buenas prácticas

Uptime Kuma almacena su información en el directorio /app/data, que en nuestra instalación está vinculado a un directorio persistente del servidor.

Aquí se conserva información importante como:

• Configuración de la aplicación.
• Monitores creados.
• Historial de monitorización.
• Datos de la base de datos.
• Configuración de notificaciones.

Por este motivo, debemos realizar respaldos periódicos del directorio de datos.

Algunas recomendaciones:

Realizar respaldos consistentes.

Antes de copiar los archivos de datos, es recomendable detener temporalmente el contenedor o utilizar un procedimiento de respaldo consistente con la base de datos. No debemos asumir que copiar únicamente el archivo SQLite mientras la aplicación está escribiendo garantiza una copia válida.

Proteger la cuenta administrativa.

Utilizar una contraseña segura y habilitar la autenticación de dos factores cuando esté disponible.

No exponer el socket Docker.

El socket proporciona un acceso privilegiado al motor Docker. Debemos limitar quién puede acceder a Uptime Kuma.

Configurar intervalos razonables.

No todos los servicios necesitan comprobarse con la misma frecuencia. Podemos adaptar los intervalos según la importancia de cada aplicación.

Utilizar notificaciones.

Un sistema de monitorización es mucho más útil cuando recibimos alertas oportunamente.

Supervisar desde una ubicación independiente.

Si Uptime Kuma y los servicios monitorizados se encuentran en el mismo servidor, una caída completa del servidor también puede dejar sin funcionamiento al sistema de monitorización. Para una supervisión más completa, podemos instalar una segunda instancia en otro equipo o servidor.

11. Conclusión

Uptime Kuma es una excelente alternativa para quienes queremos tener mayor visibilidad sobre los servicios que administramos en nuestro Home Server.

Su interfaz sencilla, las diferentes opciones de monitorización, la integración con Docker y el sistema de notificaciones permiten identificar problemas de disponibilidad sin depender de comprobaciones manuales.

Además, al ser una herramienta autohospedada, podemos ejecutarla en nuestra propia infraestructura y mantener el control sobre los datos.

Si administramos varios servicios Docker, contar con una herramienta como Uptime Kuma facilita considerablemente las tareas de supervisión y mantenimiento.

Un Home Server no solamente necesita funcionar; también necesitamos saber cuándo deja de hacerlo.

Referencias y documentación

• Sitio oficial de Uptime Kuma
• Repositorio oficial en GitHub
• Documentación de instalación
• Monitorización de contenedores Docker