Production Deployment

Learning objectives#

• Write a small, secure multi-stage Dockerfile for Node.js
• Run the API and MySQL together with Docker Compose
• Wire health checks, migrations and configuration
• Plan zero-downtime releases

Explanation#

Multi-stage build: one stage installs production dependencies with npm ci --omit=dev; the final stage copies only node_modules and src onto a slim base image. Smaller images build, pull and scan faster.

Security: run as the built-in non-root node user, keep secrets out of the image (pass them as environment variables or mounted secrets), add a .dockerignore (node_modules, .env, .git).

Health: the HEALTHCHECK (or the orchestrator’s probe) calls /health; /ready checks MySQL. The API handles SIGTERM gracefully so containers stop cleanly.

Docker Compose runs the API and MySQL locally or on a single VPS, with depends_on: condition: service_healthy so the API starts after the database is ready.

Releases: run database migrations as a separate step before the new version starts; make migrations backwards-compatible so old and new containers can run side by side during a rolling update.

Syntax#

1docker build -t learnhub-api:1.4.0 .
2docker run -p 3000:3000 --env-file .env.production learnhub-api:1.4.0
3docker compose up -d --build
4docker compose logs -f api

Code example: A production Dockerfile for the API#

1# ---- deps: install production dependencies only ----
2FROM node:22-alpine AS deps
3WORKDIR /app
4COPY package.json package-lock.json ./
5RUN npm ci --omit=dev
6

7# ---- runtime: small image, non-root, no build tools ----
8FROM node:22-alpine
9ENV NODE_ENV=production PORT=3000
10WORKDIR /app
11COPY --from=deps /app/node_modules ./node_modules
12COPY package.json ./
13COPY src ./src
14USER node
15EXPOSE 3000
16HEALTHCHECK --interval=30s --timeout=3s --start-period=10s \
17  CMD wget -qO- http://localhost:3000/health || exit 1
18CMD ["node", "src/server.js"]

docker build produces an image of roughly 150–200 MB that runs as the unprivileged node user. docker ps shows the container as “healthy” once /health answers, and docker stop sends SIGTERM so in-flight requests finish before the container exits.

This example is illustrative. Copy or download it and run it in your own environment; the expected output is shown above.

Step-by-step explanation#

1. The deps stage installs only production dependencies from the lock file.
2. The runtime stage copies node_modules and the source — no npm cache, tests or .env files.
3. NODE_ENV=production enables production behaviour in Express and libraries.
4. USER node drops root privileges inside the container.
5. HEALTHCHECK lets Docker (and Compose) know when the API is really ready; CMD runs Node directly so it receives SIGTERM.

Real-world use case#

Common mistakes#

Best practices#

• Multi-stage build with npm ci --omit=dev
• Non-root user and .dockerignore
• Health checks + graceful shutdown
• Migrations as a separate, backwards-compatible step

Remember this#

Practice exercise#

1services:
2  db:
3    image: mysql:8.4
4    environment:
5      MYSQL_DATABASE: learnhub
6      MYSQL_USER: learnhub
7      MYSQL_PASSWORD: ${DB_PASSWORD}
8      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
9    volumes:
10      - db-data:/var/lib/mysql
11    healthcheck:
12      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
13      interval: 10s
14      retries: 5
15

16  api:
17    build: .
18    ports:
19      - "3000:3000"
20    environment:
21      DATABASE_URL: mysql://learnhub:${DB_PASSWORD}@db:3306/learnhub
22      JWT_SECRET: ${JWT_SECRET}
23    depends_on:
24      db:
25        condition: service_healthy
26    restart: unless-stopped
27

28volumes:
29  db-data:

Mini quiz#

Want more? Practise all Node.js REST API MCQs · Node.js REST API interview questions

Related topics#

My notes#

Saved in this browser.