Docs menu

Deploying Express

Deploy an Express app on Primcloud: Procfile, port binding, static assets, and common patterns for Express services.

On this page

An Express app needs a package.json with a start script and a server listening on $PORT. This page covers the Procfile, common environment variables, and what to know before you ship.

Starter template#

Heroku's heroku/nodejs-getting-started repo is a minimal Express app that runs on Primcloud unchanged. Fork it as a starting point:

Terminal
git clone https://github.com/heroku/nodejs-getting-started
cd nodejs-getting-started

The relevant pieces:

package.json
{
  "engines": {
    "node": "24.x"
  },
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "express": "^5.0.0"
  }
}
index.js
const express = require("express");
const app = express();
const port = process.env.PORT || 3000;

app.get("/", (req, res) => res.send("Hello from Express on Primcloud"));

app.listen(port, () => console.log(`listening on ${port}`));

That's the whole app. Commit, push, import into Primcloud, and it deploys.

Procfile for Express on Primcloud#

Express apps can go either way, with or without a Procfile.

Without a Procfile. If package.json has a start script, your web process runs npm start (or pnpm start / yarn start).

With a Procfile. Add one to make the command explicit, run other formations, or start Node directly:

Procfile
web: node index.js

Starting node directly means your app receives SIGTERM itself on shutdown, rather than through npm.

With background workers:

Procfile
web: node index.js
worker: node worker.js

Each formation is scaled independently; see Formations.

Env vars this framework expects#

Express itself reads very few env vars. Most of what your app needs is app-specific. The conventional set:

  • NODE_ENV=production: turns on Express's production behavior, such as view caching and shorter error messages. Primcloud sets it for Node.js apps unless you set it yourself.
  • PORT: set by Primcloud on web (5000). Read it; don't override it.
  • DATABASE_URL, REDIS_URL, and other connection strings your app uses.

Set your own values as secrets.

Framework gotchas on Primcloud#

Bind to $PORT, not a hardcoded port.

Tutorials often hard-code 3000, but only $PORT receives traffic. Read it from the environment so the same code runs locally and on Primcloud:

const port = process.env.PORT || 3000;
app.listen(port);

Warning

Listen on 0.0.0.0 or leave out the host (app.listen(port, () => ...)). A server listening only on 127.0.0.1 gets no traffic.

Trust the proxy.

Primcloud handles HTTPS in front of your app and passes the original request details in X-Forwarded-* headers. Tell Express to trust them, or req.ip and req.protocol won't reflect the visitor:

app.set("trust proxy", true);

With this on, req.ip returns the visitor's IP from X-Forwarded-For, and req.protocol returns https.

Static assets.

express.static() works as it does locally.

Body parsing and file uploads.

Express 4.16+ ships express.json() and express.urlencoded(). Use those over the deprecated body-parser package. For multipart uploads, use multer or a streaming parser; buffering large uploads can use more memory than your formation's size has.

Graceful shutdown.

When a deploy or restart stops your app, it gets SIGTERM and has 30 seconds to exit before it's killed. To finish in-flight requests and close connections cleanly, handle SIGTERM:

const server = app.listen(port);

process.on("SIGTERM", () => {
  console.log("SIGTERM received, closing HTTP server");
  server.close(() => {
    console.log("HTTP server closed");
    process.exit(0);
  });
});

Without this, in-flight requests are cut off when the process exits.

Session storage.

express-session's default MemoryStore keeps sessions in one process: they vanish on restart and aren't shared when the formation runs more than one copy. Use a store like connect-redis or connect-pg-simple instead.

Troubleshooting#

The deployment fails waiting for web to accept connections: the app isn't listening on $PORT. Fix the app.listen() call.

req.ip isn't the visitor's address: turn on app.set('trust proxy', true).

Uploads over ~10MB fail with 413 or hang: Express's default body-parser limits are 100kb for JSON and urlencoded. Raise them with express.json({ limit: '10mb' }), or better, stream uploads directly to storage instead of buffering them through Node.js.

Sessions disappear after a deploy: you're using MemoryStore. Switch to a store like connect-redis.

Cannot find module 'express' at runtime: Express is in devDependencies, which can be pruned after the build. Move it to dependencies.

Restarts drop in-flight requests: add a SIGTERM handler that closes the HTTP server, as shown under Graceful shutdown.