DEV Community: Mushood

JWT Authentication in Express That You Can Actually Revoke

Mushood — Sat, 15 Aug 2026 21:38:04 +0000

Access tokens, refresh token rotation, and theft detection: the parts most Node.js tutorials leave out.

A friend messaged me about his side project a few months ago:

"Someone else is logged into my account. I changed my password. They're still in."

He had followed the tutorials to the letter. Sign a JWT on login, send it to the frontend, keep it in localStorage, attach it to every request. Done.

What none of those tutorials mentioned is that this setup has no way to un-log anyone in. A JWT is a signed piece of paper. Once you hand it over, it stays valid until it expires, and his expired in 30 days. Changing the password accomplished nothing, because the token had already been signed and nothing about it depended on the password. There was no list of active sessions to delete from. There was nothing to revoke.

His only remaining move was rotating the signing secret, which logged out every user on the platform at once. That was his entire kill switch: burn it all down.

This is the walkthrough I wish someone had handed me the first time I built auth. Token design, storage, refresh rotation, theft detection, the Express code, the Axios interceptor on the frontend, and the specific mistakes that turn a working login into an incident.

It's long. Auth is one of those areas where the missing ten percent is the part that gets you.

What the standard tutorial leaves out

Nearly every "JWT authentication in Node.js" post ends in the same place: sign a token, put it in localStorage, send a Bearer header. That gets you a demo. Four things stand between that and production.

localStorage is readable by any JavaScript on the page. That includes the analytics snippet you added last week, the npm package that got compromised upstream, and any XSS hole in your own code. One call to localStorage.getItem('token') and an attacker holds a working credential they can replay from their own machine. You can't detect it and you can't stop it.

There is no revocation. The appeal of JWTs is stateless verification: the server checks a signature and trusts the payload without touching the database. The price is that you can't take a token back. Ban a user and they stay logged in. Reset a password and the thief stays logged in.

Long expiry makes both of those catastrophic. Developers reach for a long TTL because nobody wants to be logged out every fifteen minutes. But long expiry is exactly what makes a stolen token worth stealing. You end up choosing between bad UX and a bad breach.

The payload isn't encrypted. base64url is encoding. Paste any JWT into jwt.io and read it. I've seen internal role hierarchies, email addresses, and on one occasion a live database connection string sitting in a token payload.

One architecture fixes all four: a very short-lived access token held in memory, plus a long-lived refresh token stored in an httpOnly cookie and tracked in your database.

The architecture

                    LOGIN
                      |
        +-------------+--------------+
        |                            |
  Access Token                 Refresh Token
  (JWT, 15 min)                (opaque, 30 days)
        |                            |
  Held in JS memory            httpOnly cookie
  Sent as:                     Sent automatically
  Authorization: Bearer ...    only to /auth/*
        |                            |
        v                            v
  Verified by signature        Looked up in DB,
  No DB call. Fast.            hashed, rotated
                               on every use

Two tokens doing two very different jobs.

The access token is a real JWT. Short-lived, verified purely by signature, never touches the database. That's what keeps your API fast. If it leaks, your exposure is fifteen minutes.

The refresh token is deliberately not a JWT. It's 64 random bytes. It lives in an httpOnly cookie so JavaScript can't read it, it's stored hashed so a database leak doesn't hand over live sessions, and every time it's used it gets replaced.

That last part, rotation, is what gives you theft detection. It's also the piece almost nobody implements, and it's the heart of Step 6.

Step 1: Setup and real secrets

mkdir jwt-auth-api && cd jwt-auth-api
npm init -y
npm install express jsonwebtoken bcrypt cookie-parser pg dotenv
npm install helmet express-rate-limit cors
npm install -D nodemon

Add "type": "module" to package.json so ESM imports work.

src/
  config/env.js
  db/index.js
  db/refreshTokens.js
  middleware/requireAuth.js
  routes/auth.js
  utils/tokens.js
  utils/cookies.js
  server.js

Now the thirty-second step people skip, which is how signing secrets end up being the literal string secret. For HS256 you want at least 256 bits of randomness:

node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"

Run it twice. You need two secrets and they must not be the same value.

# .env
NODE_ENV=development
PORT=5000

DATABASE_URL=postgres://user:pass@localhost:5432/myapp

JWT_ACCESS_SECRET=<first generated value>
JWT_REFRESH_PEPPER=<second generated value>

TOKEN_ISSUER=api.your-domain.com
TOKEN_AUDIENCE=your-domain.com
COOKIE_DOMAIN=.your-domain.com

If you've read my post on environment variables in Vite, the rules here are stricter. These values are backend-only. Never prefix them with VITE_, never let them reach a browser bundle, and put .env in .gitignore before you write a line of code.

A small config module means a missing variable fails at boot rather than at 3am:

// src/config/env.js
import 'dotenv/config';

function required(name) {
  const value = process.env[name];
  if (!value) throw new Error(`Missing required env variable: ${name}`);
  return value;
}

export const config = {
  isProd: process.env.NODE_ENV === 'production',
  port: process.env.PORT || 5000,
  accessSecret: required('JWT_ACCESS_SECRET'),
  refreshPepper: required('JWT_REFRESH_PEPPER'),
  issuer: required('TOKEN_ISSUER'),
  audience: required('TOKEN_AUDIENCE'),
  cookieDomain: process.env.COOKIE_DOMAIN,
  accessTtl: '15m',
  refreshTtlDays: 30,
};

Step 2: Signing and verifying tokens

// src/utils/tokens.js
import jwt from 'jsonwebtoken';
import crypto from 'node:crypto';
import { config } from '../config/env.js';

export function signAccessToken(user) {
  return jwt.sign(
    {
      sub: String(user.id),
      role: user.role,
      // Nothing sensitive. This payload is readable by anyone.
    },
    config.accessSecret,
    {
      algorithm: 'HS256',
      expiresIn: config.accessTtl,
      issuer: config.issuer,
      audience: config.audience,
      jwtid: crypto.randomUUID(),
    }
  );
}

export function verifyAccessToken(token) {
  return jwt.verify(token, config.accessSecret, {
    algorithms: ['HS256'],        // <- do not skip this line
    issuer: config.issuer,
    audience: config.audience,
  });
}

The algorithms: ['HS256'] line is not decoration.

Leave it out and you've told the library to accept whatever algorithm the token's own header claims. An attacker sets {"alg": "none"} and submits an unsigned token; older library versions accepted exactly that. It gets worse if you later migrate to RS256, where an attacker can take your public key, which is public by definition, and use it as an HMAC secret to sign tokens your server then verifies as valid.

The server decides the algorithm. Never the token.

The refresh token is a different animal:

export function generateRefreshToken() {
  return crypto.randomBytes(64).toString('base64url');
}

export function hashRefreshToken(token) {
  return crypto
    .createHmac('sha256', config.refreshPepper)
    .update(token)
    .digest('hex');
}

Two questions come up here every time.

Why isn't the refresh token a JWT? Because you're going to look it up in the database on every use anyway. That lookup is the entire point of it being revocable. A self-describing signed token buys you nothing and adds surface area to get wrong. 512 bits of randomness is simpler and unguessable.

Why HMAC-SHA256 instead of bcrypt? bcrypt is slow on purpose, to protect low-entropy secrets like human passwords from brute force. A 512-bit random token has no brute-force risk; nobody is guessing it. What you actually need is a fast one-way transform so a leaked database dump contains no usable sessions. HMAC with a server-side pepper does that and is cheap enough to run on every request. bcrypt also silently truncates input past 72 bytes, which would quietly weaken the token you just generated.

Step 3: The refresh token table

CREATE TABLE users (
  id            BIGSERIAL PRIMARY KEY,
  email         CITEXT NOT NULL UNIQUE,
  password_hash TEXT NOT NULL,
  role          TEXT NOT NULL DEFAULT 'user',
  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE TABLE refresh_tokens (
  id          BIGSERIAL PRIMARY KEY,
  user_id     BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  token_hash  CHAR(64) NOT NULL UNIQUE,
  family_id   UUID NOT NULL,
  expires_at  TIMESTAMPTZ NOT NULL,
  revoked_at  TIMESTAMPTZ,
  replaced_by CHAR(64),
  user_agent  TEXT,
  ip          INET,
  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_rt_user   ON refresh_tokens(user_id);
CREATE INDEX idx_rt_family ON refresh_tokens(family_id);
CREATE INDEX idx_rt_expiry ON refresh_tokens(expires_at);

CITEXT needs CREATE EXTENSION IF NOT EXISTS citext; first. Use TEXT with a lowercase-on-write rule if you'd rather not add the extension.

Three columns carry most of the design, so they're worth explaining before the code.

family_id groups every token descended from one login. Laptop login is family A; each refresh in that session keeps family_id = A. Phone login is family B. This lets you kill one compromised session without logging the user out of everything, and when theft is detected, kill an entire chain at once.

revoked_at marks a token as spent. Rotation makes refresh tokens single-use: the moment one is exchanged, it's dead.

replaced_by records which token superseded it. Handy for debugging, and load-bearing for the race condition in Step 6.

The repository:

// src/db/refreshTokens.js
import crypto from 'node:crypto';
import { pool } from './index.js';
import { config } from '../config/env.js';

export async function createRefreshToken({
  userId, tokenHash, familyId, userAgent, ip,
}) {
  const expiresAt = new Date(
    Date.now() + config.refreshTtlDays * 24 * 60 * 60 * 1000
  );
  const { rows } = await pool.query(
    `INSERT INTO refresh_tokens
       (user_id, token_hash, family_id, expires_at, user_agent, ip)
     VALUES ($1, $2, $3, $4, $5, $6)
     RETURNING *`,
    [userId, tokenHash, familyId ?? crypto.randomUUID(), expiresAt, userAgent, ip]
  );
  return rows[0];
}

export async function findByHash(tokenHash) {
  const { rows } = await pool.query(
    `SELECT * FROM refresh_tokens WHERE token_hash = $1`,
    [tokenHash]
  );
  return rows[0] ?? null;
}

export async function revokeToken(id, replacedByHash = null) {
  await pool.query(
    `UPDATE refresh_tokens
        SET revoked_at = NOW(), replaced_by = $2
      WHERE id = $1 AND revoked_at IS NULL`,
    [id, replacedByHash]
  );
}

export async function revokeFamily(familyId) {
  await pool.query(
    `UPDATE refresh_tokens
        SET revoked_at = NOW()
      WHERE family_id = $1 AND revoked_at IS NULL`,
    [familyId]
  );
}

export async function revokeAllForUser(userId) {
  await pool.query(
    `UPDATE refresh_tokens
        SET revoked_at = NOW()
      WHERE user_id = $1 AND revoked_at IS NULL`,
    [userId]
  );
}

export async function deleteExpired() {
  const { rowCount } = await pool.query(
    `DELETE FROM refresh_tokens
      WHERE expires_at < NOW() - INTERVAL '7 days'`
  );
  return rowCount;
}

Run deleteExpired() on a daily cron. This table grows fast and nobody notices until it's twelve million rows.

On Prisma or Mongoose? Same columns, same six operations. Only the query syntax changes.

Step 4: Cookie settings that matter

Small file. A surprising number of auth bugs live in it.

// src/utils/cookies.js
import { config } from '../config/env.js';

export const REFRESH_COOKIE = 'rt';

export function refreshCookieOptions() {
  return {
    httpOnly: true,                 // JavaScript cannot read it
    secure: config.isProd,          // HTTPS only in production
    sameSite: 'strict',             // not sent on cross-site requests
    path: '/auth',                  // only sent to /auth/* endpoints
    domain: config.isProd ? config.cookieDomain : undefined,
    maxAge: config.refreshTtlDays * 24 * 60 * 60 * 1000,
  };
}

Every option earns its place.

httpOnly is the entire reason we're using a cookie. XSS can still make requests as the user, but it can't lift the credential and replay it from somewhere else next month.
secure keeps the cookie off plain HTTP. It's disabled in development so localhost works, though if you'd rather run HTTPS locally and match production, I covered that in setting up mkcert with Express.
sameSite: 'strict' is your CSRF defence. The browser won't attach the cookie to requests that originate on another site.
path: '/auth' keeps the cookie off your regular API calls entirely. It goes out only when you're refreshing. Less exposure, smaller headers.

The cross-site gotcha. sameSite: 'strict' works when frontend and API share a registrable domain, so app.example.com calling api.example.com is fine. But a frontend on myapp.vercel.app calling api.mycompany.com is genuinely cross-site, and the cookie simply won't be sent. Your refresh fails with no error message, which is a deeply annoying afternoon.

The workaround is sameSite: 'none' with secure: true, and since that disables your CSRF protection you then need a CSRF token or an Origin check on the refresh endpoint. My advice: put the API on a subdomain of your frontend's domain and skip the whole problem.

Step 5: Register and login

// src/routes/auth.js
import express from 'express';
import bcrypt from 'bcrypt';
import crypto from 'node:crypto';
import rateLimit from 'express-rate-limit';
import { pool } from '../db/index.js';
import { config } from '../config/env.js';
import * as tokenStore from '../db/refreshTokens.js';
import { requireAuth } from '../middleware/requireAuth.js';
import {
  signAccessToken, generateRefreshToken, hashRefreshToken,
} from '../utils/tokens.js';
import { REFRESH_COOKIE, refreshCookieOptions } from '../utils/cookies.js';

const router = express.Router();

const loginLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 10,
  standardHeaders: true,
  legacyHeaders: false,
  message: { error: 'Too many attempts. Try again later.' },
});

// A valid bcrypt hash of a random string, used to equalise response
// timing when the email doesn't exist.
const DUMMY_HASH =
  '$2b$12$C6UzMDM.H6dfI/f/IKcEe.7qJ8gxvKk1z4qYyWPq7Xo5nJ8VtQ4Ky';

async function issueSession(res, user, req, familyId = null) {
  const refreshToken = generateRefreshToken();
  const tokenHash = hashRefreshToken(refreshToken);

  await tokenStore.createRefreshToken({
    userId: user.id,
    tokenHash,
    familyId,
    userAgent: req.get('user-agent') ?? null,
    ip: req.ip,
  });

  res.cookie(REFRESH_COOKIE, refreshToken, refreshCookieOptions());

  return signAccessToken(user);
}

Register

router.post('/register', async (req, res) => {
  const { email, password } = req.body ?? {};

  if (!email || !password) {
    return res.status(400).json({ error: 'Email and password are required' });
  }
  if (password.length < 12) {
    return res.status(400).json({ error: 'Password must be at least 12 characters' });
  }

  const passwordHash = await bcrypt.hash(password, 12);

  try {
    const { rows } = await pool.query(
      `INSERT INTO users (email, password_hash)
       VALUES ($1, $2)
       RETURNING id, email, role`,
      [email.toLowerCase().trim(), passwordHash]
    );
    const user = rows[0];
    const accessToken = await issueSession(res, user, req);

    return res.status(201).json({
      accessToken,
      user: { id: user.id, email: user.email, role: user.role },
    });
  } catch (err) {
    if (err.code === '23505') {
      // Unique violation. Don't confirm the email exists.
      return res.status(409).json({ error: 'Could not create account' });
    }
    throw err;
  }
});

Note the length minimum and the absence of composition rules. "At least one uppercase, one number, one symbol" reliably produces Password1! and very little else. Length is what actually helps.

Login

router.post('/login', loginLimiter, async (req, res) => {
  const { email, password } = req.body ?? {};

  if (!email || !password) {
    return res.status(400).json({ error: 'Email and password are required' });
  }

  const { rows } = await pool.query(
    `SELECT id, email, role, password_hash FROM users WHERE email = $1`,
    [email.toLowerCase().trim()]
  );
  const user = rows[0];

  // Always run a comparison, even when the user doesn't exist,
  // so response time doesn't leak which emails are registered.
  const valid = await bcrypt.compare(password, user?.password_hash ?? DUMMY_HASH);

  if (!user || !valid) {
    return res.status(401).json({ error: 'Invalid email or password' });
  }

  const accessToken = await issueSession(res, user, req);

  return res.json({
    accessToken,
    user: { id: user.id, email: user.email, role: user.role },
  });
});

Two choices there are deliberate.

The error message is identical for "no such email" and "wrong password." Return "user not found" and you've built an account enumeration endpoint: an attacker walks a list of emails and learns exactly who has an account with you. Pair that with a breach dump from another site and you've handed over a credential-stuffing target list.

The dummy hash matters just as much. Without it, a nonexistent email returns almost immediately while a real one takes as long as bcrypt takes, which at cost factor 12 is a very visible difference. That gap is measurable over a network and leaks precisely the information your generic error message was trying to hide.

Also notice the access token goes in the JSON body, not a cookie. The frontend keeps it in memory, which we'll get to shortly.

Step 6: Refresh, rotation, and reuse detection

This is the important one. Everything else here is fairly standard. This is the part that turns "JWT auth" into something you can defend.

router.post('/refresh', async (req, res) => {
  const presented = req.cookies?.[REFRESH_COOKIE];

  if (!presented) {
    return res.status(401).json({ error: 'Not authenticated', code: 'NO_REFRESH_TOKEN' });
  }

  const presentedHash = hashRefreshToken(presented);
  const stored = await tokenStore.findByHash(presentedHash);

  // Unknown token: forged, or from a family we already purged.
  if (!stored) {
    res.clearCookie(REFRESH_COOKIE, refreshCookieOptions());
    return res.status(401).json({ error: 'Invalid session', code: 'INVALID_REFRESH_TOKEN' });
  }

  // ---- REUSE DETECTION ----
  // This token was already spent. Someone is replaying it.
  if (stored.revoked_at) {
    await tokenStore.revokeFamily(stored.family_id);
    res.clearCookie(REFRESH_COOKIE, refreshCookieOptions());

    console.warn('[security] refresh token reuse detected', {
      userId: stored.user_id,
      familyId: stored.family_id,
      ip: req.ip,
      userAgent: req.get('user-agent'),
    });

    return res.status(401).json({ error: 'Session revoked', code: 'TOKEN_REUSE' });
  }

  if (new Date(stored.expires_at) < new Date()) {
    res.clearCookie(REFRESH_COOKIE, refreshCookieOptions());
    return res.status(401).json({ error: 'Session expired', code: 'REFRESH_EXPIRED' });
  }

  const { rows } = await pool.query(
    `SELECT id, email, role FROM users WHERE id = $1`,
    [stored.user_id]
  );
  const user = rows[0];

  if (!user) {
    await tokenStore.revokeFamily(stored.family_id);
    res.clearCookie(REFRESH_COOKIE, refreshCookieOptions());
    return res.status(401).json({ error: 'Invalid session', code: 'USER_GONE' });
  }

  // ---- ROTATE ----
  const newRefreshToken = generateRefreshToken();
  const newHash = hashRefreshToken(newRefreshToken);

  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    await client.query(
      `UPDATE refresh_tokens
          SET revoked_at = NOW(), replaced_by = $2
        WHERE id = $1 AND revoked_at IS NULL`,
      [stored.id, newHash]
    );
    await client.query(
      `INSERT INTO refresh_tokens
         (user_id, token_hash, family_id, expires_at, user_agent, ip)
       VALUES ($1, $2, $3, $4, $5, $6)`,
      [
        user.id,
        newHash,
        stored.family_id,
        new Date(Date.now() + config.refreshTtlDays * 86400_000),
        req.get('user-agent') ?? null,
        req.ip,
      ]
    );
    await client.query('COMMIT');
  } catch (err) {
    await client.query('ROLLBACK');
    throw err;
  } finally {
    client.release();
  }

  res.cookie(REFRESH_COOKIE, newRefreshToken, refreshCookieOptions());

  return res.json({
    accessToken: signAccessToken(user),
    user: { id: user.id, email: user.email, role: user.role },
  });
});

Why reuse detection actually works

This deserves spelling out, because when I first read about rotation I understood the mechanic and completely missed the point.

Refresh tokens are single-use. Use one, it dies, you get a new one. So a token can only ever be presented twice if two parties are holding the same token, and that only happens if one of them stole it.

Play out the theft:

Attacker obtains refresh token R1 somehow. Malware, a leaked log, a shared machine.
Attacker calls /auth/refresh with R1. It works. They get R2 and an access token. So far you've lost.
Fifteen minutes later your real user's access token expires. Their browser calls /auth/refresh with R1, the only token it has.
R1 is already revoked. Detected.
The whole family dies. The attacker's R2, R3, everything downstream. Both parties get logged out.

Reverse the order, with the real user refreshing first and the attacker replaying later, and detection fires just the same. Either way you catch the theft within one refresh cycle instead of thirty days later, and you catch it automatically, with nobody having to report anything.

That is the difference between my friend's situation and a system that defends itself.

The race condition nobody warns you about

Ship the code above and eventually a user emails you saying they got randomly logged out.

Here's what happened. Three tabs open. All three woke at once, all three fired requests carrying the same expired access token, all three got a 401, all three called /auth/refresh with the same R1. The first won. The other two tripped reuse detection and killed the family.

You've built a system that logs people out for using tabs.

There are two fixes and you want both.

Client side, the real one: deduplicate refresh calls so only one is ever in flight. Code for that is in Step 8.

Server side, the safety net: allow a short grace window. If a revoked token was replaced a couple of seconds ago, that's almost certainly a race and not an attacker, so hand back the replacement instead of burning the session.

const GRACE_MS = 10_000;

if (stored.revoked_at) {
  const age = Date.now() - new Date(stored.revoked_at).getTime();
  const replacement = stored.replaced_by
    ? await tokenStore.findByHash(stored.replaced_by)
    : null;

  const isLikelyRace =
    age < GRACE_MS && replacement && !replacement.revoked_at;

  if (!isLikelyRace) {
    await tokenStore.revokeFamily(stored.family_id);
    res.clearCookie(REFRESH_COOKIE, refreshCookieOptions());
    return res.status(401).json({ error: 'Session revoked', code: 'TOKEN_REUSE' });
  }

  // Concurrent refresh. Reissue an access token against the live
  // replacement without rotating again.
  const { rows } = await pool.query(
    `SELECT id, email, role FROM users WHERE id = $1`, [stored.user_id]
  );
  return res.json({ accessToken: signAccessToken(rows[0]) });
}

Ten seconds is a genuine trade-off rather than a free win. A fast attacker inside that window slips through. But logging out legitimate users daily is worse than a ten-second gap in a detection mechanism most systems don't have at all. Tighten it if your threat model demands it.

Step 7: Middleware, and the authorization bug everyone ships

// src/middleware/requireAuth.js
import { verifyAccessToken } from '../utils/tokens.js';

export function requireAuth(req, res, next) {
  const header = req.headers.authorization;

  if (!header?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Not authenticated', code: 'NO_TOKEN' });
  }

  try {
    const payload = verifyAccessToken(header.slice(7));
    req.user = { id: payload.sub, role: payload.role };
    return next();
  } catch (err) {
    if (err.name === 'TokenExpiredError') {
      // Distinct code: the client should refresh, not log out.
      return res.status(401).json({ error: 'Token expired', code: 'TOKEN_EXPIRED' });
    }
    return res.status(401).json({ error: 'Invalid token', code: 'INVALID_TOKEN' });
  }
}

export function requireRole(...roles) {
  return (req, res, next) => {
    if (!req.user) {
      return res.status(401).json({ error: 'Not authenticated' });
    }
    if (!roles.includes(req.user.role)) {
      return res.status(403).json({ error: 'Forbidden' });
    }
    return next();
  };
}

That separate TOKEN_EXPIRED code looks trivial and isn't. Without it your frontend sees a generic 401 and can't distinguish "your token aged out, refresh quietly" from "your token is garbage, log out." Get it wrong and you either log people out constantly or send them into an infinite refresh loop.

Using it:

router.get('/me', requireAuth, async (req, res) => {
  const { rows } = await pool.query(
    `SELECT id, email, role, created_at FROM users WHERE id = $1`,
    [req.user.id]     // <- from the verified token. Never from req.body.
  );
  res.json(rows[0]);
});

router.delete('/admin/users/:id', requireAuth, requireRole('admin'), handler);

That comment deserves its own paragraph. The most common authorization bug I've found in code review looks like this:

// Broken. Anyone can pass any userId.
router.get('/orders', requireAuth, async (req, res) => {
  const orders = await db.orders.findByUser(req.query.userId);
  res.json(orders);
});

The request was authenticated. It was never authorized. The user proved who they were, then told you whose data to fetch, and you believed them. Identity comes from req.user, which came from a verified signature. Anything in the body, query, or params is user input.

Step 8: Logout and the kill switch

router.post('/logout', async (req, res) => {
  const presented = req.cookies?.[REFRESH_COOKIE];

  if (presented) {
    const stored = await tokenStore.findByHash(hashRefreshToken(presented));
    if (stored) {
      // Kill the whole family, not just this token — otherwise the
      // rest of the chain stays valid.
      await tokenStore.revokeFamily(stored.family_id);
    }
  }

  res.clearCookie(REFRESH_COOKIE, refreshCookieOptions());
  return res.status(204).end();
});

// "Log out everywhere" — use this on password change too.
router.post('/logout-all', requireAuth, async (req, res) => {
  await tokenStore.revokeAllForUser(req.user.id);
  res.clearCookie(REFRESH_COOKIE, refreshCookieOptions());
  return res.status(204).end();
});

Call revokeAllForUser whenever a user changes their password, changes their email, or disables 2FA. This is the kill switch my friend didn't have.

One limitation is worth being honest about: access tokens already issued stay valid until they expire. Logout kills the refresh chain, so the session can't continue past the current access token, but there's a window of up to fifteen minutes.

If your app can't tolerate that window, meaning banking, healthcare, anywhere "log out" has to mean now, you need a denylist. On logout, write the access token's jti to Redis with a TTL matching its remaining lifetime and have requireAuth check it. That costs a Redis lookup on every request and gives back some of the statelessness you chose JWTs for. Most apps should shorten the access TTL to five minutes and accept the gap.

Step 9: The frontend half

The backend is only half of this, and getting the client wrong undoes the rest.

// src/lib/api.js
import axios from 'axios';

let accessToken = null;
let refreshPromise = null;

export const setAccessToken = (t) => { accessToken = t; };
export const getAccessToken = () => accessToken;

export const api = axios.create({
  baseURL: import.meta.env.VITE_API_URL,
  withCredentials: true,   // required, or the refresh cookie never goes out
});

api.interceptors.request.use((cfg) => {
  if (accessToken) cfg.headers.Authorization = `Bearer ${accessToken}`;
  return cfg;
});

async function refreshAccessToken() {
  const { data } = await axios.post(
    `${import.meta.env.VITE_API_URL}/auth/refresh`,
    {},
    { withCredentials: true }
  );
  setAccessToken(data.accessToken);
  return data.accessToken;
}

api.interceptors.response.use(
  (res) => res,
  async (error) => {
    const original = error.config;

    if (error.response?.status !== 401 || original._retried) {
      return Promise.reject(error);
    }

    // Only an expired token is worth refreshing. Anything else
    // means the session is genuinely dead.
    if (error.response.data?.code !== 'TOKEN_EXPIRED') {
      handleLoggedOut();
      return Promise.reject(error);
    }

    original._retried = true;

    // Single-flight: every concurrent 401 awaits the same refresh.
    refreshPromise ??= refreshAccessToken().finally(() => {
      refreshPromise = null;
    });

    try {
      const fresh = await refreshPromise;
      original.headers.Authorization = `Bearer ${fresh}`;
      return api(original);
    } catch (err) {
      handleLoggedOut();
      return Promise.reject(err);
    }
  }
);

function handleLoggedOut() {
  setAccessToken(null);
  window.location.href = '/login';
}

Four things there are doing real work.

refreshPromise ??= is the single-flight guard, the client-side half of the race fix from Step 6. Ten requests fail at once, the first starts a refresh, the other nine await that same promise. One network call, one rotation, no false reuse detection.

original._retried prevents an infinite loop, which is what you get when a refresh succeeds but the retried request still fails.

Checking code === 'TOKEN_EXPIRED' stops you from trying to refresh a session that's genuinely over.

withCredentials: true appears on both the instance and the raw refresh call. Miss it and the cookie never goes out, silently, which makes it maddening to debug. Your API needs matching CORS:

app.use(cors({
  origin: process.env.FRONTEND_URL,   // never '*' with credentials
  credentials: true,
}));

Every browser rejects origin: '*' alongside credentials: true. If your refresh works in Postman and dies in the browser, this is usually the reason.

"Won't users get logged out every time they reload?"

This is the standard objection to in-memory tokens and it has a clean answer: on app boot, call /auth/refresh once.

The access token is gone, since it lived in a JavaScript variable. The refresh cookie survived the reload, because that's what cookies do. So you exchange it for a fresh access token before rendering anything.

// src/App.jsx
import { useEffect, useState } from 'react';
import { api, setAccessToken } from './lib/api';

export default function App() {
  const [state, setState] = useState({ status: 'loading', user: null });

  useEffect(() => {
    let cancelled = false;

    (async () => {
      try {
        const { data } = await api.post('/auth/refresh');
        if (cancelled) return;
        setAccessToken(data.accessToken);
        setState({ status: 'authenticated', user: data.user });
      } catch {
        if (!cancelled) setState({ status: 'anonymous', user: null });
      }
    })();

    return () => { cancelled = true; };
  }, []);

  if (state.status === 'loading') return <FullPageSpinner />;
  return state.status === 'authenticated'
    ? <AuthenticatedApp user={state.user} />
    : <LoginPage />;
}

One extra round trip on cold load, and in exchange the credential never touches localStorage. That's a very good trade.

If you're managing this with Zustand, as in my Axios + Zustand + Persist post, one warning: do not put the access token in the persisted slice. persist writes to localStorage, which reintroduces the exact problem this architecture exists to avoid. Persist the user profile for a nicer loading state if you want. Keep the token in a field that never gets written out.

Step 10: Wiring the server together

// src/server.js
import express from 'express';
import helmet from 'helmet';
import cors from 'cors';
import cookieParser from 'cookie-parser';
import authRoutes from './routes/auth.js';
import { config } from './config/env.js';

const app = express();

app.set('trust proxy', 1);        // behind Nginx — required for correct req.ip
app.use(helmet());
app.use(cors({ origin: process.env.FRONTEND_URL, credentials: true }));
app.use(express.json({ limit: '10kb' }));
app.use(cookieParser());

app.use('/auth', authRoutes);

app.use((err, req, res, _next) => {
  console.error(err);
  res.status(500).json({ error: 'Internal server error' });
});

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

app.set('trust proxy', 1) matters if you deployed the way I described in the Nginx + PM2 post. Without it req.ip is 127.0.0.1 for every request, which means your rate limiter throttles all users as a single client and your security logs are worthless. Make sure Nginx forwards the real address:

proxy_set_header X-Real-IP        $remote_addr;
proxy_set_header X-Forwarded-For  $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

The footgun list

Quick reference. Most of these I've either shipped myself or caught in review.

Mistake	What it costs you
Access token in `localStorage`	Any XSS is a permanent account takeover
No `algorithms: ['HS256']` on verify	`alg: none` and algorithm confusion attacks
Access token TTL measured in days	Nothing to revoke, huge damage window
Same secret for access and refresh	One leak compromises both layers
Secret is `"secret"` or `"mysecretkey"`	Anyone can mint valid tokens for any user
Sensitive data in the JWT payload	It's base64. Everyone can read it
No `expiresIn`	Immortal tokens
Refresh tokens stored in plaintext	DB leak = every live session handed over
Refresh token not rotated	Theft is undetectable
No rate limit on `/login`	Free credential stuffing
Trusting `req.body.userId`	Any user reads any user's data
Generic 401 with no error code	Infinite refresh loops or constant logouts
`origin: '*'` with `credentials: true`	CORS silently blocks every cookie
Logging tokens	Your logs become a credential store
Never cleaning `refresh_tokens`	A table with ten million dead rows

So why not just use sessions?

I want to end on this, because it's the question you should have been asking the whole way down.

If you've been paying attention, something awkward has become obvious: we hit the database on every refresh. We store token state. We revoke it. That's a session table. We've built sessions with extra steps.

Fair criticism. Here's my honest position.

Plain sessions win when you have one backend serving one frontend, everything lives in one place, and you already run Redis or Postgres. express-session plus a store is fewer moving parts, revocation is instant and total, and there's no rotation logic to get subtly wrong. For most projects most of the time, that's the right answer. The reason people skip it is that it feels less modern, which is not a technical reason.

The split-token setup wins when several services need to verify identity without calling a central auth service, or you have a mobile app where cookie handling is awkward, or third-party clients consume your API, or your access checks are hot enough that a per-request database lookup shows up in your latency numbers.

The real advantage here isn't statelessness. It's the ratio. Your access token gets checked thousands of times with zero database work. Your refresh token gets checked once every fifteen minutes with full stateful control. Fast verification where verification is frequent, real revocation where revocation matters.

That's the actual argument for JWTs. Not "stateless is better." Nobody needs the auth on their CRUD app to be stateless.

Production checklist

[ ] Both secrets are 32+ random bytes, and they differ from each other
[ ] Secrets come from the environment, never from source
[ ] Access token TTL is 15 minutes or less
[ ] algorithms is pinned explicitly on every jwt.verify call
[ ] Refresh tokens are hashed in the database
[ ] Rotation is on, with reuse detection and a grace window
[ ] Cookie is httpOnly, secure, sameSite, path-scoped
[ ] /login, /register, and /refresh are rate limited
[ ] Password change calls revokeAllForUser
[ ] CORS origin is your real frontend URL, with credentials: true
[ ] trust proxy is set if you're behind Nginx
[ ] Reuse-detection events are logged and alert someone
[ ] A cron job clears expired tokens
[ ] No token, hash, or password appears in any log line
[ ] The frontend does single-flight refresh
[ ] The access token is not in localStorage, sessionStorage, or a persisted store

Auth is the one part of your app where the failure mode isn't a bug report. It's a message from someone who can't get a stranger out of their account.

The whole design reduces to a single idea: separate the credential you use constantly from the credential you can take back. The access token is fast, short-lived, and disposable, and if it leaks you lose fifteen minutes. The refresh token is slow, tracked, rotated, and revocable, and if it leaks, rotation catches the theft the next time either party uses it. Neither one gets you there alone. Together you get speed on the hot path and control on the cold one.

Build the revocation path before you need it. That's what my friend was missing, and it's what the tutorials leave out.

If this was useful, follow me. I write about backend, DevOps, and the things that break in production. Next up: automating VPS deploys with GitHub Actions.

I Stopped SSH-ing Into My Server to Deploy — Here’s the 30 Lines of YAML That Replaced It

Mushood — Mon, 03 Aug 2026 22:54:55 +0000

Automatic Node.js deployments on any VPS, using GitHub Actions, PM2, and a shell script that lives on the server.

Last month I merged a one-line fix at nine o'clock on a Friday night.

Then came the ritual. Open a terminal. SSH into the box. cd into the project. git pull. npm install. pm2 restart backend-api. Sit there for a few seconds waiting to find out whether anything caught fire.

Six commands for a single changed line.

I've run that sequence something like four hundred times, and every run carries a small tax. Wrong terminal tab. Wrong server. Skipping npm install and then burning twenty minutes hunting a missing dependency that was sitting in package.json the whole time. The commands aren't difficult. Remembering all of them, in order, while tired, is where it goes wrong.

In an earlier post I walked through getting a Node.js backend live on a VPS behind Nginx with PM2. That guide stopped at the manual deploy.

This one throws the manual deploy away.

By the time you finish reading, a merge into main will ship your backend without you. SSH becomes something you use when something's genuinely broken, not something you use on Fridays.

What the Pipeline Actually Does

The shape of it:

You merge a PR into main
  |
  v
GitHub Actions runner starts
  |
  v
Runner SSHs into your VPS with a deploy key
  |
  v
deploy.sh runs: git pull -> npm ci -> pm2 reload
  |
  v
App is live, no downtime

The part worth internalizing: GitHub Actions never builds your app or ships files anywhere. It logs into your server and tells the server to go update itself. That's the whole trick.

For one VPS, this is almost always the right call. No container registry. No artifact uploads. No orchestration layer you'll spend a weekend learning. A key, a script, and a workflow file.

What You Need Before Any of This Works

I'm assuming you've already got:

A Node.js backend running on a VPS under PM2
The project cloned on that server from a Git repository
Nginx sitting in front of it

If any of those are missing, stop here and go set them up. Automating a deployment that doesn't work by hand doesn't give you a pipeline — it gives you two broken things instead of one, and no clear way to tell them apart.

Step 1: Generate a Deploy Key That Only Deploys

Never reuse your personal SSH key for this. Not once, not "just to test it."

The moment your personal private key lands in GitHub Secrets, every collaborator with admin rights on that repo is one workflow file away from everything that key touches. That's not a hypothetical — it's a two-minute exercise for anyone who wants to try.

Make a dedicated key on your local machine:

ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/deploy_key -N ""

You get two files out of that:

~/.ssh/deploy_key — the private half. This one goes into GitHub Secrets.
~/.ssh/deploy_key.pub — the public half. This one goes on your server.

The -N "" flag creates the key without a passphrase. Yes, a passphrase would be stronger. No, GitHub Actions can't type one at three in the morning. So this key ships bare — which is precisely the argument for giving it its own narrow job and nothing else.

Step 2: Install the Public Key on Your Server

Push it up:

ssh-copy-id -i ~/.ssh/deploy_key.pub your-user@your-server-ip

No ssh-copy-id on your machine? Do it the long way. Print the key:

cat ~/.ssh/deploy_key.pub

Then on the server:

nano ~/.ssh/authorized_keys

Drop the key onto its own line and save.

Before you go anywhere near GitHub, prove the key works:

ssh -i ~/.ssh/deploy_key your-user@your-server-ip

If that doesn't log you in, nothing downstream will either. Sort it out now, at the layer where the error messages still make sense to a human.

Step 3: Store Four Secrets in GitHub

In your repository, head to:

Settings → Secrets and variables → Actions → New repository secret

Add these four:

Secret name	Value
`VPS_HOST`	your server IP or domain
`VPS_USER`	the SSH user, e.g. `ubuntu`
`VPS_SSH_KEY`	the entire contents of `~/.ssh/deploy_key`
`VPS_PORT`	`22`, or whatever custom SSH port you run

For that third one:

cat ~/.ssh/deploy_key

Copy all of it. The -----BEGIN OPENSSH PRIVATE KEY----- line. The -----END OPENSSH PRIVATE KEY----- line. The trailing newline after it.

Roughly half the Permission denied (publickey) failures you'll ever stare at in a deploy log trace back to someone who grabbed only the middle chunk.

Step 4: Put the Deploy Logic in a Script on the Server

You could stuff every deploy command straight into the workflow YAML.

Don't.

Keep them in a script that lives on the server, because:

You can run it by hand whenever you need to
You can test changes without pushing a commit to trigger anything
Editing your deploy steps stops meaning editing your CI config

On the server:

nano ~/deploy.sh

Here's the script:

#!/bin/bash
set -euo pipefail

APP_DIR="$HOME/your-backend-repo"
APP_NAME="backend-api"
BRANCH="main"

echo "==> Deploying $APP_NAME"

cd "$APP_DIR"

echo "==> Pulling latest code"
git fetch origin "$BRANCH"
git reset --hard "origin/$BRANCH"

echo "==> Installing dependencies"
npm ci --omit=dev

echo "==> Reloading PM2"
pm2 reload "$APP_NAME" --update-env

echo "==> Deploy complete"

Make it executable:

chmod +x ~/deploy.sh

Short script, but several of those lines are carrying real weight.

`set -euo pipefail`

Halts the script the instant something fails. Leave it out and npm ci can blow up while the script cheerfully reloads PM2 anyway — handing you a green checkmark on a deploy that just took production down.

`git reset --hard` rather than `git pull`

git pull chokes on merge conflicts, which is exactly what you get when someone edits a file directly on the server. reset --hard forces the working tree to match the remote branch and asks no questions. Your server shouldn't be holding local changes in the first place. If it is, that's the actual bug — not the thing the deploy script needs to negotiate with.

`npm ci` rather than `npm install`

ci installs precisely what's pinned in package-lock.json and fails loudly when the lockfile has drifted. install will quietly resolve to versions you never tested against, which is a fun problem to discover in production at 2am.

`pm2 reload` rather than `pm2 restart`

restart kills the process, then starts a fresh one — and requests arriving in that gap get refused. reload spins up the replacement before retiring the old process. On a single instance the window shrinks to almost nothing; in cluster mode it really is zero downtime.

Now run it yourself, once:

~/deploy.sh

Get a clean run here before you automate anything.

Step 5: Write the Workflow

Back on your local machine, inside the repo:

mkdir -p .github/workflows
nano .github/workflows/deploy.yml

The whole thing:

name: Deploy Backend

on:
  push:
    branches: [main]
  workflow_dispatch:

concurrency:
  group: production-deploy
  cancel-in-progress: false

jobs:
  deploy:
    name: Deploy to VPS
    runs-on: ubuntu-latest

    steps:
      - name: Deploy over SSH
        uses: appleboy/ssh-action@v1.2.0
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USER }}
          key: ${{ secrets.VPS_SSH_KEY }}
          port: ${{ secrets.VPS_PORT }}
          script_stop: true
          script: |
            export NVM_DIR="$HOME/.nvm"
            [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
            bash ~/deploy.sh

Commit it and push.

Two lines in there deserve a closer look.

workflow_dispatch puts a "Run workflow" button in your Actions tab. The first time you need to redeploy without producing a new commit — and that day comes — you'll be glad it's sitting there.

concurrency keeps two deploys from stepping on each other. Merge two pull requests thirty seconds apart without it and you've got two git reset --hard calls racing in the same directory. Setting cancel-in-progress: false tells the second run to queue up and wait rather than get discarded.

Step 6: Merge Something and Watch

Push a change into main, then open the Actions tab.

You'll watch the job spin up, connect over SSH, and stream every line of deploy.sh straight into the log. Same output you'd have seen in your terminal, minus the terminal.

Green? You're finished. Go delete that text file of deploy commands you've been keeping.

The Error Nearly Everyone Hits First

bash: line 1: pm2: command not found

This one catches almost everybody, and it isn't a mistake on your part.

When you SSH in as a person, bash reads ~/.bashrc and ~/.profile — and if you installed Node through nvm, that's where pm2 gets added to your PATH. When GitHub Actions runs a command over SSH, it opens a non-interactive shell. Those files never get sourced. Your PATH shows up nearly empty, and as far as that shell is concerned, pm2 doesn't exist.

The two NVM_DIR lines in the workflow above solve it by loading nvm by hand before the script runs.

Installed Node from NodeSource instead of nvm, like in my VPS post? Then there's no nvm to load, those lines are harmless no-ops, and pm2 should already be sitting at /usr/bin/pm2. Still not found? Track it down:

which pm2

And use the full path inside deploy.sh:

/usr/bin/pm2 reload "$APP_NAME" --update-env

Four Other Things That Will Trip You Up

Host key verification failed. Your server has never spoken to the Git remote before and doesn't trust its fingerprint. SSH in manually, run git fetch once, accept the fingerprint, and it never asks again.

A private repo the server can't clone. The server needs read access of its own. Generate a key on the server, then add the public half under Repository Settings → Deploy keys. Leave write access switched off — the server only ever needs to read.

Your .env isn't on the server. Good. It's gitignored and it should stay gitignored. The file belongs on the server and nowhere else, and nothing in this pipeline goes near it. That's the design working, not a gap in it.

npm ci failing with a lockfile error. Your package-lock.json has fallen out of sync. Run npm install locally, commit the refreshed lockfile, push again.

Three Upgrades Worth Fifteen Minutes

Once the basic pipeline is green, these are the additions that pay for themselves fastest.

Run your tests first

Add a job the deploy depends on:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      # ... the SSH step from before

needs: test means a red test suite blocks the deploy outright. No override, no judgment call at midnight.

Add a health check

A deploy that completed isn't the same thing as an app that's serving traffic. Tack this onto the end of deploy.sh:

sleep 5
curl -fsS https://your-domain.com/health || {
  echo "Health check failed"
  exit 1
}

Now a broken release surfaces as a red X in GitHub within seconds, instead of as a support ticket six hours later.

Lock down the branch that triggers all this

Think about what you've just built: anyone who can push to main can push straight to production. That's a lot of authority to leave sitting out in the open. I wrote a separate piece on restricting pushes and routing everything through a staging workflow — worth reading before you forget this part.

What You Actually Gained

Manual deployment isn't risky because the commands are hard. It's risky because it runs on your memory — every step, in the right order, every single time, including at 11pm on a Friday when you just want to close the laptop.

A pipeline takes that memory and writes it down where it can't forget.

Here's what's now in place:

A dedicated key that can deploy and do nothing else
A script on the server you can still run by hand when you want to
A workflow that fires on merge, refuses to run twice at once, and streams its logs somewhere you can actually read them
A reload instead of a restart, so nobody hits a refused connection mid-deploy

Setup runs about twenty minutes. You'll make that back before the week is out — and the fourth or fifth time you merge a fix and simply close the tab, it stops feeling like automation and starts feeling like the way it should have worked all along.

How to Deploy a Node.js Backend the Correct Way with Nginx + PM2 on Any VPS

Mushood — Sun, 02 Aug 2026 23:02:57 +0000

# Deploying a Node.js Backend in Production with PM2 & Nginx

Deploying a Node.js backend is easy until you do it on a real VPS server.

Locally, everything works perfectly:

npm start

The API launches, connects to the database, Postman returns the correct response, and everything looks good.

But once you move your project to a production server, you'll quickly face questions like:

What happens if the server reboots?
Will the application restart automatically?
Should users access port 5000 directly?
How do you configure HTTPS?
Where do logs go?
How should you restart the application after deployment?

These are common mistakes during a first production deployment.

Many beginners simply run:

node server.js

While this works for testing, it is not suitable for production.

Problems with this approach:

The process may stop when your SSH session ends.
If the app crashes, it won't restart automatically.
After a server reboot, your application stays offline.

Instead, a proper production setup uses:

PM2 — Process manager for Node.js
Nginx — Reverse proxy and web server

Production Architecture

Internet
   │
   ▼
Nginx (80 / 443)
   │
   ▼
Node.js App (localhost:5000)
   │
   ▼
PM2 Process Manager

Important: Users should never communicate directly with your Node.js application.

Instead of exposing:

http://your-server-ip:5000

Users should access:

https://your-domain.com

Nginx receives the request, handles HTTP/HTTPS, and forwards it to your backend.

Step 1 — Connect to Your Server

If using the root user:

ssh root@your-server-ip

Or if using Ubuntu:

ssh ubuntu@your-server-ip

Replace your-server-ip with your VPS IP address.

Step 2 — Update Your Server

Always update the package list first.

sudo apt update && sudo apt upgrade -y

Step 3 — Install Node.js

For Node.js v20:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs -y

Verify the installation:

node -v
npm -v

Step 4 — Clone Your Backend Project

Clone your repository:

git clone https://github.com/your-username/your-backend-repo.git

Move into the project:

cd your-backend-repo

Install dependencies:

npm install

If your application uses environment variables:

nano .env

Example:

PORT=5000
DATABASE_URL=your_database_url
JWT_SECRET=your_secret_key
NODE_ENV=production

Never commit your .env file.

.gitignore

.env

Step 5 — Test the Application

If you have a start script:

npm start

Otherwise:

node server.js

This verifies that:

Environment variables are correct
Database connection works
Dependencies are installed
Production configuration is valid

Stop the application afterward:

CTRL + C

Step 6 — Install PM2

Install PM2 globally:

sudo npm install pm2 -g

Start your application.

Using server.js:

pm2 start server.js --name backend-api

Or using the npm start script:

pm2 start npm --name backend-api -- start

Verify:

pm2 list

Step 7 — Enable Auto Startup

Generate the startup script:

pm2 startup

PM2 will display another command.

Run the generated command (it begins with sudo).

Finally save the process list:

pm2 save

Now your application starts automatically after server reboots.

Step 8 — Install Nginx

Install Nginx:

sudo apt install nginx -y

Start the service:

sudo systemctl start nginx

Enable startup:

sudo systemctl enable nginx

Check status:

sudo systemctl status nginx

Step 9 — Configure Nginx

Create a configuration file:

sudo nano /etc/nginx/sites-available/backend

Paste the following:

server {
    listen 80;

    server_name your-domain.com www.your-domain.com;

    location / {
        proxy_pass http://localhost:5000;
        proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Replace your-domain.com with your real domain.

Enable the configuration:

sudo ln -s /etc/nginx/sites-available/backend /etc/nginx/sites-enabled/

Test the configuration:

sudo nginx -t

Restart Nginx:

sudo systemctl restart nginx

Step 10 — Configure the Firewall

If you're using UFW:

Allow SSH:

sudo ufw allow OpenSSH

Allow HTTP & HTTPS:

sudo ufw allow 'Nginx Full'

Enable the firewall:

sudo ufw enable

Only these ports should be accessible:

SSH
HTTP (80)
HTTPS (443)

Do not expose port 5000.

Step 11 — Configure HTTPS with Certbot

Install Certbot:

sudo apt install certbot python3-certbot-nginx -y

Generate the SSL certificate:

sudo certbot --nginx -d your-domain.com -d www.your-domain.com

Certbot automatically:

Creates SSL certificates
Updates your Nginx configuration
Redirects HTTP → HTTPS

Useful PM2 Commands

Check running applications

pm2 list

Restart application

pm2 restart backend-api

Stop application

pm2 stop backend-api

Delete application

pm2 delete backend-api

View logs

pm2 logs

Open monitoring dashboard

pm2 monit

Save current process list

pm2 save

The most useful command during debugging:

pm2 logs

Typical Deployment Workflow

Once everything is configured, future deployments become simple.

cd your-backend-repo

git pull

npm install

pm2 restart backend-api

Why Use PM2 & Nginx?

Instead of exposing your Node.js server directly, using PM2 and Nginx provides several advantages:

Automatic application restarts
Auto-start after server reboot
SSL/TLS support
Reverse proxy functionality
Better logging
Easier scaling
Multiple applications or subdomains on one server
Improved security

Production Best Practices

Use environment variables

Good:

process.env.JWT_SECRET

Bad:

const jwtSecret = "your_secret_here";

Only expose necessary ports

Open only:

22 (SSH)
80 (HTTP)
443 (HTTPS)

Avoid exposing your application port (5000).

Always monitor logs

pm2 logs

Restart after deployment

pm2 restart backend-api

Summary

Production deployment is much more than simply starting your Node.js application.

A production-ready backend should:

✅ Automatically restart after crashes
✅ Start after server reboots
✅ Use HTTPS
✅ Hide internal application ports
✅ Generate accessible logs
✅ Be easy to update and maintain

Using PM2 together with Nginx provides a reliable, secure, and scalable setup for deploying Node.js applications on any Ubuntu-based VPS, whether it's AWS EC2, DigitalOcean, Hetzner, Azure, Linode, Contabo, or similar cloud providers.