Deploying Node (PM2 & Docker)

Reviewed & published by Brayan K

Deploying a Node app means running it reliably in production: loading config from environment variables, keeping the process alive with a manager like PM2 or a container, exposing a health check, and shutting down gracefully on SIGTERM.

Part of the free Node.js course at LearnCodingFast — hands-on lessons with worked examples and the output they print, plus practice exercises and a quick quiz.

In this lesson you'll set NODE_ENV, load config safely from env vars, supervise your app with PM2 (cluster, logs, restart, reload), containerize it with a cache-friendly Dockerfile and health check, and handle graceful shutdown so deploys never drop a request.

What You'll Learn in This Lesson

• Why NODE_ENV=production matters and how to set it
• How to load config from env vars and fail fast on missing ones
• How PM2 keeps your app alive, clustered, and logged
• How to write a small, cache-friendly Dockerfile for Node
• How a /health endpoint and HEALTHCHECK keep traffic safe
• How to shut down gracefully on SIGTERM with no dropped requests

1️⃣ Environment & Config

Production code should never hard-code secrets or settings. Instead it reads environment variables — process.env.PORT, process.env.DATABASE_URL, process.env.NODE_ENV — so the same image runs in dev, staging, and prod with different values. A good config loader applies defaults and fails fast: if a required variable is missing, it crashes at startup, not later under load.

// A tiny config loader: read env vars, apply defaults, fail fast on missing ones.
// This runs as plain Node — set vars with NODE_ENV=production node app.js
function loadConfig(env) {
  const required = ['DATABASE_URL'];
  for (const key of required) {
    if (!env[key]) throw new Error(`Missing required env var: ${key}`);
  }
  return {
    nodeEnv: env.NODE_ENV || 'development',
    port: Number(env.PORT || 3000),
    databaseUrl: env.DATABASE_URL,
    isProd: env.NODE_ENV === 'production',
  };
}

// Simulate a production environment object.
const config = loadConfig({ NODE_ENV: 'production', PORT: '8080', DATABASE_URL: 'postgres://db/app' });
console.log('Env:    ', config.nodeEnv);
console.log('Port:   ', config.port);
console.log('Is prod?', config.isProd);

// Missing a required var? Crash NOW, at startup — not later under load.
try {
  loadConfig({ NODE_ENV: 'production' });   // no DATABASE_URL
} catch (err) {
  console.log('Startup failed ->', err.message);
}

2️⃣ Keeping It Alive: PM2 & Graceful Shutdown

A plain node app.js stops the instant it crashes or the box reboots. PM2 is a process manager that supervises your app: it restarts on crash, runs one worker per CPU core in cluster mode, aggregates logs, and can reload with zero downtime. These are shell commands you run on the server:

When PM2 (or Docker) stops your app it sends SIGTERM first. Catch it and shut down gracefully: stop accepting new connections, let in-flight requests finish, then exit. The block below runs for real and sends itself SIGTERM so you can see the sequence:

const http = require('node:http');
const server = http.createServer((req, res) => res.end('ok'));

server.listen(3000, () => console.log('Server listening on port 3000'));

// On SIGTERM (what PM2, Docker, and Kubernetes send to stop you), stop
// accepting NEW connections, finish in-flight ones, then exit cleanly.
// Without this, the platform force-kills you and drops live requests.
function shutdown(signal) {
  console.log(`Received ${signal}, shutting down gracefully...`);
  server.close(() => {
    console.log('Closed remaining connections. Bye.');
    process.exit(0);
  });
}
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));

// (Demo: we send SIGTERM to ourselves so the output is reproducible.)
setTimeout(() => process.kill(process.pid, 'SIGTERM'), 100);

3️⃣ Containerizing with Docker + Health Checks

Docker packages your app and its exact Node version into an image that runs identically anywhere. The key trick is layer caching: copy package*.json and run npm ci before copying your source, so the slow install step is cached when only your code changes.

# A small, production-ready Dockerfile for a Node app.
FROM node:22-alpine

# Run as a non-root user for safety.
WORKDIR /app

# Copy manifests FIRST so Docker can cache the slow "npm ci" layer.
COPY package*.json ./
RUN npm ci --omit=dev

# Now copy the rest of the source.
COPY . .

# Tell Docker (and humans) which port the app uses.
ENV NODE_ENV=production
EXPOSE 3000

# A health check lets the orchestrator know if the app is alive.
HEALTHCHECK --interval=30s --timeout=3s \
  CMD node -e "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode === 200 ? 0 : 1))"

# Use the array form so signals (SIGTERM) reach Node for graceful shutdown.
CMD ["node", "app.js"]

The Dockerfile's HEALTHCHECK pings a /health route so the orchestrator knows whether this instance should receive traffic. That route is just a cheap endpoint in your app:

const express = require('express');
const app = express();

// A health endpoint the load balancer / orchestrator pings to decide if
// this instance should receive traffic. Keep it cheap and dependency-light.
app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok', uptime: process.uptime() });
});

app.listen(process.env.PORT || 3000);

Your turn. Fill in the two ___ blanks so the config helpers read the port and mode correctly, then run it.

// 🎯 YOUR TURN — replace each ___ then run it.
// Read a PORT from the environment, defaulting to 3000, and report the mode.

function getPort(env) {
  return Number(env.PORT || ___);          // 👉 3000  (the default port)
}
function isProduction(env) {
  return env.NODE_ENV === ___;             // 👉 'production'
}

const env = { PORT: '8080', NODE_ENV: 'production' };
console.log('Port:', getPort(env));
console.log('Production?', isProduction(env));

// ✅ Expected output:
//    Port: 8080
//    Production? true

Mini-Challenge: A Server That Stops Cleanly

No blanks this time — just a brief and an outline. Write it yourself, run it, and check your output. This is the exact pattern that keeps deploys from dropping live requests.

const http = require('node:http');

// 🎯 MINI-CHALLENGE: a server that shuts down gracefully.
// 1. Create an http server that replies 'ok' to every request.
// 2. Listen on port 3000 and log 'up'.
// 3. On 'SIGTERM', log 'stopping', then server.close() and log 'done' + exit(0).
// 4. (Demo line is provided to fire SIGTERM at yourself after 100ms.)
//
// ✅ Example output:
//    up
//    stopping
//    done

// your code here

// keep this demo line LAST so it triggers your handler:
setTimeout(() => process.kill(process.pid, 'SIGTERM'), 100);

Common Errors (and the fix)

• App works locally, crashes in prod with "undefined" config — A required env var isn't set on the server. Load config with a fail-fast check so the cause is obvious at startup.
• "EADDRINUSE: address already in use" — Another process holds the port. Free it, or read the port from process.env.PORT so the platform can assign one.
• Deploys drop requests — No SIGTERM handler, so the platform kills the app mid-response. Add a graceful server.close() handler.
• Docker rebuild reinstalls everything every time — You copied source before npm ci, busting the cache. Copy package*.json first.
• Container ignores Ctrl-C / SIGTERM — You used the shell form of CMD. Switch to the exec/array form so Node gets the signal.

Pro Tips

• 💡 Fail fast on config: validate required env vars at boot so a misconfigured deploy crashes immediately instead of erroring randomly later.
• 💡 Use pm2 reload, not restart: reload drains old workers before swapping in new ones, giving you zero-downtime deploys.
• 💡 Pin your base image: node:22-alpine keeps images small and reproducible — avoid the floating latest tag.

📋 Quick Reference — Deployment

🎉 Lesson Complete!

• ✅ Read config from env vars and fail fast when a required one is missing
• ✅ NODE_ENV=production switches Express and libraries into optimized mode
• ✅ PM2 keeps your app alive, runs cluster mode, and reloads with zero downtime
• ✅ A cache-friendly Dockerfile copies package*.json before the source
• ✅ A /health route plus HEALTHCHECK tell the platform you're alive
• ✅ A SIGTERM handler with server.close() means deploys drop zero requests

Practice quiz

Continue this course

• Previous: MongoDB with Mongoose
• Next: Checkpoint: Build a REST API — Combine validation, JWT auth and logging into a JSON API — then a quiz
• Quick reference: Node.js cheat sheet · Docker cheat sheet › Dockerfile

Frequently asked questions

Why does setting NODE_ENV=production matter?

NODE_ENV is the conventional switch that tells your app and its libraries they're in production. Express, for example, caches view templates and skips verbose error pages when NODE_ENV is 'production', and many packages disable debug output or enable optimizations based on it. It also signals npm ci --omit=dev to skip dev dependencies. It is not magic — it only changes behavior in code that reads it — but the ecosystem has standardized on it, so always set it explicitly in production rather than relying on a default.

What does a process manager like PM2 actually do for me?

A bare 'node app.js' dies the moment it crashes or the server reboots, taking your site down. PM2 is a process manager that keeps the app alive: it restarts it automatically if it crashes, can run one instance per CPU core in cluster mode to use all your cores, aggregates and rotates logs, supports zero-downtime reloads, and (with pm2 startup + pm2 save) relaunches everything after a reboot. It turns a fragile foreground process into a supervised, resilient service. In a containerized setup the orchestrator (Docker/Kubernetes) plays a similar supervising role.

Why is graceful shutdown on SIGTERM important?

When a platform stops your app — a deploy, a scale-down, a container restart — it sends SIGTERM and then, after a grace period, SIGKILL. If you ignore SIGTERM, in-flight requests are cut off mid-response and connections to your database may not close cleanly. A graceful handler calls server.close() so the process stops accepting new connections but lets existing requests finish, closes database pools, and then exits 0. The result is zero dropped requests during deploys and restarts, which is essential for a reliable production service.

Why copy package.json before the rest of the code in a Dockerfile?

Docker builds images in layers and caches each one. Dependency installation (npm ci) is the slow step, but your dependencies change far less often than your source code. By copying only package.json and package-lock.json first and running npm ci, that expensive layer is cached and reused on every build where the manifests didn't change. If you copied all your source first, any one-line code change would invalidate the cache and force a full reinstall every build. Copying manifests first, then the source, gives you fast, cache-friendly builds.