# Deploy an Express app to production: from nodemon to a running service

Deploy an Express app with npm start, not a watcher. Listen on 0.0.0.0 and PORT, add /health, and keep secrets in variables. Node.js can qualify for Free.

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

## The short answer

To deploy an Express app, stop starting it with `nodemon` or `node --watch`. An Express production deployment runs `npm start`, listens on `0.0.0.0` and `process.env.PORT`, answers `GET /health`, and closes the server on `SIGTERM`. Commit the lockfile. If the project is TypeScript, the build produces JavaScript and the start command runs that file. Secrets go in Variables. The browser origin is an explicit CORS allow. `trust proxy` matches the ingress in front of the app. Sessions that have to survive a restart live outside the process. The Postgres pool has a ceiling.

Express app hosting on Unbroker uses the Node.js preset and the start command `npm start`. The public managed Node.js path can qualify for Free. Custom domains, private repositories, and CLI access require Pro. The product page is [Deploy Express](https://unbroker.cloud/deploy/express). The steps are [Deploy an Express API](https://docs.unbroker.cloud/guides/deploy-express). Fastify is a different Node HTTP framework. This note stays on Express.

## Dev and production

`nodemon` and `node --watch` restart the process when a file changes. That loop is for the machine where you are editing. The [Express guide](https://docs.unbroker.cloud/guides/deploy-express) sets the start script to `node server.cjs` and tells you to run `npm start`. A TypeScript project gets a build command, and the start command runs the generated file instead of a development watcher.

The Express guide says development watcher. It does not name `nodemon`, `node --watch`, or `ts-node`. It says to start the generated entry point instead.

| | On the laptop | Production process |
| --- | --- | --- |
| Process | `nodemon`, `node --watch`, or a TypeScript runtime that restarts when files change. | `npm start`. The sample script is `node server.cjs`. TypeScript starts the file the build wrote. |
| Address | Often `localhost` and a port you picked. | `0.0.0.0` and `process.env.PORT`. The sample uses 3000 only when `PORT` is empty. |
| Dependencies | Whatever the local install has. | The lockfile from your package manager, committed with the manifest. |
| Settings | A `.env` file next to the code. | The service's Variables view. A production `.env` stays out of Git. |

## A production entry point

The guide's `server.cjs` is the file to ship. It caps the JSON body, exposes `/health`, listens on `PORT` and `0.0.0.0`, and closes on `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());
```

The guide sets that script with `npm pkg set scripts.start="node server.cjs"`. `Number(process.env.PORT || 3000)` listens on `PORT` when it is set, and on 3000 when `PORT` is empty. Bind `0.0.0.0`. A process bound to `127.0.0.1` answers the machine it is on, which is the wrong address once the process is not on your laptop. The Node.js guide says the same thing when you deploy a Node.js API without Express: listen on `0.0.0.0` and the supplied `PORT`, not a hard-coded localhost address. The [Node.js guide](https://docs.unbroker.cloud/guides/deploy-nodejs) is that page. The sample's `express.json({ limit: "100kb" })` is the limit in this file. This page does not describe another body limit.

The Express health check in the sample is `GET /health`, and the body is `{"ok": true}`. The guide also has `GET /api/message`. It points at the [Express hello-world page](https://expressjs.com/en/starter/hello-world.html) for the routing model this sample uses.

### Why SIGTERM matters on a redeploy

A redeploy replaces the running process. [Express's health-check page](https://expressjs.com/en/advanced/healthcheck-graceful-shutdown.html) says the process manager sends `SIGTERM` to tell the app it will be killed. The app should stop accepting new requests, finish the requests already in flight, release what it holds (the page names database connections and file locks), and then exit. `server.close()` is the call in Express's example and in the sample above. Node graceful shutdown on `SIGTERM` is that sequence. This page does not state how long the platform waits before it kills the process.

Express's [performance guide](https://expressjs.com/en/advanced/best-practice-performance.html) says to set `NODE_ENV` to `production`. In that mode Express caches view templates, caches CSS generated from CSS extensions, and generates less verbose error messages. This page does not claim a measured speedup from that variable, and it does not say Unbroker sets it for you.

## Build, lockfile, and TypeScript

Commit the server, the package manifest, and the lockfile. The Express guide says that. The Node.js guide says that an application with dependencies should commit the lockfile the package manager produced. The install on the build should match the install you reviewed.

A project with no compile step can start `node server.cjs`. A TypeScript project needs a build that writes JavaScript, and a start command that points at that output. The Node.js guide says a compiled file that was never generated is a typical reason the process exits. So is a missing start script, and so is an environment variable the process requires before it can listen.

Run `npm start` locally and request `/health` before you connect the repository. The sample's local check is `npm start` and a request to `/api/message`.

## Settings and secrets

Add secrets in the service's Variables view. Keep production `.env` files out of Git. Set the variables before you deploy. Those three sentences are the Express guide and the Node.js guide.

A value in the repository is in the history. A value only in Variables is on the service. How a variable is scoped to production or to a preview, and when you have to redeploy, is [Environment variables and secrets](https://unbroker.cloud/blog/environment-variables-and-secrets). The steps are [Configure environment variables and secrets](https://docs.unbroker.cloud/guides/environment-variables).

## CORS, proxies, and cookies

If the frontend is on another origin, allow that origin in the CORS policy. The Express guide says a JSON endpoint that works in a terminal does not prove the browser may call it. Cookie-based authentication needs a deliberate cookie policy and a CSRF policy. This page does not pick a `SameSite` value or a CORS package.

The Express trust proxy setting is how Express reads the headers a reverse proxy adds. [Express's behind-proxies page](https://expressjs.com/en/guide/behind-proxies.html) says some APIs return different values behind a reverse proxy, and `trust proxy` is the setting that adjusts them. The common case it names is the client IP showing up as the proxy's own address.

The default is `false`: the app is treated as facing the client, and the client IP comes from `req.socket.remoteAddress`. `true` takes the client IP as the left-most entry in `X-Forwarded-For`. Express warns that, with `true`, the last reverse proxy has to remove or overwrite `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwarded-Proto`. Otherwise the client may send any value. The page also accepts a hop count, a list of proxy addresses, or a function. A hop count is wrong when the client can reach the app by a shorter path than the number you set.

When the setting is on, `req.hostname` comes from `X-Forwarded-Host`, `req.protocol` comes from `X-Forwarded-Proto`, and `req.ip` / `req.ips` are filled from the socket and `X-Forwarded-For`. `X-Forwarded-Proto` may be `https`, `http`, or a name that is neither. The Express guide says not to turn on unrestricted proxy trust just to make redirects work. Configure the behavior for the ingress you have, and check how the app decides a request is HTTPS before you rely on a secure cookie or the client IP. This page does not name Unbroker's proxy hops.

## Sessions, replicas, and state

A session stored in the process belongs to that process. Express's performance guide says instances do not share memory, so you cannot keep state in application code. It names Redis as one place for session data, and it says the same limit applies to horizontal scaling in general, not only to a cluster of processes on one machine. It also says a stateless app does not keep local data in the process, and it names sessions as that kind of data.

The Express guide says to keep sessions outside process memory when you need them to last, or when more than one replica will serve the app. The Node.js guide says to move sessions or records to a database before you scale across replicas. Files on the container filesystem are temporary unless they go to a configured persistent volume. That volume requires Pro. The plans table lists persistent volumes as not available on Free.

Free runs one replica, up to 250m CPU and 256 MiB, and it always sleeps when idle. The [pricing page](https://unbroker.cloud/pricing) says memory and temporary files are reset when a Free app sleeps. A session that lived only in that process is gone after the sleep, and it is gone when a new process replaces the old one on a redeploy. Pro can configure replicas, up to the shared-cell limit in the [plans table](https://docs.unbroker.cloud/billing/plans). Replica autoscaling is not available on Free. How copies are added is [Replica autoscaling](https://unbroker.cloud/blog/replica-autoscaling). Redis as a place for sessions, cache, and queues is [Managed Redis](https://unbroker.cloud/blog/managed-redis-cache-queues). This page does not pick a session store, and it does not say the platform pins a browser to one replica.

## Database connections

The Express guide's sample has no database. When you add Postgres, the [Node.js and PostgreSQL guide](https://docs.unbroker.cloud/guides/api-with-postgres) starts from Unbroker Pro and an existing PostgreSQL resource. Managed databases are not available on Free. You still choose an Apps node or a managed cluster. An Apps node is a private service you operate: image, volume, upgrades, and recovery. A managed cluster leaves the host to the provider. Map the connection to the name your app reads. The sample expects `DATABASE_URL` and throws if it is missing. Put that value in Variables. Do not turn certificate verification off to get a connection. Operating the database is [Postgres in production](https://unbroker.cloud/blog/postgres-in-production).

Bound the pool. The guide's Express example is:

```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` applies to each process. The guide's arithmetic is three replicas with a pool of five, which can open fifteen connections, before jobs and administration tools. Leave room under the database's connection limit. Call `pool.end()` in the shutdown path after HTTP requests have drained. That sits next to `server.close()`, which stops new requests so the ones already open can finish.

Keep `GET /health` as a cheap check of the process. The guide adds `GET /ready`, which runs `SELECT 1` and returns 503 when that query fails. It says to keep the process check separate when a database incident should not be read as an unhealthy HTTP process. Express's health-check page uses Kubernetes as the example of two checks: liveness decides when to restart a container, and readiness decides when it can take traffic. Those are the page's names for Kubernetes. This page does not say Unbroker's health-check path is one of those two probes.

Apply schema changes as their own release step, with the runtime credentials, then deploy. Migration commands require Pro. What a code rollback leaves in the schema is [Database migrations on deploy](https://unbroker.cloud/blog/database-migrations-on-deploy). Estimate the API and the database separately. The Express guide says database and other paid resources belong in the [plan estimate](https://unbroker.cloud/pricing).

## Common failures

The Express guide's table is the list to use before you change the machine size.

| Symptom | What to inspect |
| --- | --- |
| Service cannot become healthy | Listen address, `PORT`, start script, and `/health` response |
| API returns 404 | Route prefix and HTTP method, including any frontend base URL |
| Browser blocks a working API | CORS response and the allowed frontend origin |
| Login stops working after a deploy | Session persistence, cookie settings, and the signing secret |

Read the runtime logs to separate an application error from a deployment error. The Node.js guide says to do that when the process exits. Where to start when a release fails is [Debug a failed deployment](https://unbroker.cloud/blog/debug-failed-deployment). What logs, metrics, and alerts are for is [Logs, metrics, and alerts](https://unbroker.cloud/blog/logs-metrics-alerts). Runtime logs are available on Free and on Pro. The plans table lists resource metrics as not available on Free and available on Pro.

## How this works on Unbroker

In Cloud, add a repository service, choose Node.js, and set the start command to `npm start`. If the project compiles TypeScript, set the build command and start the generated file. Put secrets in Variables. Deploy, then request `/health` on the URL Cloud shows. On Pro, set the health-check path to that route.

The public managed Node.js path can qualify for Free. Eligible public Node.js apps can use Free through Cloud. The [plans table](https://docs.unbroker.cloud/billing/plans) lists managed Node.js as included on Free. Custom domains, private repository credentials, and CLI access require Pro. API token creation requires Pro. Dockerfile builds are not available on Free and are available on Pro. Deploying this API from a Dockerfile is that other path, and this page does not describe it as a Free path.

Free is one project, two services, and three deploy requests per UTC day. Each Free service runs one replica, up to 250m CPU and 256 MiB, and sleeps when idle. The first request after a sleep can take longer while the process starts. Pro is $25 a month with $25 of usage credit. The credit resets each billing cycle, does not roll over, and has no cash value. If eligible usage stays under the credit, the monthly charge is still the plan price. If eligible usage is above the credit, only the difference is added. Those terms are on [pricing](https://unbroker.cloud/pricing) and in [Plans](https://docs.unbroker.cloud/billing/plans). Count the API and any database as separate lines. The generic Node path is [Deploy Node.js](https://unbroker.cloud/deploy/nodejs) and [Deploy a Node.js application](https://docs.unbroker.cloud/guides/deploy-nodejs). The same Free caps, including sleep after idle, are [a $0 plan for a small Node API](https://unbroker.cloud/blog/free-backend-hosting).

## Checklist

1. Point `npm start` at `node server.cjs`, or at the JavaScript the build emitted. Leave `nodemon` and `node --watch` out of that script.
2. Listen on `0.0.0.0`. Read `PORT`. The sample uses 3000 only when `PORT` is empty.
3. Serve `GET /health`. On Pro, set the health-check path to that route.
4. Call `server.close()` on `SIGTERM`. Call `pool.end()` after requests have drained, when the app holds a pool.
5. Commit the lockfile with the manifest. A TypeScript app builds first and starts the generated file.
6. Put secrets in Variables. Keep production `.env` files out of Git.
7. Allow the frontend origin in CORS. Set `trust proxy` for the ingress you have, not to `true` as a shortcut.
8. Keep sessions outside the process if they have to survive a restart, a Free sleep, or more than one replica.
9. Cap the pool. The guide's example is `max: 5`, and that max is per process.
10. Open `/health` after deploy. Read the runtime logs before you raise CPU or memory.

## FAQ

### Can I run nodemon or node --watch in production?

Leave them out of the start script. The Express guide sets scripts.start to node server.cjs and the service start command to npm start. nodemon and node --watch restart the process when files change. That is a local loop. If the project compiles TypeScript, the same guide says to configure the build command and start the generated entry point instead of a development watcher. A watcher is waiting on the working tree. The release runs the command you configured.

### Why does my Express app work locally but not after deploy?

Check the address, the port, and the start script. The sample listens on 0.0.0.0 and on Number(process.env.PORT || 3000), so an empty PORT falls back to 3000. The Node.js guide says a successful build does not prove the server is reachable: the process has to listen on 0.0.0.0 and the supplied PORT, not a hard-coded localhost address. If the service exits, the same guide names a missing start script, a compiled file that was never generated, or an environment variable required during startup. The failure table says an unhealthy service is the listen address, PORT, the start script, and the /health response.

### Should I set app.set('trust proxy', true)?

Not as a default. Express's behind-proxies page says the default is false: the app is treated as facing the client, and the client IP comes from req.socket.remoteAddress. true reads the client IP as the left-most X-Forwarded-For entry. The same page warns that, with true, the last reverse proxy has to remove or overwrite X-Forwarded-For, X-Forwarded-Host, and X-Forwarded-Proto, or the client may supply any value. The Express guide says not to enable unrestricted proxy trust just to make redirects work. Set the option for the ingress you actually have, and check how the app reads HTTPS before you rely on a secure cookie or the client IP. This page does not pick a hop count.

### How do I shut down an Express server gracefully on redeploy?

Close the HTTP server when the process receives SIGTERM. Express's health-check page says that a new version starts with the process manager sending SIGTERM, so the app can stop accepting new requests, finish the ones in flight, release resources such as database connections and file locks, and then exit. The sample on that page, and the Unbroker sample, call server.close() from that handler. The Postgres guide says to call pool.end() after HTTP requests have drained. This page does not state a grace-period length.

### Where do Express secrets go in production?

In the service's Variables view, not in a production .env file in Git. That is the Express guide's instruction. Set application environment variables before deployment, which is what the Node.js guide says. How those variables are scoped is [Environment variables and secrets](https://unbroker.cloud/blog/environment-variables-and-secrets).

### Can I deploy an Express API on Unbroker's Free plan?

The public managed Node.js path can qualify for Free. Eligible public Node.js apps can use Free through Cloud. Custom domains, private repositories, and CLI access require Pro. API tokens and the CLI deployment flow require Pro as well. The plans table lists managed Node.js as included on Free, and Dockerfile builds as not available on Free. A Dockerfile is a different path. On Pro, the Express guide says to configure the health-check path to match the route. Pro is $25 a month with $25 of usage credit. The steps are [Deploy Express](https://unbroker.cloud/deploy/express) and the [Express guide](https://docs.unbroker.cloud/guides/deploy-express).

## Related reading

- [Deploy Express](https://unbroker.cloud/deploy/express)
- [Deploy Node.js](https://unbroker.cloud/deploy/nodejs)
- [Environment variables and secrets](https://unbroker.cloud/blog/environment-variables-and-secrets)
- [Postgres in production](https://unbroker.cloud/blog/postgres-in-production)
- [Database migrations on deploy](https://unbroker.cloud/blog/database-migrations-on-deploy)
- [Replica autoscaling](https://unbroker.cloud/blog/replica-autoscaling)
- [Managed Redis](https://unbroker.cloud/blog/managed-redis-cache-queues)
- [Debug a failed deployment](https://unbroker.cloud/blog/debug-failed-deployment)
- [Logs, metrics, and alerts](https://unbroker.cloud/blog/logs-metrics-alerts)
- [Pricing](https://unbroker.cloud/pricing)
- [Free plan caps for a Node API](https://unbroker.cloud/blog/free-backend-hosting)
