Docker cho Node.js: Cấu Hình Production-Ready Mà Ít Ai Nói Đến | Akousa

FROM node:20
WORKDIR /app
COPY . .
RUN npm install
EXPOSE 3000
CMD ["node", "server.js"]

dockerfile

# Single stage: ~600MB
FROM node:20
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "server.js"]
 
# Multi-stage: ~150MB
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
CMD ["node", "dist/server.js"]

Cách tiếp cận	Kích thước Image
`node:20` + `npm install`	1.1 GB
`node:20-slim` + `npm install`	420 MB
`node:20-alpine` + `npm ci`	280 MB
Multi-stage + alpine + chỉ production deps	150 MB
Multi-stage + alpine + deps đã cắt tỉa	95 MB

dockerfile

# ============================================
# Stage 1: Cài đặt dependencies
# ============================================
FROM node:20-alpine AS deps
 
# Bảo mật: tạo thư mục làm việc trước mọi thứ khác
WORKDIR /app
 
# Cài dependencies dựa trên lockfile
# Chỉ copy file package trước — điều này quan trọng cho layer caching
COPY package.json package-lock.json ./
 
# ci tốt hơn install: nhanh hơn, nghiêm ngặt hơn, và tái tạo được
# --omit=dev loại trừ devDependencies khỏi stage này
RUN npm ci --omit=dev
 
# ============================================
# Stage 2: Build ứng dụng
# ============================================
FROM node:20-alpine AS builder
 
WORKDIR /app
 
# Copy file package và cài TẤT CẢ dependencies (bao gồm dev)
COPY package.json package-lock.json ./
RUN npm ci
 
# BÂY GIỜ copy source code — thay đổi ở đây không vô hiệu hóa cache npm ci
COPY . .
 
# Build ứng dụng (TypeScript compile, Next.js build, v.v.)
RUN npm run build
 
# ============================================
# Stage 3: Production runner
# ============================================
FROM node:20-alpine AS runner
 
# Thêm label cho metadata image
LABEL maintainer="your-email@example.com"
LABEL org.opencontainers.image.source="https://github.com/yourorg/yourrepo"
 
# Bảo mật: cài dumb-init để xử lý tín hiệu PID 1 đúng cách
RUN apk add --no-cache dumb-init
 
# Bảo mật: đặt NODE_ENV trước mọi thứ khác
ENV NODE_ENV=production
 
# Bảo mật: dùng non-root user
# Image node đã bao gồm user 'node' (uid 1000)
USER node
 
# Tạo thư mục app thuộc sở hữu của user node
WORKDIR /app
 
# Copy production dependencies từ stage deps
COPY --from=deps --chown=node:node /app/node_modules ./node_modules
 
# Copy ứng dụng đã build từ stage builder
COPY --from=deps --chown=node:node /app/package.json ./
COPY --from=builder --chown=node:node /app/dist ./dist
 
# Expose port (chỉ là tài liệu — không publish)
EXPOSE 3000
 
# Health check: curl không có sẵn trong alpine, dùng node
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"
 
# Dùng dumb-init làm PID 1 để xử lý tín hiệu đúng cách
ENTRYPOINT ["dumb-init", "--"]
 
# Khởi động ứng dụng
CMD ["node", "dist/server.js"]

javascript

// server.js
const server = app.listen(3000);
 
process.on("SIGTERM", () => {
  console.log("Nhận SIGTERM, đang shutdown nhẹ nhàng");
  server.close(() => {
    console.log("HTTP server đã đóng");
    // Đóng kết nối database, flush log, v.v.
    process.exit(0);
  });
});

# .dockerignore
node_modules
npm-debug.log*
.git
.gitignore
.env
.env.*
!.env.example
Dockerfile
docker-compose*.yml
.dockerignore
README.md
LICENSE
.github
.vscode
.idea
coverage
.nyc_output
*.test.ts
*.test.js
*.spec.ts
*.spec.js
__tests__
test
tests
docs
.husky
.eslintrc*
.prettierrc*
tsconfig.json
jest.config.*
vitest.config.*

dockerfile

# syntax=docker/dockerfile:1
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
 
# Mount secret lúc build — nó không bao giờ được lưu trong image
RUN --mount=type=secret,id=npmrc,target=/app/.npmrc \
    npm ci
 
COPY . .
RUN npm run build

yaml

# docker-compose.yml (Swarm mode)
version: "3.8"
services:
  api:
    image: myapp:latest
    secrets:
      - db_password
      - api_key
 
secrets:
  db_password:
    external: true
  api_key:
    external: true

javascript

import { readFileSync } from "fs";
 
function getSecret(name) {
  try {
    return readFileSync(`/run/secrets/${name}`, "utf8").trim();
  } catch {
    // Dùng biến môi trường làm fallback cho phát triển local
    return process.env[name.toUpperCase()];
  }
}
 
const dbPassword = getSecret("db_password");

dockerfile

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

javascript

// healthcheck.js
const http = require("http");
 
const options = {
  hostname: "localhost",
  port: 3000,
  path: "/health",
  timeout: 5000,
};
 
const req = http.request(options, (res) => {
  process.exit(res.statusCode === 200 ? 0 : 1);
});
 
req.on("error", () => process.exit(1));
req.on("timeout", () => {
  req.destroy();
  process.exit(1);
});
 
req.end();

javascript

app.get("/health", async (req, res) => {
  const checks = {
    uptime: process.uptime(),
    timestamp: Date.now(),
    status: "ok",
  };
 
  try {
    // Kiểm tra kết nối database
    await db.query("SELECT 1");
    checks.database = "connected";
  } catch (err) {
    checks.database = "disconnected";
    checks.status = "degraded";
  }
 
  try {
    // Kiểm tra kết nối Redis
    await redis.ping();
    checks.redis = "connected";
  } catch (err) {
    checks.redis = "disconnected";
    checks.status = "degraded";
  }
 
  const statusCode = checks.status === "ok" ? 200 : 503;
  res.status(statusCode).json(checks);
});

yaml

# docker-compose.dev.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
      args:
        NODE_VERSION: "20"
    ports:
      - "3000:3000"
      - "9229:9229" # Node.js debugger
    volumes:
      # Mount source code cho hot reload
      - .:/app
      # Volume ẩn danh để giữ node_modules từ image
      # Ngăn node_modules của host ghi đè lên container
      - /app/node_modules
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgres://postgres:devpassword@db:5432/myapp_dev
      - REDIS_URL=redis://redis:6379
    env_file:
      - .env.local
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    command: npm run dev
 
  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: myapp_dev
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: devpassword
    volumes:
      # Named volume để dữ liệu bền vững qua các lần restart container
      - pgdata:/var/lib/postgresql/data
      # Script khởi tạo
      - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
 
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data
    command: redis-server --appendonly yes
 
  # Tùy chọn: UI quản trị database
  adminer:
    image: adminer:latest
    ports:
      - "8080:8080"
    depends_on:
      - db
 
volumes:
  pgdata:
  redisdata:

dockerfile

# Dockerfile.dev
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine
 
WORKDIR /app
 
# Cài tất cả dependencies (bao gồm devDependencies)
COPY package*.json ./
RUN npm ci
 
# Source code được mount qua volume, không copy
# Nhưng vẫn cần cho lần build ban đầu
COPY . .
 
EXPOSE 3000 9229
 
CMD ["npm", "run", "dev"]

yaml

# docker-compose.prod.yml
services:
  app:
    image: ghcr.io/yourorg/myapp:${TAG:-latest}
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    env_file:
      - .env.production
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          cpus: "0.25"
          memory: 128M
      replicas: 2
    healthcheck:
      test:
        [
          "CMD",
          "node",
          "-e",
          "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode === 200 ? 0 : 1))",
        ]
      interval: 30s
      timeout: 10s
      start_period: 40s
      retries: 3
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - internal
      - web
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
 
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 1G
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - internal
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
 
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: >
      redis-server
      --appendonly yes
      --maxmemory 256mb
      --maxmemory-policy allkeys-lru
    volumes:
      - redisdata:/data
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 512M
    networks:
      - internal
    logging:
      driver: "json-file"
      options:
        max-size: "5m"
        max-file: "3"
 
volumes:
  pgdata:
    driver: local
  redisdata:
    driver: local
 
networks:
  internal:
    driver: bridge
  web:
    external: true

dockerfile

# ============================================
# Stage 1: Cài đặt dependencies
# ============================================
FROM node:20-alpine AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
 
COPY package.json package-lock.json ./
RUN npm ci
 
# ============================================
# Stage 2: Build ứng dụng
# ============================================
FROM node:20-alpine AS builder
WORKDIR /app
 
COPY --from=deps /app/node_modules ./node_modules
COPY . .
 
# Tắt telemetry Next.js trong quá trình build
ENV NEXT_TELEMETRY_DISABLED=1
 
RUN npm run build
 
# ============================================
# Stage 3: Production runner
# ============================================
FROM node:20-alpine AS runner
WORKDIR /app
 
RUN apk add --no-cache dumb-init
 
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
 
# Non-root user
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
 
# Copy asset tĩnh
COPY --from=builder /app/public ./public
 
# Thiết lập thư mục standalone output
# Tự động tận dụng output trace để giảm kích thước image
# https://nextjs.org/docs/advanced-features/output-file-tracing
RUN mkdir .next
RUN chown nextjs:nodejs .next
 
# Copy standalone server và file tĩnh
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 
USER nextjs
 
EXPOSE 3000
 
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"
 
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/api/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"
 
ENTRYPOINT ["dumb-init", "--"]
CMD ["node", "server.js"]

myapp:latest (alpine 3.19.1)
=============================
Total: 0 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 0)

Node.js (node_modules/package-lock.json)
=========================================
Total: 2 (UNKNOWN: 0, LOW: 0, MEDIUM: 1, HIGH: 1, CRITICAL: 0)

┌──────────────┬────────────────┬──────────┬────────┬───────────────┐
│   Library    │ Vulnerability  │ Severity │ Status │ Fixed Version │
├──────────────┼────────────────┼──────────┼────────┼───────────────┤
│ semver       │ CVE-2022-25883 │ HIGH     │ fixed  │ 7.5.4         │
│ word-wrap    │ CVE-2023-26115 │ MEDIUM   │ fixed  │ 1.2.4         │
└──────────────┴────────────────┴──────────┴────────┴───────────────┘

yaml

# .github/workflows/docker.yml
- name: Build image
  run: docker build -t myapp:${{ github.sha }} .
 
- name: Scan image
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: myapp:${{ github.sha }}
    exit-code: 1
    severity: CRITICAL,HIGH
    ignore-unfixed: true

yaml

# .github/workflows/docker.yml
name: Build and Push Docker Image
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
 
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      security-events: write
 
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
 
      - name: Log in to Container Registry
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
 
      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=sha
            type=ref,event=branch
            type=semver,pattern={{version}}
 
      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
 
      - name: Scan image with Trivy
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:sha-${{ github.sha }}
          exit-code: 1
          severity: CRITICAL,HIGH
          ignore-unfixed: true
 
      - name: Upload Trivy results
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: trivy-results.sarif

dockerfile

# Cấu hình build-time
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine
 
# Cấu hình runtime
ENV PORT=3000
 
# SAI: Điều này làm secret hiển thị trong image
ARG API_KEY
ENV API_KEY=${API_KEY}
 
# ĐÚNG: Truyền secret lúc runtime
# docker run -e API_KEY=secret myapp

yaml

# docker-compose.monitoring.yml
services:
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    ports:
      - "9090:9090"
    networks:
      - internal
 
  grafana:
    image: grafana/grafana:latest
    volumes:
      - grafana_data:/var/lib/grafana
    ports:
      - "3001:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
    networks:
      - internal
 
volumes:
  prometheus_data:
  grafana_data:

javascript

import { collectDefaultMetrics, Registry, Histogram } from "prom-client";
 
const register = new Registry();
collectDefaultMetrics({ register });
 
const httpRequestDuration = new Histogram({
  name: "http_request_duration_seconds",
  help: "Thời lượng HTTP request tính bằng giây",
  labelNames: ["method", "route", "status_code"],
  buckets: [0.01, 0.05, 0.1, 0.5, 1, 5],
  registers: [register],
});
 
// Middleware
app.use((req, res, next) => {
  const end = httpRequestDuration.startTimer();
  res.on("finish", () => {
    end({ method: req.method, route: req.route?.path || req.path, status_code: res.statusCode });
  });
  next();
});
 
// Endpoint metric
app.get("/metrics", async (req, res) => {
  res.set("Content-Type", register.contentType);
  res.end(await register.metrics());
});

Cách tiếp cận	Kích thước Image
`node:20` + đầy đủ `node_modules` + `.next`	1.4 GB
`node:20-alpine` + đầy đủ `node_modules` + `.next`	600 MB
`node:20-alpine` + standalone output	120 MB

Tại Sao Dockerfile Hiện Tại Của Bạn Có Thể Sai

Chạy Với Quyền Root

Cài devDependencies Trên Production

COPY Tất Cả

Không Có Health Check

Không Có Chiến Lược Layer Caching

Multi-Stage Builds: Cải Tiến Lớn Nhất

So Sánh Kích Thước Thực Tế

Tại Sao Alpine?

Dockerfile Production Hoàn Chỉnh

Tại Sao Ba Stage Thay Vì Hai?

Tại Sao dumb-init?

File .dockerignore

Layer Caching: Đừng Đợi 3 Phút Mỗi Lần Build

Thứ Tự Sai

Thứ Tự Đúng

Cache Mount Cho npm

Dùng ARG Để Phá Cache

Quản Lý Secrets: Đừng Đặt Secrets Trong Dockerfile

Ba Cấp Độ Secrets

File .env và Docker

Health Checks: Cho Docker Biết Ứng Dụng Thực Sự Hoạt Động

Lệnh HEALTHCHECK

Tại Sao Không Dùng curl?

Endpoint Health

Tại Sao Health Check Quan Trọng Với Orchestrator

docker-compose Cho Phát Triển

Pattern Phát Triển Chính

Dockerfile Phát Triển

Production Docker Compose

Khác Biệt Gì So Với Phát Triển

Next.js Cụ Thể: Standalone Output

Dockerfile Production Cho Next.js

So Sánh Kích Thước Cho Next.js

Xử Lý File Tĩnh

Sharp Cho Tối Ưu Hình Ảnh

Quét Image và Bảo Mật

Trivy: Quét Image

Filesystem Chỉ Đọc

Loại Bỏ Tất Cả Capabilities

Pin Digest Base Image

Tích Hợp CI/CD: Tổng Hợp Tất Cả

BuildKit Cache Trong CI

Bẫy Thường Gặp và Cách Tránh

Xung Đột node_modules Trong Image vs Host

Xử Lý SIGTERM Trong Dự Án TypeScript

Giới Hạn Bộ Nhớ và Node.js

Vấn Đề Timezone

Build Argument vs Biến Môi Trường

Giám Sát Trong Production

Danh Sách Kiểm Tra

Bài viết liên quan

Monorepos in 2026: Nx, Turborepo, and the Lessons Nobody Shares

YAML Validator Guide: Catch Config Errors Before Deploy