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
depscài với--omit=dev. Image cuối khoảng 620 MB, stagebuildkhoảng 940 MB. USER node: không chạy bằng root.CMD ["node", "dist/main"]:nodelà 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 đó:
migratedùng image stagebuild(có Prisma CLI) chạyprisma migrate deploy: chỉ áp dụng migration đã commit, không tạo mới hay xoá dữ liệu nhưmigrate dev.healthcheckgọi/health/readybằngwget(image Alpine không cócurl), xem Bài 35. Ổ đĩa quá 90% chỉ làmstoragebáodegraded(vẫn200) nên container không thànhunhealthy,--waitkhô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.envcạnhcompose.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!





0 Comments