Week 14: Containerization & Deployment

1. A Multi-Stage Dockerfile for TypeScript

A naive Dockerfile that installs every dependency, copies all your source, and runs tsc inside the final image ships your entire toolchain — TypeScript itself, dev dependencies, source files — into production, bloating the image and widening its attack surface for no benefit. A multi-stage build uses one throwaway stage to compile, then copies only the compiled output into a clean, minimal final stage.

# ---- Stage 1: build ----
FROM node:20-alpine AS builder
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY tsconfig.json ./
COPY prisma ./prisma
COPY src ./src
RUN npx prisma generate
RUN npm run build

# ---- Stage 2: runtime ----
FROM node:20-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production

COPY package.json package-lock.json ./
RUN npm ci --omit=dev

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules/.prisma ./node_modules/.prisma
COPY prisma ./prisma

# Run as a non-root user -- never run a production container as root.
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

EXPOSE 3000
CMD ["node", "dist/main.js"]

The builder stage has the full dependency tree, including typescript and @types/node, and produces dist/. The runtime stage starts completely fresh from node:20-alpine — a minimal Linux image — installs only production dependencies with npm ci --omit=dev, and copies in nothing but the compiled JavaScript. Docker discards everything from the builder stage that wasn't explicitly copied over, so TypeScript itself never exists in the final image.

node_modules
dist
.env
.git
*.log

2. CI/CD with GitHub Actions

A pipeline that builds and deploys an image without running tests first will happily ship a broken build to production. The workflow below runs the Vitest/Supertest suite from Week 8 as a required, separate job, and only builds the Docker image if it passes:

name: CI/CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: test_db
        ports: ["5432:5432"]
        options: >-
          --health-cmd="pg_isready -U postgres"
          --health-interval=5s
          --health-timeout=5s
          --health-retries=5
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"

      - run: npm ci
      - run: npx prisma migrate deploy
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test_db
      - run: npm test
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test_db

  build-and-push:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}

needs: test is what enforces the ordering — build-and-push won't start until test finishes successfully, and if any test fails, the build job never runs at all. The services block spins up a real Postgres container for the test job to run integration tests against, matching the test-database strategy from Week 8 rather than mocking the database away entirely. Restricting the build-and-push job to main keeps pull-request runs fast (tests only) while still publishing an image on every merge.

3. Running Node in Production: PM2 & the Cluster Module

Week 1 established that Node runs your JavaScript on a single thread. A modern server has many CPU cores, and a single Node process only ever uses one of them for your application code — leaving the rest idle unless you explicitly do something about it. Node's built-in cluster module forks multiple copies of your process, one per CPU core, with the OS load-balancing incoming connections across them:

import cluster from "node:cluster";
import os from "node:os";

if (cluster.isPrimary) {
  const numCPUs = os.availableParallelism();
  console.log(`Primary ${process.pid} forking ${numCPUs} workers`);

  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on("exit", (worker, code, signal) => {
    console.warn(`Worker ${worker.process.pid} died (${signal ?? code}), forking a replacement`);
    cluster.fork();
  });
} else {
  // Each worker just runs the normal app entry point --
  // it doesn't know or care that it's one of several.
  await import("./main.js");
}

Each worker is a full, independent Node process with its own memory and its own event loop — they share nothing in-process, which is why Week 11's Redis cache and Week 4's database are external, shared services rather than in-memory objects: any state that needs to be consistent across workers has to live outside any single process.

PM2 is a process manager that wraps this same clustering behavior (plus automatic restarts, log management, and zero-downtime reloads) behind a simple CLI, and is a common alternative to hand-rolling the cluster module yourself:

module.exports = {
  apps: [
    {
      name: "api",
      script: "dist/main.js",
      instances: "max", // one instance per available CPU core
      exec_mode: "cluster",
      env: { NODE_ENV: "production" },
    },
  ],
};

pm2 start ecosystem.config.cjs
pm2 logs api
pm2 reload api   # zero-downtime reload, one worker at a time

In a container-orchestrated deployment (Kubernetes, ECS), it's common to skip both and instead run one Node process per container, letting the orchestrator run multiple container replicas and handle scaling and restarts — either approach is valid, and which one you pick depends on whether your platform or your application manages multi-core utilization.

4. Graceful Shutdown on SIGTERM

When Docker or Kubernetes stops a container — during a deploy, a scale-down, or a node being drained — it sends SIGTERM first, then waits a grace period (30 seconds by default in Kubernetes) before sending an unforgiving SIGKILL. If your app doesn't handle SIGTERM, requests in-flight when the signal arrives get dropped mid-response, and the process is killed without a chance to close database or Redis connections cleanly.

import { createApp } from "./app.js";
import { prisma } from "./lib/prisma.js";
import { redis } from "./lib/redis.js";
import { logger } from "./lib/logger.js";

const app = createApp();
const server = app.listen(process.env.PORT ?? 3000, () => {
  logger.info({}, `Server listening on port ${process.env.PORT ?? 3000}`);
});

async function shutdown(signal: string): Promise<void> {
  logger.info({ signal }, "Shutdown signal received, closing gracefully");

  // Stop accepting new connections; let in-flight requests finish.
  server.close(async (err) => {
    if (err) {
      logger.error({ err }, "Error while closing HTTP server");
    }

    await Promise.allSettled([prisma.$disconnect(), redis.quit()]);

    logger.info({}, "Shutdown complete");
    process.exit(err ? 1 : 0);
  });

  // Safety net: if something hangs (a stuck connection, a slow client),
  // force-exit rather than relying on the orchestrator's SIGKILL.
  setTimeout(() => {
    logger.error({}, "Forced shutdown after timeout");
    process.exit(1);
  }, 10_000).unref();
}

process.on("SIGTERM", () => void shutdown("SIGTERM"));
process.on("SIGINT", () => void shutdown("SIGINT")); // Ctrl+C during local dev

server.close() stops the HTTP server from accepting brand-new connections but lets requests already in progress complete normally — this is the difference between a clean deploy where no client sees a dropped connection, and one where every deploy causes a small burst of failed requests. The 10-second safety-net timeout, with .unref() so it doesn't itself keep the process alive if shutdown finishes first, guards against a shutdown that never completes (a hung database connection, for instance) instead of relying entirely on the orchestrator's own kill timeout.

5. Hands-on Exercise

6. Knowledge Check

Four quick questions. Expand each to check your answer.