Uptime Kuma en un VPS: instalación del monitoreo de sitios y servidores

30/8/20267 min de lectura

Tropic

Uptime Kuma en un VPS: instalación del monitoreo de sitios y servidores

Uptime Kuma: cómo instalar tu propio monitoreo de sitios en un VPS

Un sitio puede fallar y seguir respondiendo con 200 OK. Una copia de seguridad también puede dejar de crearse sin mostrar un error evidente. Uptime Kuma detecta ambos casos: comprueba sitios, API, puertos y tareas en segundo plano, y envía una notificación cuando encuentra un problema.

A continuación veremos dónde alojar el monitoreo, qué VPS necesita y cómo instalar Uptime Kuma 2, activar HTTPS, conectar Telegram y crear una página de estado.

Uptime Kuma en siete pasos

Preparar un VPS pequeño separado de los proyectos que se van a monitorear.
Apuntar hacia él un subdominio, por ejemplo monitor.example.com.
Instalar Docker e iniciar Uptime Kuma 2.
Cerrar el puerto interno 3001 al exterior y configurar HTTPS.
Crear monitores HTTP, DNS, TCP o Push.
Configurar Telegram y, cuando sea necesario, una página de estado.
Activar las actualizaciones y una copia externa del directorio de datos.

Qué es Uptime Kuma

Uptime Kuma es una herramienta gratuita, de código abierto y autoalojada. El panel y el historial de comprobaciones se guardan en tu propio servidor.

Puede monitorear HTTP(S), puertos TCP, ping, DNS, WebSocket, texto y JSON en las respuestas, señales Push y contenedores Docker. El intervalo mínimo de comprobación es de 20 segundos. También ofrece decenas de canales de notificación, 2FA, gráficos de latencia, supervisión de certificados TLS y varias páginas de estado.

Cómo detectar una falla detrás de un `200 OK`

Una comprobación HTTP convencional solo ve el código de respuesta. Sin embargo, el servidor web puede mostrar una página en blanco o una pantalla de error de la aplicación y aun así devolver un estado correcto.

Para realizar una comprobación más precisa, utiliza:

Keyword — busca una frase esperada, como el nombre del sitio o el texto «Área de clientes»;
JSON Query — comprueba un valor en la respuesta de la API, por ejemplo status: healthy.

De este modo, el monitoreo no solo confirma que el puerto está accesible, sino también una señal mínima de que la aplicación funciona correctamente.

Monitor Push para copias de seguridad y tareas cron

Un monitor Push no consulta el servicio, sino que espera una señal periódica enviada por este. Un script de copia de seguridad o una tarea cron accede a una URL única después de finalizar correctamente. Si la señal no llega a tiempo, Uptime Kuma informa de la falla.

Esto permite detectar un problema «silencioso»: el sitio sigue funcionando, pero la copia de seguridad diaria no se crea desde hace varios días.

Qué no sustituye Uptime Kuma

Uptime Kuma monitorea principalmente la disponibilidad y el tiempo de respuesta. Para CPU, RAM, disco, registros y métricas de contenedores, conviene complementarlo con Prometheus, Netdata, Zabbix u otro sistema: Kuma detecta el problema desde fuera, mientras que las métricas ayudan a encontrar la causa.

Por qué conviene alojar el monitoreo en otro VPS

Si Uptime Kuma se instala junto al sitio, una falla del VPS, la red o el centro de datos puede dejar fuera de servicio tanto el proyecto como el monitoreo. En ese caso, la notificación podría no enviarse.

Aloja el panel en un VPS independiente y, para proyectos importantes, en otra ubicación o con otro proveedor. También resulta útil monitorear el propio Kuma mediante un servicio externo: el sistema de monitoreo también necesita ser vigilado.

Requisitos de servidor de Uptime Kuma

El proyecto no establece un mínimo oficial estricto de CPU y RAM. Una configuración inicial práctica para una instalación pequeña es:

1 vCPU;
1 GB de RAM;
10 GB de SSD;
Ubuntu 24.04 LTS;
IPv4;
un dominio o subdominio para HTTPS.

Esta configuración suele ser suficiente para varias decenas de comprobaciones sencillas. Para cientos de monitores, un historial extenso o comprobaciones mediante navegador, es mejor elegir 2 GB de RAM o más.

Cómo instalar Uptime Kuma en un VPS

En este ejemplo se utilizan Ubuntu 24.04 y el subdominio monitor.example.com.

1. Configura DNS y el firewall

Crea un registro DNS A que apunte a la dirección IPv4 del VPS. Conéctate por SSH y abre los puertos necesarios:

ssh root@SERVER_IP
apt update && apt upgrade -y

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable

No cierres la sesión SSH actual hasta comprobar que puedes iniciar una nueva conexión.

2. Instala Docker y Docker Compose

apt install -y ca-certificates curl
install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

apt update
apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

docker compose version

3. Inicia Uptime Kuma 2

mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma

cat > compose.yaml <<'EOF'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data
EOF

docker compose up -d
docker compose ps

Utiliza la etiqueta :2: latest sigue apuntando a la antigua rama v1. El directorio /app/data debe encontrarse en un disco local o en un Docker volume convencional. NFS y los almacenamientos que no gestionan correctamente el bloqueo de archivos pueden dañar la base de datos.

El puerto 3001 solo está disponible en 127.0.0.1. Un proxy inverso con HTTPS publicará el panel hacia el exterior.

4. Configura HTTPS con Caddy

apt install -y caddy

cat > /etc/caddy/Caddyfile <<'EOF'
monitor.example.com {
    reverse_proxy 127.0.0.1:3001
}
EOF

caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy

Si DNS apunta al VPS, Caddy solicitará automáticamente un certificado TLS y reenviará las conexiones WebSocket. Aloja el panel en la raíz de un dominio o subdominio: una dirección como example.com/kuma no es compatible.

5. Crea la cuenta de administrador

Abre https://monitor.example.com, crea una cuenta con una contraseña larga y única y activa la autenticación de dos factores.

Cómo añadir el primer monitor

Haz clic en Add New Monitor y selecciona HTTP(s):

Indica un nombre y la URL completa.
Define un intervalo, por ejemplo 60 segundos.
Añade dos reintentos para evitar falsos avisos por fallas ocasionales de red.
Selecciona un canal de notificación.
Guarda el monitor y comprueba que comienzan a aparecer solicitudes correctas.

Para el sitio principal son útiles las comprobaciones HTTP y Keyword. Para una API, utiliza un endpoint de salud y JSON Query. No expongas bases de datos ni puertos administrativos a internet solo para monitorearlos: usa una red de confianza o una VPN.

Ejemplo de monitor Push para una copia de seguridad

Después de crear un monitor de tipo Push, añade su URL única al final del script:

backup-command && \
  curl -fsS "https://monitor.example.com/api/push/SECRET_TOKEN?status=up&msg=backup-ok"

La solicitud solo se ejecutará después de una copia de seguridad correcta. Guarda el token Push como si fuera una contraseña: cualquier persona que conozca la URL puede enviar una señal falsa.

Cómo conectar Telegram

Crea un bot mediante @BotFather, envíale un mensaje y abre Settings → Notifications → Telegram. Introduce el Bot Token y el Chat ID, pulsa Test y vincula el canal con los monitores. Para servicios críticos, añade un segundo canal, como el correo electrónico.

Cómo crear una página de estado

En Status Pages puedes agrupar monitores, mostrar el estado actual y el historial de disponibilidad, asignar un dominio e informar sobre trabajos programados mediante Maintenance. No publiques direcciones IP internas ni URL técnicas: para los clientes bastan componentes como «Sitio», «API», «Área de clientes» y «Pagos».

Actualización y copia de seguridad

Antes de una actualización importante, detén el contenedor y guarda el directorio de datos:

cd /opt/uptime-kuma
docker compose down

tar -czf /root/uptime-kuma-$(date +%F).tar.gz \
  data compose.yaml

docker compose up -d

Transfiere el archivo a otro dispositivo o almacenamiento externo. Una copia en el mismo VPS no protege frente a la eliminación del servidor ni ante una falla del disco.

Para una actualización normal:

cd /opt/uptime-kuma
docker compose pull
docker compose up -d --force-recreate

Después del arranque, comprueba docker compose ps, el panel y una notificación de prueba.

Qué VPS elegir para Uptime Kuma

Para una instalación pequeña basta con un VPS Linux de 1 vCPU y 1 GB de RAM. La independencia es más importante que la potencia: el monitor debe seguir funcionando cuando el proyecto principal no está disponible.

Uptime Kuma puede alojarse en un VPS de tropic.host si los servicios monitoreados se encuentran en otra plataforma o en un nodo independiente. Ubuntu, Docker y una IP fija permiten iniciar rápidamente el panel, y los recursos pueden ampliarse a medida que aumenta el número de comprobaciones.

Si la producción ya funciona en la misma infraestructura, elige otro nodo o añade un monitor externo de respaldo. Separar los puntos de falla resulta más útil que agregar un núcleo de CPU.

Errores habituales

Error	Por qué es un problema	Cómo hacerlo mejor
El monitoreo está junto al proyecto	Una falla común deja fuera de servicio tanto el servicio como las notificaciones	Usar un VPS o una ubicación independiente
El puerto `3001` está expuesto públicamente	El panel queda accesible sin proxy inverso ni HTTPS	Vincular el puerto a `127.0.0.1`
Solo se comprueba el código `200`	Una falla de la aplicación puede parecer un resultado correcto	Añadir Keyword o JSON Query
Se utiliza la etiqueta `latest`	Apunta a la antigua rama v1	Usar `louislam/uptime-kuma:2`
La copia se guarda en el mismo VPS	Desaparecerá junto con el servidor	Copiar el directorio `data` fuera del VPS

Resumen

Uptime Kuma convierte un VPS pequeño en un centro propio de monitoreo para sitios, API, DNS, puertos, certificados y tareas en segundo plano. Keyword ayuda a detectar una página dañada, JSON Query identifica una respuesta incorrecta de la API y Push revela una copia de seguridad o una tarea cron detenida.

Para conseguir una configuración confiable, separa el monitoreo de la producción, cierra el puerto 3001, activa HTTPS y 2FA y configura dos canales de notificación. Después, crea una copia externa del directorio de datos y una comprobación independiente del propio Uptime Kuma.

FAQ

¿Uptime Kuma es gratuito?

Sí. El proyecto es de código abierto y se distribuye bajo la licencia MIT. Solo se pagan la infraestructura, el dominio y las copias de seguridad externas.

¿Cuánta RAM necesita Uptime Kuma?

Para una instalación pequeña, 1 GB de RAM es un punto de partida razonable. Para cientos de comprobaciones, un historial largo o Browser Engine, asigna 2 GB o más.

¿Se puede instalar Uptime Kuma sin Docker?

Sí, mediante Node.js y PM2. Sin embargo, Docker Compose suele ser más fácil de actualizar, migrar y restaurar en un VPS.

¿Se puede utilizar Uptime Kuma sin dominio?

Técnicamente sí, mediante la dirección IP o un túnel SSH. Para un acceso permanente desde internet, es más seguro usar un subdominio con HTTPS.

¿Uptime Kuma muestra el uso de CPU, RAM y disco?

No como un sistema completo de métricas del servidor. Para monitorear los recursos, conviene complementarlo con Prometheus, Netdata, Zabbix u otra herramienta especializada.

Volver al blog