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:
git clone https://github.com/heroku/nodejs-getting-started
cd nodejs-getting-started
The relevant pieces:
{
"engines": {
"node": "24.x"
},
"main": "index.js",
"scripts": {
"start": "node index.js"
},
"dependencies": {
"express": "^5.0.0"
}
}
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:
web: node index.js
Starting node directly means your app receives SIGTERM itself on shutdown, rather than through npm.
With background workers:
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 onweb(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.