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. The steps are Deploy an Express API. 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 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 laptopProduction process
Processnodemon, 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.
AddressOften localhost and a port you picked.0.0.0.0 and process.env.PORT. The sample uses 3000 only when PORT is empty.
DependenciesWhatever the local install has.The lockfile from your package manager, committed with the manifest.
SettingsA .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.

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 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 for the routing model this sample uses.

Why SIGTERM matters on a redeploy

A redeploy replaces the running process. Express’s health-check page 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 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. The steps are Configure environment variables and secrets.

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 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 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. Replica autoscaling is not available on Free. How copies are added is Replica autoscaling. Redis as a place for sessions, cache, and queues is Managed Redis. 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 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.

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

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. Estimate the API and the database separately. The Express guide says database and other paid resources belong in the plan estimate.

Common failures

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

SymptomWhat to inspect
Service cannot become healthyListen address, PORT, start script, and /health response
API returns 404Route prefix and HTTP method, including any frontend base URL
Browser blocks a working APICORS response and the allowed frontend origin
Login stops working after a deploySession 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. What logs, metrics, and alerts are for is Logs, metrics, and 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 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 and in Plans. Count the API and any database as separate lines. The generic Node path is Deploy Node.js and Deploy a Node.js application. The same Free caps, including sleep after idle, are a $0 plan for a small Node API.

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.

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 and the Express guide.