Toidicode.com

Toidicode.com

BASIC TO ADVANCE

Bài 36: Deploy NestJS với Docker

Tiếp tục với series, bài cuối này mình sẽ giới thiệu với mọi người về deploy NestJS với Docker: đóng gói TaskFlow API thành image, chạy cả hệ thống bằng docker compose và đặt sau Nginx có HTTPS.

1. Chuẩn bị code cho production.

Trên production, npm run build dịch code sang dist/ rồi chạy node dist/main. Cấu hình đọc từ biến môi trường (Bài 14), NODE_ENV=production tắt /docs và GraphiQL. Code cần sửa hai chỗ.

Thứ nhất, image không có src/ để ghi schema.gql (Bài 24):

- src/app.module.ts (đoạn trích)

autoSchemaFile:
    // Production: schema chỉ sinh trong bộ nhớ
    process.env.NODE_ENV === 'production'
        ? true
        : join(process.cwd(), 'src/schema.gql'),

Thứ hai, sau Nginx mọi request đến từ IP của proxy, throttler (Bài 20) sẽ coi mọi người là một client. Mình thêm biến TRUST_PROXY: số proxy đứng trước (VD 1 sau một load balancer), true/false, hoặc danh sách tên/IP/subnet cách nhau dấu phẩy (loopback, uniquelocal, 10.0.0.0/8). envSchema kiểm tra giá trị bằng refine(). Express hiểu chuỗi '1' là IP 0.0.0.1 (không tin ai) còn 'true' làm app lỗi, nên phải đổi kiểu trước:

- src/config/app.config.ts (đoạn trích, registerAs() gọi parseTrustProxy(process.env.TRUST_PROXY))

export function parseTrustProxy(
    value = '',
): number | boolean | string[] | undefined {
    if (value === '') {
        return undefined;
    }
    if (/^\d+$/.test(value)) {
        return Number(value);
    }
    if (value === 'true' || value === 'false') {
        return value === 'true';
    }
    return value.split(',').map((item) => item.trim());
}

Rồi bật trong main.ts:

- src/main.ts (đoạn trích)

import type { NestExpressApplication } from '@nestjs/platform-express';
// ...
const app = await NestFactory.create<NestExpressApplication>(AppModule, {
// ...
if (config.trustProxy) {
    // req.ip lấy IP thật của client từ X-Forwarded-For do Nginx gửi tới
    app.set('trust proxy', config.trustProxy);
}

2. Dockerfile nhiều stage.

Với multi-stage build, stage đầu cài đủ dependency để build, stage cuối chỉ copy thứ cần để chạy:

- Dockerfile

# Stage 1: cài đủ dependency để build
FROM node:24-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npx prisma generate && npm run build

# Stage 2: chỉ dependency cần khi chạy
FROM node:24-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

# Stage 3: image chạy production
FROM node:24-alpine
ENV NODE_ENV=production
WORKDIR /app
COPY package.json ./
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
# Thư mục upload thuộc user node (volume tạo lần đầu giữ quyền này)
RUN mkdir storage && chown node:node storage
USER node
EXPOSE 3000
CMD ["node", "dist/main"]

Trong đó:

  • npx prisma generate: Prisma Client không được commit (Bài 15) nên phải sinh lúc build.
  • Stage deps cài với --omit=dev. Image cuối khoảng 620 MB, stage build khoảng 940 MB.
  • USER node: không chạy bằng root.
  • CMD ["node", "dist/main"]: node là process số 1, tự nhận tín hiệu tắt từ Docker (phần 4).

.dockerignore loại file thừa khỏi image, nhất là .env*: secret chỉ truyền vào lúc chạy.

- .dockerignore

node_modules
dist
src/generated
storage
coverage
.git
.env*
*.md

3. Chạy cả hệ thống với docker compose.

Compose chạy API, service thông báo (Bài 32), PostgreSQL, MongoDB, Redis, NATS (Bài 33) trên network riêng, chỉ mở cổng API trên 127.0.0.1:

- compose.yaml

name: taskflow

# API và service thông báo dùng chung một image
x-app: &app
  image: taskflow-api
  restart: unless-stopped
  depends_on: &app-deps
    migrate: { condition: service_completed_successfully }
    redis: { condition: service_healthy }
    nats: { condition: service_healthy }

x-db-url: &db-url postgresql://taskflow:${POSTGRES_PASSWORD:?}@postgres:5432/taskflow?schema=public

services:
  migrate:
    build: { context: ., target: build }
    image: taskflow-api-build
    command: npx prisma migrate deploy
    environment: { DATABASE_URL: *db-url }
    depends_on: { postgres: { condition: service_healthy } }

  api:
    <<: *app
    build: .
    environment:
      DATABASE_URL: *db-url
      MONGODB_URI: mongodb://taskflow:${MONGO_PASSWORD:?}@mongo:27017/taskflow?authSource=admin
      REDIS_URL: redis://redis:6379
      NATS_URL: nats://nats:4222
      JWT_SECRET: ${JWT_SECRET:?}
      CORS_ORIGINS: ${CORS_ORIGINS:?}
      TRUST_PROXY: uniquelocal
    ports: ["127.0.0.1:3000:3000"] # chỉ Nginx trên server gọi được
    volumes: [storage:/app/storage]
    healthcheck:
      test: wget -qO /dev/null http://127.0.0.1:3000/health/ready || exit 1
      interval: 10s
      start_period: 30s
    depends_on:
      <<: *app-deps
      mongo: { condition: service_healthy }

  notifications:
    <<: *app
    pull_policy: never # dùng image mà service api vừa build
    command: node dist/notification-service/main
    environment:
      DATABASE_URL: *db-url
      REDIS_URL: redis://redis:6379
      NATS_URL: nats://nats:4222
      SMTP_URL: ${SMTP_URL:?}
      MAIL_FROM: ${MAIL_FROM:?}
    stop_grace_period: 30s

  postgres:
    image: postgres:18-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: taskflow
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?}
      POSTGRES_DB: taskflow
    volumes: [pgdata:/var/lib/postgresql]
    healthcheck: { test: pg_isready -U taskflow -d taskflow, interval: 5s }

  mongo:
    image: mongo:9
    restart: unless-stopped
    environment:
      MONGO_INITDB_ROOT_USERNAME: taskflow
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD:?}
    volumes: [mongodata:/data/db]
    healthcheck:
      test: mongosh --quiet --eval "db.adminCommand('ping')"
      interval: 5s

  redis:
    image: redis:8-alpine
    restart: unless-stopped
    # Lưu xuống đĩa, không xoá key khi đầy RAM: không mất job BullMQ
    command: redis-server --appendonly yes --maxmemory-policy noeviction
    volumes: [redisdata:/data]
    healthcheck: { test: redis-cli ping, interval: 5s }

  nats:
    image: nats:2-alpine
    restart: unless-stopped
    healthcheck:
      test: wget -qO /dev/null http://127.0.0.1:8222/healthz || exit 1
      interval: 5s

volumes: { pgdata: {}, mongodata: {}, redisdata: {}, storage: {} }

Trong đó:

  • migrate dùng image stage build (có Prisma CLI) chạy prisma migrate deploy: chỉ áp dụng migration đã commit, không tạo mới hay xoá dữ liệu như migrate dev.
  • healthcheck gọi /health/ready bằng wget (image Alpine không có curl), xem Bài 35. Ổ đĩa quá 90% chỉ làm storage báo degraded (vẫn 200) nên container không thành unhealthy, --wait không báo lỗi.
  • Volume giữ dữ liệu database và file upload (Bài 22).
  • ${JWT_SECRET:?}: Compose lấy giá trị từ file .env cạnh compose.yaml, thiếu thì báo lỗi.

Trên server các bạn tạo file .env đó (không commit), mật khẩu tạo bằng openssl cho khỏi có ký tự đặc biệt trong URL:

# .env cạnh compose.yaml trên server (chmod 600 .env)
JWT_SECRET=<openssl rand -hex 32>
POSTGRES_PASSWORD=<openssl rand -hex 24>
MONGO_PASSWORD=<openssl rand -hex 24>
SMTP_URL=smtp://user:[email protected]:587
MAIL_FROM="TaskFlow <[email protected]>"
CORS_ORIGINS=https://taskflow.example.com

Build và chạy, --wait chờ tới khi các healthcheck đạt:

docker compose up -d --build --wait
curl -s http://127.0.0.1:3000/api/v1
# {"data":"Xin chào TaskFlow API!"}

Deploy bản mới chỉ cần git pull rồi chạy lại lệnh đầu: build lại image, chạy migration mới, tạo lại container.

4. Graceful shutdown.

Khi dừng container, Docker gửi SIGTERM, chờ 10 giây rồi SIGKILL. Nhờ app.enableShutdownHooks() (Bài 15) trong cả hai main.ts, NestJS chạy các hook lúc tắt, đóng server và kết nối rồi thoát với mã 0.

@nestjs/bullmq đóng worker trong onModuleDestroy() và chờ job đang chạy xong (Bài 29). Gửi mail có thể quá 10 giây nên compose đặt stop_grace_period: 30s.

5. Reverse proxy Nginx và HTTPS.

Nginx trên server nhận request ở cổng 80/443 rồi chuyển vào 127.0.0.1:3000:

- deploy/nginx.conf

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name taskflow.example.com;
    client_max_body_size 26m; # upload tối đa 5 file x 5 MB

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        # Ghi đè, không nối thêm: client không tự khai IP giả được
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        # WebSocket (Socket.IO, GraphQL subscription)
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

Request từ Nginx vào container qua địa chỉ private của Docker nên compose đặt TRUST_PROXY: uniquelocal. Thử đăng nhập sai 6 lần qua Nginx, mỗi lần một X-Forwarded-For khác: lần thứ 6 vẫn bị 429.

trust proxy chỉ áp dụng cho HTTP. Socket.IO (Bài 31) lấy IP từ socket.handshake.address, sau Nginx mọi socket chung IP đó, giới hạn project:join thành của cả hệ thống. Nên message WebSocket được đếm theo user:

- src/common/guards/app-throttler.guard.ts (thêm vào class, import type AuthRequest)

    // WebSocket có req.user từ lúc handshake: đếm theo user, vì sau Nginx mọi socket
    // có cùng handshake.address. HTTP chạy guard này trước JwtAuthGuard: vẫn theo IP
    protected async getTracker(req: AuthRequest): Promise<string> {
        return req.user ? `user:${req.user.id}` : super.getTracker(req);
    }

Cài Nginx, bật site và lấy chứng chỉ Let's Encrypt bằng certbot làm như bài deploy Laravel 13 lên VPS:

sudo cp deploy/nginx.conf /etc/nginx/sites-available/taskflow
sudo ln -s /etc/nginx/sites-available/taskflow /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d taskflow.example.com

Certbot chuyển sang HTTPS và tự gia hạn chứng chỉ. CORS_ORIGINS phải là domain https:// này để Socket.IO (Bài 31) kết nối được.

6. Lời kết.

Như vậy mình đã giới thiệu xong deploy NestJS với Docker: Dockerfile nhiều stage, docker compose, healthcheck, graceful shutdown, Nginx với trust proxy và HTTPS. Các bạn xem thêm tại tài liệu chính thức.

Đây cũng là bài cuối của series NestJS: từ một project trống, TaskFlow API giờ có REST, GraphQL, queue, WebSocket, microservice, test và chạy được trên server. Tiếp theo các bạn có thể tìm hiểu CI/CD hoặc Kubernetes nhé!

Đăng ký nhận tin.

Chúng tôi chỉ gửi tối đa 2 lần trên 1 tháng. Tuyên bố không spam mail!

Vũ Thanh Tài

About author
The best way to learn is to share
Xem tất cả bài đăng

0 Comments

Bài viết chưa có ai bình luận, hãy là người đầu tiên đi bạn!

Bình luận

Captcha