Comprobar un servidor Node con Docker: puerto, salud y estado

Tu web abre en el editor, pero al cerrar la terminal desaparece. Si responde mediante un proceso Node, necesitas comprobar ese proceso antes de elegir dónde alojarlo. Esta guía se centra en señales concretas: puerto correcto, rutas, salud, apagado y estado tras reiniciar.

Usamos Señal, ejemplo original MIT, sin dependencias externas, cuentas, pagos ni base de datos. Su página lee la versión y el tiempo de actividad del servidor. No basta con copiar sus archivos a un alojamiento estático.

Fija la versión y arranca el proceso

Instala Node 22.23.3, versión publicada por Node.js, y comprueba que node --version devuelve v22.23.3. Conserva la licencia MIT y el lockfile al copiar el ejemplo.

git clone https://github.com/ocentelles/hostbrid-example-service.git
cd hostbrid-example-service
git checkout dffe40abc37323cb9a84f172f804ed91670e465e
node --version
npm ci
npm run check
npm test
PORT=8080 npm start

npm ci utiliza el lockfile y falla si no coincide con package.json. Aquí no hay paquetes externos. npm start mantiene el servidor activo; no genera una carpeta dist. Abre http://localhost:8080/ y conserva esa terminal mientras haces las comprobaciones desde otra.

El código escucha en 0.0.0.0:8080. PORT puede cambiar el puerto; el valor del proceso debe coincidir con el puerto configurado para el servicio. 0.0.0.0 permite recibir conexiones desde fuera del proceso: no es una URL para visitar y, en ejecución nativa, puede permitir acceso desde tu red local.

Reproduce la imagen sin exponerla públicamente

Con un motor Docker ya disponible, detén primero el proceso nativo para liberar 8080 y ejecuta:

docker build -t hostbrid-service-check:dffe40a .
docker run --rm --name hostbrid-service-check -e PORT=8080 \
  -p 127.0.0.1:8080:8080 hostbrid-service-check:dffe40a

La base del Dockerfile fija Node 22.23.3 Alpine mediante digest. El contenedor usa un usuario no root y arranca Node directamente. El mapeo de puertos anterior publica 8080 únicamente en el loopback del equipo. EXPOSE documenta un puerto, pero no lo publica por sí solo. Estos comandos son una receta local; no configuran un dominio ni HTTPS.

Para esta restricción a localhost usa Docker Engine 28.0.0 o posterior con la red bridge predeterminada. Docker advierte que en versiones anteriores otros equipos del mismo segmento L2 pueden alcanzar puertos publicados en localhost. Comprueba la versión del servidor con docker version; no hemos probado un daemon Docker local. Aviso oficial de publicación de puertos.

Comprueba algo que pueda fallar

Desde otra terminal:

curl -fsS http://127.0.0.1:8080/healthz
curl -fsS http://127.0.0.1:8080/status.json
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/missing
curl -s -o /dev/null -w '%{http_code}\n' 'http://127.0.0.1:8080/healthz?check=1'

/healthz debe devolver JSON con status: ok; /status.json incluye version, bootId, uptimeSeconds y requests. La ruta inexistente y la query no declarada deben devolver 404, sin sustituirlas por la página principal. Abre también /service.css y /signal.svg: una portada que responde no demuestra que sus activos estén disponibles.

Tres controles de salud distintos

/healthz es una ruta que implementa la aplicación. El HEALTHCHECK del Dockerfile ejecuta un helper dentro del contenedor. Las probes de Kubernetes se configuran aparte: readiness controla recepción de tráfico, liveness reinicios y startup el arranque. El Dockerfile no configura automáticamente esas probes.

En nuestra prueba se ejecutó el helper con éxito. No presentamos eso como prueba del estado health de un daemon Docker ni de probes Kubernetes de un servicio publicado.

Apagado y memoria: comprueba el límite

docker stop --timeout 10 hostbrid-service-check

El ejemplo maneja SIGTERM: deja de aceptar conexiones y espera las peticiones activas; tiene un límite interno de cinco segundos. El test de contenedor verificó salida 0 y puerto cerrado enviando SIGTERM al servidor hijo del verificador. No demuestra un rollout ni entrega de señales por Kubernetes a Node como PID1.

Tras arrancar de nuevo, bootId cambia y el contador se reinicia. Uptime y peticiones viven en memoria efímera, no en almacenamiento persistente. Las sondas también cuentan como peticiones: no son visitantes. Para datos duraderos, necesitas diseñar y probar almacenamiento, copias y recuperación aparte.

Qué hemos probado y qué falta para publicar

El 8 de octubre de 2026 construimos una imagen OCI y ejecutamos 11 comprobaciones en un Job temporal: versión, salud, estado, uptime, activos, 404, apagado y reinicio de memoria. Se limpió el Job y sus referencias propias. La prueba no creó un servicio de alojamiento ni demostró una URL pública HTTPS, OAuth de cliente o despliegue automático tras un push.

Para llevar una aplicación con proceso a Hostbrid Projects, revisa un plan con servicios incluidos y cuota libre, Dockerfile en la raíz, puerto del servicio y variables. La cuota estática no autoriza procesos permanentes. Consulta el precio actual antes de crear recursos; este ejemplo no demuestra servicios gratuitos. Dominio, HTTPS, probes y persistencia necesitan su propia verificación con tu aplicación.

Si tu aplicación necesita coordinar una web, una API y una base de datos en contenedores separados, consulta la guía para desplegar Docker Compose en un VPS. Trata una pila de varios servicios; esta página se centra en comprobar un único proceso Node.

Cuando el proceso ya funciona, compara las rutas de despliegue en la guía de alojamiento Node.js: Sites, Projects con Git y un VPS tienen requisitos distintos de dominio y operación.