La respuesta corta
Para desplegar una app Express en producción, nodemon y node --watch se quedan en la laptop. El proceso de producción corre npm start, escucha en 0.0.0.0 y en process.env.PORT, responde GET /health y cierra el servidor con SIGTERM. El lockfile va en el repositorio. Si el proyecto es TypeScript, el build escribe JavaScript y el comando de arranque corre ese archivo. Los secretos van en Variables. El origen del navegador entra en una política de CORS explícita. trust proxy sigue el ingress que está delante de la app. Una sesión que tiene que sobrevivir un reinicio vive fuera del proceso. El pool de Postgres tiene un techo.
Si estás eligiendo hosting para Node.js Express, en Unbroker ese camino es el preset de Node.js y el comando npm start. El camino público de Node.js gestionado puede calificar para Free. Los dominios propios, los repos privados y la CLI piden Pro. La página de producto es Desplegar Express. Los pasos están en Deploy an Express API. Fastify es otro framework HTTP de Node. Esta nota se queda en Express.
Desarrollo y producción
nodemon y node --watch reinician el proceso cuando cambia un archivo. Ese loop es de la máquina donde estás editando. La guía de Express deja el script de arranque en node server.cjs y te dice que corras npm start. Un proyecto TypeScript tiene un comando de build, y el arranque corre el archivo generado en lugar de un watcher de desarrollo.
La guía de Express dice watcher de desarrollo. No nombra nodemon, node --watch ni ts-node. Pide arrancar el entry point generado.
| En la laptop | Proceso de producción | |
|---|---|---|
| Proceso | nodemon, node --watch, o un runtime de TypeScript que reinicia cuando cambian los archivos. | npm start. El script del ejemplo es node server.cjs. TypeScript arranca el archivo que escribió el build. |
| Dirección | Muchas veces localhost y un puerto elegido a mano. | 0.0.0.0 y process.env.PORT. El ejemplo usa 3000 solo cuando PORT está vacío. |
| Dependencias | Lo que tenga instalado la máquina local. | El lockfile del gestor de paquetes, commiteado junto con el manifest. |
| Configuración | Un .env al lado del código. | La vista Variables del servicio. El .env de producción queda fuera de Git. |
Un entry point de producción
El server.cjs de la guía es el archivo para publicar. Limita el body JSON, expone /health, escucha en PORT y en 0.0.0.0, y cierra con SIGTERM.
const express = require("express");
const app = express();
app.use(express.json({ limit: "100kb" }));
app.get("/health", (_request, response) => response.json({ ok: true }));
app.get("/api/message", (_request, response) => {
response.json({ message: "Hello from Unbroker" });
});
const server = app.listen(Number(process.env.PORT || 3000), "0.0.0.0");
process.on("SIGTERM", () => server.close());
La guía define ese script con npm pkg set scripts.start="node server.cjs". Number(process.env.PORT || 3000) escucha en PORT cuando está definido, y en 3000 cuando PORT está vacío. El bind es 0.0.0.0. Un proceso atado a 127.0.0.1 le responde a la máquina donde corre, y esa dirección deja de servir cuando el proceso ya no está en tu laptop. La guía de Node.js dice lo mismo cuando desplegás una API Node.js sin Express: escuchá en 0.0.0.0 y en el PORT que llega, no en un localhost fijo. Esa página es la guía de Node.js. El express.json({ limit: "100kb" }) del ejemplo es el límite de este archivo. Esta nota no describe otro límite de body.
El health check de Express en el ejemplo es GET /health, y el body es {"ok": true}. La guía también tiene GET /api/message. Apunta a la página hello-world de Express por el modelo de rutas que usa este ejemplo.
Por qué SIGTERM importa en un redeploy
Un redeploy reemplaza el proceso que está corriendo. La página de health checks de Express dice que el process manager manda SIGTERM para avisar que el proceso va a morir. La app tiene que dejar de aceptar pedidos nuevos, terminar los que ya están en curso, soltar lo que tiene tomado (la página nombra conexiones a la base y locks de archivos) y después salir. server.close() es la llamada del ejemplo de Express y del ejemplo de arriba. El cierre ordenado de Node con SIGTERM es esa secuencia. Esta nota no dice cuánto espera la plataforma antes de matar el proceso.
La guía de performance de Express pide NODE_ENV=production. En ese modo Express cachea los templates de vistas, cachea el CSS generado desde extensiones de CSS y genera mensajes de error menos verbosos. Esta nota no afirma una mejora medida por esa variable, y no dice que Unbroker la defina por vos.
Build, lockfile y TypeScript
Commiteá el servidor, el manifest y el lockfile. Lo dice la guía de Express. La guía de Node.js dice que una aplicación con dependencias tiene que commitear el lockfile que produjo el gestor de paquetes. El install del build tiene que coincidir con el install que revisaste.
Un proyecto sin paso de compilación puede arrancar con node server.cjs. Un proyecto TypeScript necesita un build que escriba JavaScript, y un comando de arranque que apunte a esa salida. La guía de Node.js dice que un archivo compilado que nunca se generó es una causa típica de que el proceso se caiga. También lo es un start script que falta, y una variable de entorno que el proceso necesita antes de poder escuchar.
Corré npm start en local y pedí /health antes de conectar el repositorio. El chequeo local del ejemplo es npm start y un pedido a /api/message.
Configuración y secretos
Sumá los secretos en la vista Variables del servicio. Dejá los .env de producción fuera de Git. Definí las variables antes de desplegar. Esas tres frases son la guía de Express y la guía de Node.js.
Un valor en el repositorio queda en el historial. Un valor que solo está en Variables está en el servicio. Cómo se acota una variable a producción o a un preview, y cuándo hay que redesplegar, está en Variables de entorno y secretos. Los pasos están en Configure environment variables and secrets.
CORS, proxies y cookies
Si el frontend vive en otro origen, permití ese origen en la política de CORS. La guía de Express dice que un endpoint JSON que responde en la terminal no prueba que el navegador pueda llamarlo. Una autenticación con cookies necesita una política de cookies y una política de CSRF pensadas. Esta nota no elige un valor de SameSite ni un paquete de CORS.
El trust proxy de Express es la forma en que Express lee los headers que agrega un proxy reverso. La página de proxies de Express dice que algunas APIs devuelven otros valores detrás de un proxy reverso, y que trust proxy es el ajuste. El caso que nombra es la IP del cliente apareciendo como la dirección del propio proxy.
El default es false: la app se trata como si mirara al cliente, y la IP sale de req.socket.remoteAddress. true toma la IP como la entrada de más a la izquierda de X-Forwarded-For. Express avisa que, con true, el último proxy reverso tiene que borrar o reescribir X-Forwarded-For, X-Forwarded-Host y X-Forwarded-Proto. Si no, el cliente puede mandar cualquier valor. La página también acepta una cantidad de saltos, una lista de direcciones de proxy o una función. Una cantidad de saltos queda mal cuando el cliente puede llegar a la app por un camino más corto que el número que configuraste.
Con el ajuste prendido, req.hostname sale de X-Forwarded-Host, req.protocol sale de X-Forwarded-Proto, y req.ip / req.ips se arman con el socket y X-Forwarded-For. X-Forwarded-Proto puede ser https, http o un nombre que no es ninguno de los dos. La guía de Express dice que no prendas una confianza de proxy sin límite solo para que los redirects funcionen. Configurá el comportamiento para el ingress que tenés, y revisá cómo la app decide que un pedido es HTTPS antes de apoyarte en una cookie secure o en la IP del cliente. Esta nota no nombra los saltos del proxy de Unbroker.
Sesiones, réplicas y estado
Una sesión guardada en el proceso es de ese proceso. La guía de performance de Express dice que las instancias no comparten memoria, así que no podés guardar estado en el código de la aplicación. Nombra Redis como un lugar para los datos de sesión, y dice que el mismo límite vale para el escalado horizontal en general, no solo para un cluster de procesos en una máquina. También dice que una app sin estado no guarda datos locales en el proceso, y nombra las sesiones como ese tipo de dato.
La guía de Express pide dejar las sesiones fuera de la memoria del proceso cuando tienen que durar, o cuando más de una réplica va a atender la app. La guía de Node.js pide mover sesiones o registros a una base antes de escalar entre réplicas. Los archivos en el filesystem del contenedor son temporales, salvo que vayan a un volumen persistente configurado. Ese volumen pide Pro. La tabla de planes lista los volúmenes persistentes como no disponibles en Free.
Free corre una réplica, hasta 250m de CPU y 256 MiB, y siempre duerme cuando está idle. La página de precios dice que la memoria y los archivos temporales se reinician cuando una app Free duerme. Una sesión que solo vivía en ese proceso desaparece con el sueño, y desaparece cuando un proceso nuevo reemplaza al viejo en un redeploy. Pro puede configurar réplicas, hasta el límite de la celda compartida de la tabla de planes. El autoscaling de réplicas no está en Free. Cómo se suman copias está en Autoscaling de réplicas. Redis como lugar para sesiones, caché y colas está en Redis gestionado. Esta nota no elige un store de sesión, y no dice que la plataforma fije un navegador a una réplica.
Conexiones a la base
El ejemplo de la guía de Express no tiene base. Cuando sumás Postgres, la guía de Node.js y PostgreSQL arranca de Unbroker Pro y de un PostgreSQL que ya existe. Las bases gestionadas no están en Free. Igual elegís un nodo de Apps o un clúster gestionado. Un nodo de Apps es un servicio privado que operás vos: imagen, volumen, upgrades y recuperación. Un clúster gestionado le deja el host al proveedor. Mapeá la conexión al nombre que lee tu app. El ejemplo espera DATABASE_URL y tira un error si falta. Ese valor va en Variables. No apagues la verificación del certificado para lograr una conexión. Operar la base está en Postgres en producción.
Acotá el pool. El ejemplo de Express de la guía es:
const { Pool } = require("pg");
if (!process.env.DATABASE_URL) throw new Error("DATABASE_URL is required");
const pool = new Pool({
connectionString: process.env.DATABASE_URL,
max: 5,
connectionTimeoutMillis: 5000,
idleTimeoutMillis: 30000,
statement_timeout: 5000,
});
max vale por proceso. La cuenta de la guía es tres réplicas con un pool de cinco, que pueden abrir quince conexiones, antes de jobs y herramientas de administración. Dejá margen bajo el límite de conexiones de la base. Llamá a pool.end() en el apagado, después de drenar los pedidos HTTP. Eso va al lado de server.close(), que frena los pedidos nuevos para que los que ya están abiertos puedan terminar.
Dejá GET /health como un chequeo barato del proceso. La guía suma GET /ready, que corre SELECT 1 y responde 503 si esa query falla. Dice que separes el chequeo del proceso cuando un incidente de la base no tiene que leerse como un proceso HTTP enfermo. La página de health checks de Express usa Kubernetes como ejemplo de dos chequeos: liveness decide cuándo reiniciar un contenedor, y readiness decide cuándo puede tomar tráfico. Esos son los nombres de la página para Kubernetes. Esta nota no dice que la ruta de health check de Unbroker sea una de esas dos probes.
Aplicá los cambios de schema como un paso de release propio, con las credenciales de runtime, y después desplegá. Los comandos de migración piden Pro. Qué deja un rollback de código en el schema está en Migraciones de base de datos en el deploy. Estimá la API y la base por separado. La guía de Express dice que la base y los otros recursos pagos entran en la estimación del plan.
Fallos comunes
La tabla de la guía de Express es la lista para usar antes de cambiar el tamaño de la máquina.
| Síntoma | Qué revisar |
|---|---|
| El servicio no llega a estar sano | Dirección de escucha, PORT, script de arranque y respuesta de /health |
| La API responde 404 | Prefijo de la ruta y método HTTP, incluido cualquier base URL del frontend |
| El navegador bloquea una API que funciona | La respuesta de CORS y el origen del frontend permitido |
| El login deja de andar después de un deploy | Persistencia de la sesión, cookies y el secreto de firma |
Leé los logs de runtime para separar un error de la aplicación de un error del deploy. La guía de Node.js dice que lo hagas cuando el proceso se cae. Por dónde empezar cuando un release falla está en Depurar un deploy fallido. Para qué sirven los logs, las métricas y las alertas está en Logs, métricas y alertas. Los logs de runtime están en Free y en Pro. La tabla de planes lista las métricas de recursos como no disponibles en Free y disponibles en Pro.
Cómo funciona en Unbroker
En Cloud, agregá un servicio de repositorio, elegí Node.js y dejá el comando de arranque en npm start. Si el proyecto compila TypeScript, configurá el build y arrancá el archivo generado. Poné los secretos en Variables. Desplegá, y después pedí /health en la URL que muestra Cloud. En Pro, configurá la ruta del health check para que coincida con esa ruta.
El camino público de Node.js gestionado puede calificar para Free. Las apps Node.js públicas que entran en esa condición pueden usar Free desde Cloud. La tabla de planes lista Node.js gestionado como incluido en Free. Los dominios propios, las credenciales de repositorios privados y el acceso por CLI piden Pro. Crear un token de API pide Pro. Los builds de Dockerfile no están en Free y sí están en Pro. Desplegar esta API desde un Dockerfile es ese otro camino, y esta nota no lo describe como un camino Free.
Free es un proyecto, dos servicios y tres pedidos de deploy por día UTC. Cada servicio Free corre una réplica, hasta 250m de CPU y 256 MiB, y duerme cuando está idle. El primer pedido después de un sueño puede tardar más mientras el proceso arranca. Pro sale $25 por mes con $25 de crédito de uso. El crédito se reinicia en cada ciclo, no se acumula y no tiene valor en efectivo. Si el uso elegible queda por debajo del crédito, el cargo mensual sigue siendo el precio del plan. Si el uso elegible lo pasa, solo se suma la diferencia. Esos términos están en precios y en Plans. Contá la API y cualquier base como líneas separadas. El camino genérico de Node es Desplegar Node.js y Deploy a Node.js application. Esos mismos topes de Free, incluido el sueño cuando no hay tráfico, están en un plan de $0 para una API Node chica.
Checklist
- Apuntá
npm startanode server.cjs, o al JavaScript que emitió el build. Dejánodemonynode --watchfuera de ese script. - Escuchá en
0.0.0.0. LeéPORT. El ejemplo usa 3000 solo cuandoPORTestá vacío. - Serví
GET /health. En Pro, configurá la ruta del health check para que coincida. - Llamá a
server.close()conSIGTERM. Llamá apool.end()después de drenar los pedidos, si la app tiene un pool. - Commiteá el lockfile con el manifest. Una app TypeScript buildea primero y arranca el archivo generado.
- Poné los secretos en Variables. Dejá los
.envde producción fuera de Git. - Permití el origen del frontend en CORS. Configurá
trust proxypara el ingress que tenés, no entruecomo atajo. - Dejá las sesiones fuera del proceso si tienen que sobrevivir un reinicio, un sueño de Free o más de una réplica.
- Poné un techo al pool. El ejemplo de la guía es
max: 5, y ese máximo es por proceso. - Abrí
/healthdespués del deploy. Leé los logs de runtime antes de subir CPU o memoria.
Preguntas frecuentes
¿Puedo usar nodemon o node --watch en producción?
No van en el script de arranque. La guía de Express deja scripts.start en node server.cjs y el comando del servicio en npm start. nodemon y node --watch reinician el proceso cuando cambia un archivo. Eso es el loop de la máquina donde estás editando. Si el proyecto compila TypeScript, la misma guía pide un comando de build y arrancar el archivo generado, en lugar de un watcher de desarrollo. El watcher espera el árbol de trabajo. El release corre el comando que configuraste.
¿Por qué la app Express anda en local y después del deploy no?
Revisá la dirección, el puerto y el script de arranque. El ejemplo escucha en 0.0.0.0 y en Number(process.env.PORT || 3000): si PORT está vacío, cae a 3000. La guía de Node.js dice que un build que terminó bien no prueba que el servidor se alcance. El proceso tiene que escuchar en 0.0.0.0 y en el PORT que le llega, no en un localhost fijo. Si el servicio se cae, la misma guía nombra un start script que falta, un archivo compilado que nunca se generó, o una variable de entorno que el proceso necesita para arrancar. En la tabla de fallos, un servicio que no queda sano es la dirección, PORT, el script y la respuesta de /health.
¿Conviene app.set('trust proxy', true)?
No como default. La página de proxies de Express dice que el default es false: la app se trata como si mirara al cliente, y la IP sale de req.socket.remoteAddress. true toma la IP como la entrada de más a la izquierda de X-Forwarded-For. La misma página avisa que, con true, el último proxy reverso tiene que borrar o reescribir X-Forwarded-For, X-Forwarded-Host y X-Forwarded-Proto. Si no, el cliente puede mandar cualquier valor. La guía de Express dice que no actives una confianza de proxy sin límite solo para que los redirects funcionen. Ajustá esa opción al ingress que tenés de verdad, y fijate cómo la app lee HTTPS antes de confiar en una cookie secure o en la IP del cliente. Esta nota no elige una cantidad de saltos.
¿Cómo cierro un servidor Express con orden en un redeploy?
Cerrá el servidor HTTP cuando el proceso recibe SIGTERM. La página de health checks de Express dice que una versión nueva arranca con el process manager mandando SIGTERM, para que la app deje de aceptar pedidos nuevos, termine los que ya están en curso, suelte recursos como conexiones a la base y locks de archivos, y después salga. El ejemplo de esa página, y el de Unbroker, llaman a server.close() desde ese handler. La guía de Postgres pide pool.end() después de drenar los pedidos HTTP. Esta nota no dice cuánto espera la plataforma antes de matar el proceso.
¿Dónde van los secretos de Express en producción?
En la vista Variables del servicio, no en un .env de producción dentro de Git. Esa es la instrucción de la guía de Express. Definí las variables de la aplicación antes del deploy, que es lo que dice la guía de Node.js. Cómo se agrupan está en Variables de entorno y secretos.
¿Puedo desplegar una API Express en el plan Free de Unbroker?
El camino público de Node.js gestionado puede calificar para Free. Las apps Node.js públicas que entran en esa condición pueden usar Free desde Cloud. Los dominios propios, los repositorios privados y el acceso por CLI piden Pro. Los tokens de API y el flujo de deploy por CLI también piden Pro. La tabla de planes marca Node.js gestionado como incluido en Free, y los builds de Dockerfile como no disponibles en Free. Un Dockerfile es otro camino. En Pro, la guía de Express dice que configures la ruta del health check para que coincida con la ruta. Pro sale $25 por mes con $25 de crédito de uso. Los pasos están en Desplegar Express y en la guía de Express.