# Desplegar una app Express en producción: de nodemon a un servicio en marcha

Desplegá Express con npm start, sin watcher. Escuchá en 0.0.0.0 y PORT, sumá /health y dejá secretos en Variables. Node.js público puede calificar para Free.

Canonical URL: https://unbroker.cloud/es/blog/express-in-production
Published: 2026-11-11
Reviewed: 2026-11-11
Author: Timoteo Borgobello

## 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](https://unbroker.cloud/deploy/express). Los pasos están en [Deploy an Express API](https://docs.unbroker.cloud/guides/deploy-express). 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](https://docs.unbroker.cloud/guides/deploy-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`.

```js
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](https://docs.unbroker.cloud/guides/deploy-nodejs). 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](https://expressjs.com/en/starter/hello-world.html) 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](https://expressjs.com/en/advanced/healthcheck-graceful-shutdown.html) 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](https://expressjs.com/en/advanced/best-practice-performance.html) 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](https://unbroker.cloud/es/blog/environment-variables-and-secrets). Los pasos están en [Configure environment variables and secrets](https://docs.unbroker.cloud/guides/environment-variables).

## 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](https://expressjs.com/en/guide/behind-proxies.html) 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](https://unbroker.cloud/es/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](https://docs.unbroker.cloud/billing/plans). El autoscaling de réplicas no está en Free. Cómo se suman copias está en [Autoscaling de réplicas](https://unbroker.cloud/es/blog/replica-autoscaling). Redis como lugar para sesiones, caché y colas está en [Redis gestionado](https://unbroker.cloud/es/blog/managed-redis-cache-queues). 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](https://docs.unbroker.cloud/guides/api-with-postgres) 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](https://unbroker.cloud/es/blog/postgres-in-production).

Acotá el pool. El ejemplo de Express de la guía es:

```js
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](https://unbroker.cloud/es/blog/database-migrations-on-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](https://unbroker.cloud/es/precios).

## 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](https://unbroker.cloud/es/blog/debug-failed-deployment). Para qué sirven los logs, las métricas y las alertas está en [Logs, métricas y alertas](https://unbroker.cloud/es/blog/logs-metrics-alerts). 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](https://docs.unbroker.cloud/billing/plans) 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](https://unbroker.cloud/es/precios) y en [Plans](https://docs.unbroker.cloud/billing/plans). Contá la API y cualquier base como líneas separadas. El camino genérico de Node es [Desplegar Node.js](https://unbroker.cloud/deploy/nodejs) y [Deploy a Node.js application](https://docs.unbroker.cloud/guides/deploy-nodejs). 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](https://unbroker.cloud/es/blog/free-backend-hosting).

## Checklist

1. Apuntá `npm start` a `node server.cjs`, o al JavaScript que emitió el build. Dejá `nodemon` y `node --watch` fuera de ese script.
2. Escuchá en `0.0.0.0`. Leé `PORT`. El ejemplo usa 3000 solo cuando `PORT` está vacío.
3. Serví `GET /health`. En Pro, configurá la ruta del health check para que coincida.
4. Llamá a `server.close()` con `SIGTERM`. Llamá a `pool.end()` después de drenar los pedidos, si la app tiene un pool.
5. Commiteá el lockfile con el manifest. Una app TypeScript buildea primero y arranca el archivo generado.
6. Poné los secretos en Variables. Dejá los `.env` de producción fuera de Git.
7. Permití el origen del frontend en CORS. Configurá `trust proxy` para el ingress que tenés, no en `true` como atajo.
8. Dejá las sesiones fuera del proceso si tienen que sobrevivir un reinicio, un sueño de Free o más de una réplica.
9. Poné un techo al pool. El ejemplo de la guía es `max: 5`, y ese máximo es por proceso.
10. Abrí `/health` despué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](https://unbroker.cloud/es/blog/environment-variables-and-secrets).

### ¿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](https://unbroker.cloud/deploy/express) y en la [guía de Express](https://docs.unbroker.cloud/guides/deploy-express).

## Related reading

- [Desplegar Express](https://unbroker.cloud/deploy/express)
- [Desplegar Node.js](https://unbroker.cloud/deploy/nodejs)
- [Variables de entorno y secretos](https://unbroker.cloud/es/blog/environment-variables-and-secrets)
- [Postgres en producción](https://unbroker.cloud/es/blog/postgres-in-production)
- [Migraciones de base de datos en el deploy](https://unbroker.cloud/es/blog/database-migrations-on-deploy)
- [Autoscaling de réplicas](https://unbroker.cloud/es/blog/replica-autoscaling)
- [Redis gestionado](https://unbroker.cloud/es/blog/managed-redis-cache-queues)
- [Depurar un deploy fallido](https://unbroker.cloud/es/blog/debug-failed-deployment)
- [Logs, métricas y alertas](https://unbroker.cloud/es/blog/logs-metrics-alerts)
- [Precios](https://unbroker.cloud/es/precios)
- [Topes del plan Free para una API Node](https://unbroker.cloud/es/blog/free-backend-hosting)
