Docker Best Practices for Node.js Applications

Docker containers provide consistent environments from development to production. Here's how to build efficient, secure Node.js containers.

Multi-Stage Builds#

# Build stage
FROM node:20-alpine AS builder

WORKDIR /app

# Copy package files first for better caching
COPY package*.json ./
RUN npm ci

# Copy source and build
COPY . .
RUN npm run build

# Prune dev dependencies
RUN npm prune --production

# Production stage
FROM node:20-alpine AS production

WORKDIR /app

# Create non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

# Copy only necessary files
COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nodejs:nodejs /app/package.json ./

USER nodejs

EXPOSE 3000

CMD ["node", "dist/index.js"]

Optimized Layer Caching#

FROM node:20-alpine

WORKDIR /app

# Dependencies change less frequently
COPY package.json package-lock.json ./
RUN npm ci --only=production

# Source changes more frequently
COPY . .

CMD ["node", "src/index.js"]

.dockerignore#

# Dependencies
node_modules
npm-debug.log

# Build artifacts
dist
build
coverage

# Development files
.git
.gitignore
.env*
.editorconfig
.eslintrc*
.prettierrc*
tsconfig.json

# Documentation
README.md
docs

# Tests
__tests__
*.test.js
*.spec.js
jest.config.js

# IDE
.vscode
.idea

# Docker files
Dockerfile*
docker-compose*
.dockerignore

Security Hardening#

FROM node:20-alpine

# Update packages and remove cache
RUN apk update && \
    apk upgrade && \
    rm -rf /var/cache/apk/*

WORKDIR /app

# Create non-root user early
RUN addgroup -g 1001 -S appgroup && \
    adduser -S appuser -u 1001 -G appgroup

# Copy package files
COPY --chown=appuser:appgroup package*.json ./

# Install dependencies as root, then switch
RUN npm ci --only=production && \
    npm cache clean --force

# Copy application
COPY --chown=appuser:appgroup . .

# Switch to non-root user
USER appuser

# Don't run as PID 1 - use tini or dumb-init
RUN apk add --no-cache tini
ENTRYPOINT ["/sbin/tini", "--"]

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

EXPOSE 3000
CMD ["node", "src/index.js"]

Environment Variables#

FROM node:20-alpine

WORKDIR /app

# Build-time arguments
ARG NODE_ENV=production
ARG APP_VERSION=unknown

# Runtime environment variables
ENV NODE_ENV=$NODE_ENV \
    APP_VERSION=$APP_VERSION \
    PORT=3000

COPY package*.json ./
RUN npm ci --only=production

COPY . .

EXPOSE $PORT
CMD ["node", "src/index.js"]

# docker-compose.yml
version: '3.8'

services:
  app:
    build:
      context: .
      args:
        NODE_ENV: production
        APP_VERSION: ${APP_VERSION:-1.0.0}
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
      - JWT_SECRET=${JWT_SECRET}
    env_file:
      - .env.production

Development Setup#

# docker-compose.yml
version: '3.8'

services:
  app:
    build:
      context: .
      target: development
    volumes:
      - .:/app
      - /app/node_modules
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    command: npm run dev

  db:
    image: postgres:15-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev
      POSTGRES_DB: app_dev
    ports:
      - "5432:5432"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  postgres_data:

# Multi-target Dockerfile
FROM node:20-alpine AS base
WORKDIR /app
COPY package*.json ./

FROM base AS development
RUN npm install
COPY . .
CMD ["npm", "run", "dev"]

FROM base AS builder
RUN npm ci
COPY . .
RUN npm run build
RUN npm prune --production

FROM node:20-alpine AS production
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]

Health Checks#

// src/health.ts
import express from 'express';

const router = express.Router();

router.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

router.get('/ready', async (req, res) => {
  try {
    // Check database connection
    await db.$queryRaw`SELECT 1`;

    // Check Redis
    await redis.ping();

    res.json({ status: 'ready' });
  } catch (error) {
    res.status(503).json({ status: 'not ready', error: error.message });
  }
});

export default router;

HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
    CMD node -e "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"

Logging#

// Don't write to files in containers
const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  // Write to stdout/stderr
  transport: process.env.NODE_ENV === 'development'
    ? { target: 'pino-pretty' }
    : undefined,
});

// Log to stdout, let Docker handle the rest

# docker-compose.yml
services:
  app:
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Resource Limits#

# docker-compose.yml
services:
  app:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

# Set Node.js memory limit
ENV NODE_OPTIONS="--max-old-space-size=450"

Graceful Shutdown#

// Handle SIGTERM for graceful shutdown
process.on('SIGTERM', async () => {
  console.log('SIGTERM received, shutting down gracefully');

  // Stop accepting new requests
  server.close(async () => {
    console.log('HTTP server closed');

    // Close database connections
    await db.$disconnect();

    // Close Redis
    await redis.quit();

    process.exit(0);
  });

  // Force exit after timeout
  setTimeout(() => {
    console.error('Forced shutdown after timeout');
    process.exit(1);
  }, 30000);
});

Best Practices#

Image Size:
✓ Use Alpine-based images
✓ Multi-stage builds
✓ Remove dev dependencies
✓ Clean npm cache

Security:
✓ Run as non-root user
✓ Update base images regularly
✓ Scan for vulnerabilities
✓ Don't store secrets in images

Performance:
✓ Optimize layer caching
✓ Use .dockerignore
✓ Set resource limits
✓ Configure health checks

Development:
✓ Use docker-compose
✓ Mount source for hot reload
✓ Match production environment
✓ Use consistent versions

Docker enables consistent deployments across environments. Use multi-stage builds for smaller images, run as non-root for security, and implement health checks for reliability. The extra setup time pays off in deployment confidence.