Alojar Checkmate en un VPS administrado significa vigilar sus sitios web y sus servidores desde una máquina propia, que nuestros equipos mantienen actualizada y supervisan día y noche. Checkmate es una aplicación de monitorización libre y de código abierto con licencia AGPL-3.0: disponibilidad, tiempos de respuesta, incidencias, alertas y páginas de estado. Esta guía sigue su imagen Docker oficial, en la versión v4.0.0, y ejecutamos cada comando en un VPS de Simafri antes de escribirla: la instalación con Docker Compose, HTTPS, la primera cuenta, los monitores y las alertas, las copias de seguridad y las actualizaciones.
Por Simon Vasconcelos Lee
Publicado el 17 de noviembre de 202612 minutos de lectura
ghcr.io/bluewave-labs/checkmate y MongoDB 8.0, con el puerto publicado en 127.0.0.1 detrás de un proxy inverso en HTTPS.JWT_SECRET, ENCRYPTION_KEY y su dirección pública en CLIENT_HOST, y añada NODE_ENV=production, que el archivo de referencia omite.mongodump y conserve su archivo .env; después actualice cambiando la etiqueta de la imagen: las migraciones se ejecutan solas al iniciar.Checkmate comprueba sus servicios a intervalos regulares, registra cada respuesta y su tiempo de respuesta, y le avisa cuando algo deja de responder. Su desarrollador, BlueWave Labs, lo describe como una herramienta autoalojada para seguir en tiempo real el hardware de los servidores, la disponibilidad, los tiempos de respuesta y las incidencias.
Checkmate se publica con la GNU Affero General Public License, versión 3 (AGPL-3.0). Puede usarlo de forma gratuita, para usted, su empresa o sus clientes, copiarlo y modificarlo.
Su cláusula particular se refiere al uso en red: si modifica Checkmate y deja que otras personas usen su versión modificada a través de la red, debe ofrecerles su código fuente. Ejecutar la imagen oficial sin modificar, como en esta guía, no crea esa obligación. El software se ofrece sin garantía.
La documentación fija un mínimo modesto: cualquier VPS Linux con 1 GB de RAM o más. Añade que MongoDB usa unos 400 MB en una instancia que comprueba más de 300 servidores cada minuto.
El tamaño del servidor depende, por tanto, del número de monitores, de su intervalo y del historial que conserve. En un VPS administrado, cuéntenos su uso y le recomendaremos el tamaño adecuado.
Desde la versión 3.10, Checkmate se distribuye como una sola imagen, ghcr.io/bluewave-labs/checkmate, que sirve a la vez la interfaz y la API. MongoDB funciona a su lado, en su propio contenedor. En un servidor con Docker Engine y su plugin Compose, instalados desde el repositorio de Docker para Ubuntu, cree una carpeta como /opt/checkmate y coloque en ella este compose.yaml, basado en el archivo de referencia del proyecto:
services:
checkmate:
image: ghcr.io/bluewave-labs/checkmate:v4.0.0
restart: always
ports:
- "127.0.0.1:52345:52345"
environment:
- DB_CONNECTION_STRING=mongodb://mongodb:27017/uptime_db
- CLIENT_HOST=https://status.example.com
- JWT_SECRET=${JWT_SECRET:?set JWT_SECRET in .env}
- ENCRYPTION_KEY=${ENCRYPTION_KEY:?set ENCRYPTION_KEY in .env}
- NODE_ENV=production
stop_grace_period: 60s
healthcheck:
test: ["CMD", "node", "-e", "require('http').get('http://localhost:52346/livez',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"]
interval: 15s
timeout: 3s
start_period: 60s
start_interval: 2s
retries: 3
depends_on:
mongodb:
condition: service_healthy
mongodb:
image: mongo:8.0
restart: always
command: ["mongod", "--quiet", "--bind_ip_all"]
volumes:
- mongo-data:/data/db
healthcheck:
test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/27017"]
interval: 5s
timeout: 30s
start_period: 0s
start_interval: 1s
retries: 30
volumes:
mongo-data:
Los dos secretos van en un archivo .env situado al lado, que Docker Compose lee por sí mismo. Créelo legible solo por root y después inicie el conjunto:
umask 077
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -base64 32)" > .env
umask 022
docker compose up -d
docker compose ps
127.0.0.1: el archivo de referencia lo publica sin dirección, y Docker lo abre entonces en todas las direcciones del servidor. Publicado en local, solo es accesible a través del proxy inverso.CLIENT_HOST es la dirección que escriben sus usuarios, con https://. Checkmate la usa para las comprobaciones de origen cruzado y para los enlaces de sus alertas y sus correos.NODE_ENV=production: el README lo pide en los despliegues reales. Sin él, la aplicación funciona en modo de desarrollo, que desactiva el limitador de peticiones de la API.ENCRYPTION_KEY es opcional en el archivo de referencia. Cifra los secretos que guarda Checkmate, y la v4.0.0 la exige para los monitores Docker con TLS y para Checkmate Connect. Defínala desde el principio: es más sencillo que añadirla después.latest y la descarga en cada inicio. Una versión completa, aquí v4.0.0, le permite elegir el momento de cada actualización.mongo-data contiene todos sus datos: monitores, comprobaciones, usuarios y ajustes.El primer inicio ejecuta las migraciones de la base de datos; en nuestro VPS de prueba, la aplicación se declaró en buen estado en menos de diez segundos. Para comprobar que responde:
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:52345/
curl -s http://127.0.0.1:52345/api/v1/auth/users/superadmin
El primer comando responde 200. El segundo responde "data":false mientras no exista ninguna cuenta, y true una vez creado el Superadmin.
Checkmate no tiene cuenta por defecto. La primera persona que se registra se convierte en Superadmin, así que cree la suya justo después del primer inicio, antes de abrir la dirección al público. Un túnel SSH lleva el puerto 52345 del servidor a su ordenador, en http://localhost:52345; añada -p y el puerto SSH indicado en su área de cliente.
ssh -L 52345:127.0.0.1:52345 root@status.example.com
http://localhost:52345: Checkmate muestra su página de registro.A partir de ese momento, el registro público queda cerrado: en nuestro VPS de prueba, cada nuevo visitante era enviado a la página de inicio de sesión, y la dirección de registro también llevaba allí. Las demás personas entran por invitación, desde la sección Team de los ajustes de la cuenta, con el rol User o Admin. La invitación se envía por correo, así que necesita la configuración SMTP que se describe más abajo, y su enlace caduca al cabo de una hora.
| Rol | Lo que puede hacer |
|---|---|
| User | Ver todos los monitores, el panel, las comprobaciones, las incidencias, las páginas de estado y los ajustes, sin cambiar nada |
| Admin | Todo lo que puede un User, más los monitores, los canales de notificación, las incidencias, las ventanas de mantenimiento, las páginas de estado, las invitaciones y los ajustes globales, SMTP incluido |
| Superadmin | Todo lo que puede un Admin, más crear cuentas directamente, editar a otro usuario, cambiar un rol o una contraseña |
Desde la v4.0.0, las etiquetas, las páginas de estado y los proxies son acciones de Admin: un User que podía gestionarlos antes pierde ese acceso después de la actualización.
El contenedor sirve Checkmate en HTTP, en el puerto 52345. HTTPS corre a cargo de un proxy inverso situado delante: la documentación cita Caddy, Traefik y nginx. Probamos Caddy, instalado desde su repositorio oficial para Debian y Ubuntu: obtiene por sí mismo el certificado de Let’s Encrypt, lo renueva, y transmite por defecto la cabecera Host y las cabeceras X-Forwarded-*.
status.example.com {
reverse_proxy 127.0.0.1:52345
}
sudo systemctl reload caddy
CLIENT_HOST debe contener la misma dirección en https:// que el proxy. Después de cambiarla, ejecute docker compose up -d para recrear el contenedor.Las alertas por correo y las invitaciones pasan por una conexión SMTP común a todo el servidor, que se configura en «Settings», pestaña «Email»: servidor, puerto, usuario, contraseña y dirección del remitente, y después «Save» y «Test». En un VPS de Simafri, use un servidor SMTP autenticado, en el puerto 587 o 465: el servicio de correo de su dominio, o un servicio de envío. Cree después una notificación por correo con las direcciones que hay que avisar, y asóciela a sus monitores.
Slack, Discord, Teams, Telegram y los demás canales se crean del mismo modo, en «Notifications», cada uno con su dirección de webhook o su token, y cada uno con un botón «Test».
Un monitor heartbeat vigila una tarea que se ejecuta sola, como una copia de seguridad nocturna. Genere la clave de ping del equipo en «Settings», pestaña «Monitoring» (solo se muestra una vez), cree un monitor Heartbeat con un slug y una ventana de alerta, y después llame a su URL de ping al final de la tarea:
0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 "https://status.example.com/api/v1/heartbeat/<ping-key>/nightly-backup"
Añadir /fail, o el código de salida de la tarea, a la URL marca el monitor como caído de inmediato, sin esperar a que pase la ventana.
En «Status pages», un Admin publica una página que enumera los monitores elegidos y su disponibilidad, para sus clientes o su equipo. Desde la v4.0.0, cada página de estado tiene una zona horaria, UTC por defecto.
Todo se encuentra en dos lugares: la base de datos MongoDB, en el volumen mongo-data, y su archivo .env. Guarde este último en lugar seguro: ENCRYPTION_KEY es necesaria para leer los secretos guardados en la base de datos, y JWT_SECRET mantiene abiertas las sesiones de sus usuarios. La imagen de MongoDB incluye mongodump:
docker compose exec -T mongodb mongodump --archive --gzip --db uptime_db > checkmate-$(date +%F).archive.gz
cp .env env-$(date +%F).bak
Programe esta copia y envíela fuera del servidor; un monitor heartbeat puede avisarle si algún día deja de ejecutarse. Guardados en el disco, los archivos entran también en las copias de seguridad nocturnas del servidor.
En la misma instalación o en una nueva, con el mismo .env, detenga la aplicación, cargue el archivo y vuelva a iniciarla:
docker compose stop checkmate
docker compose exec -T mongodb mongorestore --archive --gzip --drop < checkmate-2026-11-17.archive.gz
docker compose start checkmate
Probamos el ciclo completo en nuestro VPS: copia, base de datos realmente eliminada, restauración. El monitor y la cuenta volvieron, y el inicio de sesión funcionó de nuevo al instante.
Checkmate v4.0.0 ofrece también copias de seguridad cifradas en la nube mediante Checkmate Connect, un servicio opcional, gratuito durante su beta, que necesita ENCRYPTION_KEY y un Superadmin para inscribir la instalación. Las copias anteriores funcionan sin él.
Lea la nota de versión, haga una copia de seguridad, cambie la etiqueta de la imagen en el compose.yaml, y después descargue la nueva imagen y recree el contenedor. Las migraciones de la base de datos se ejecutan solas al iniciar:
docker compose pull
docker compose up -d
docker compose logs checkmate | grep -i migration
mongodump y mongorestore. No se requiere ninguna variable de entorno nueva.checkmate-client, checkmate-backend y checkmate-mongo, que ya no se actualizan. Pase a ghcr.io/bluewave-labs/checkmate y conserve su servicio MongoDB y su volumen; las variables UPTIME_APP_* ya no se leen.Checkmate envía un informe anónimo al día: un identificador de instalación, la versión, el modo de instalación y el número de monitores de cada tipo, nunca sus URL ni sus resultados. Lo indica en su registro al iniciar. Para desactivarlo, añada TELEMETRY_ENABLED=false al entorno del servicio checkmate y después ejecute docker compose up -d.
El autoalojamiento exige mantener el servidor además de la aplicación. En un VPS administrado, nuestros equipos se encargan del servidor y siguen su instancia de forma proactiva; Checkmate sigue siendo su software, con sus monitores y sus ajustes.
| Tema | Nuestros equipos | Usted |
|---|---|---|
| El servidor | Actualizaciones del sistema y de seguridad, con intervenciones en el servidor incluidas | El momento que mejor convenga a su actividad |
| La supervisión | Servidor vigilado las 24 horas del día, los 7 días de la semana, con intervención sin esperar su llamada | Sus propios monitores, alertas y páginas de estado en Checkmate |
| Checkmate | Seguimiento proactivo: errores, lentitud, base de datos y espacio en disco detectados, corrección recomendada | Su instalación, sus actualizaciones y sus ajustes, que aplica usted o su asistente de IA |
| Los usuarios y las alertas | El servidor que los soporta, vigilado y con copias de seguridad | Las cuentas, los roles, las invitaciones y los canales de notificación |
| Las copias de seguridad | Cada noche, cifradas y guardadas fuera de la máquina; restauración incluida | Las exportaciones propias de la base de datos de Checkmate, y la petición de restauración, cuando la necesite |
| La migración | Su servidor actual migrado, gratis | El momento del cambio |
Si prefiere que nuestros equipos intervengan en la propia aplicación, ese servicio se factura por horas o a precio cerrado, con un presupuesto comunicado antes de la intervención.
Con un VPS administrado de Simafri, nuestros equipos mantienen actualizado el servidor de su instancia de Checkmate, lo vigilan día y noche e intervienen sin esperar su llamada; también siguen su instancia de forma proactiva y le recomiendan las correcciones útiles, que aplica usted o su asistente de IA. Las copias de seguridad se cifran cada noche y se guardan fuera de la máquina, su restauración está incluida, y la migración de su servidor actual es gratuita.
Sí. Checkmate tiene licencia AGPL-3.0: puede ejecutarlo para usted, su equipo o sus clientes sin ninguna licencia que comprar. Si lo modifica y deja que otros lo usen a través de la red, comparte sus cambios. Queda el coste del servidor que lo ejecuta.
Parta del compose.yaml de referencia: la imagen ghcr.io/bluewave-labs/checkmate y MongoDB 8.0. Ponga JWT_SECRET y ENCRYPTION_KEY en un archivo .env, defina CLIENT_HOST con su dirección https y NODE_ENV en production, publique el puerto 52345 en 127.0.0.1, ejecute docker compose up -d y coloque delante un proxy inverso en HTTPS.
No hay ninguno. La primera persona que se registra en una instancia nueva se convierte en Superadmin. Cree su cuenta justo después del primer inicio, a través de un túnel SSH; después, los visitantes son enviados a la página de inicio de sesión y los nuevos usuarios entran por invitación.
La documentación pide un VPS Linux con 1 GB de RAM o más. En nuestro VPS de prueba, una instalación nueva usaba unos 300 MB para Checkmate y 280 MB para MongoDB. El disco crece con el número de monitores, su intervalo y el historial que conserve, 90 días por defecto.
Configure la conexión SMTP en Settings, pestaña Email: servidor, puerto 587 o 465, usuario, contraseña y remitente, y después Save y Test. Cree una notificación por correo con las direcciones que hay que avisar y asóciela a sus monitores. Las invitaciones usan la misma configuración.
Exporte la base de datos MongoDB con docker compose exec -T mongodb mongodump --archive --gzip --db uptime_db, y conserve una copia de su archivo .env, cuya ENCRYPTION_KEY es necesaria para leer los secretos guardados. Restaure con mongorestore --archive --gzip --drop, con la aplicación detenida.
Lea la nota de versión y haga una copia de seguridad, cambie la etiqueta de la imagen en compose.yaml, y después ejecute docker compose pull y docker compose up -d. Las migraciones de la base de datos se ejecutan solas al iniciar.
Un VPS administrado cubre el servidor: sistema, seguridad, supervisión y copias de seguridad. Nuestros equipos siguen también su instancia de forma proactiva y le recomiendan las correcciones útiles, que aplica usted. Una intervención en la aplicación se factura por horas o a precio cerrado.
Simafri
Hablemos de su proyecto
Díganos en pocas palabras lo que necesita: le respondemos rápidamente.
¡Gracias! Su solicitud ha sido enviada. Le responderemos en breve.
¿Prefiere el correo? Escríbanos a support@simafri.com.