Triển khai
Hướng dẫn triển khai lên một VPS bằng Docker Compose. Nội dung được chuyển từ DEPLOYMENT.md (tiếng Anh, nay chỉ còn trỏ tới đây), đã đối chiếu với docker-compose.prod.yml và Dockerfile. Stack compose production (thứ tự khởi động, tự phục hồi, seed, scripts/deploy.sh, scripts/backup-mongo.sh) đã chạy thử trên Docker cục bộ. Chưa xác minh trên VPS thật: chứng chỉ TLS, workflow đẩy image và mức RAM dưới tải.
Hai cách chạy
| Phát triển | Production (VPS) | |
|---|---|---|
| File compose | docker-compose.yml | docker-compose.prod.yml |
| File môi trường | .env | .env.production |
| Backend | npm run dev trên máy | Image production kéo từ Docker Hub (build ở CI), không phải root, có healthcheck |
| MongoDB và Redis | Gắn vào 127.0.0.1 | Mạng Docker riêng, không publish, Redis có mật khẩu |
| HTTPS | Không | Caddy trong compose, tự cấp chứng chỉ Let's Encrypt |
| Swagger | http://localhost:8081/api | Tắt (đặt SWAGGER_ENABLED=true để mở) |
Chạy local: quick-start.
Kiến trúc triển khai tham chiếu
Cấu hình mẫu trong DEPLOYMENT.md: Ubuntu 22.04 trở lên, 2 vCPU, 4 GB RAM, Docker Engine kèm Compose plugin. Sơ đồ: container-diagram.
Các bước
Hướng dẫn từng bước cho VPS nhỏ (1.5GB RAM) kèm FE trên Vercel: vps-production-guide. Các mục dưới đây là tham chiếu.
1. Chuẩn bị máy chủ
- Tường lửa chỉ mở SSH, 80, 443 (ví dụ
ufw). - Cài Docker Engine kèm Compose plugin. Caddy chạy trong compose nên không cần nginx hay certbot.
- Lưu ý: cổng do Docker publish bỏ qua
ufw. Vì vậy compose production chỉ publish 80 và 443 (Caddy); backend, MongoDB, Redis không publish cổng nào. Không đổi điều này.
2. Cấu hình môi trường
git clone <repo-url> /opt/job-portal-be && cd /opt/job-portal-be
cp .env.example .env.production
chmod 600 .env.production
Đặt tối thiểu (giá trị thật tự sinh bằng openssl rand -hex ..., không lưu vào git):
NODE_ENV=production
PORT=8081
FE_URL=https://example.com
CORS_ORIGINS=https://example.com,https://www.example.com
TRUST_PROXY=1
MONGO_INITDB_ROOT_PASSWORD=<chuỗi hex ngẫu nhiên>
REDIS_PASSWORD=<chuỗi hex ngẫu nhiên>
JWT_ACCESS_TOKEN_SECRET=<chuỗi hex ngẫu nhiên>
JWT_REFRESH_TOKEN_SECRET=<chuỗi hex ngẫu nhiên>
OTP_SECRET=<chuỗi hex ngẫu nhiên>
kèm các biến SMTP_*, GOOGLE_*, GEMINI_*, GROQ_*, AI_GROQ_*, EMAIL_ADMIN, INIT_PASSWORD. Danh sách đầy đủ: environment-variables.
- Dùng mật khẩu hex vì
MONGO_URLđược dựng từ chúng; ký tự@ / :làm hỏng URI. MONGO_URLvàREDIS_HOSTtrong file bị compose ghi đè.- Cookie refresh là
SecurevàSameSite=Strictở production, nên frontend và API phải phục vụ qua HTTPS và cùng site (ví dụexample.comvàapi.example.com).
3. Khởi động
./scripts/deploy.sh # pull image theo IMAGE_TAG rồi up -d --wait
curl -s https://<API_DOMAIN>/api/v1/health/ready
Cần thêm DOCKERHUB_USER, IMAGE_NAME, IMAGE_TAG, API_DOMAIN vào .env.production (xem .env.example).
4. Dữ liệu ban đầu
npm run seed tạo kỹ năng, nguồn tin và tài khoản quản trị EMAIL_ADMIN. Công ty, tin, CV và các tài khoản mẫu @seed.local chỉ được tạo khi NODE_ENV là development hoặc test; mọi giá trị khác, kể cả không đặt, đều chỉ tạo admin (seed.service.ts). Ở chế độ này INIT_PASSWORD phải dài ít nhất 12 ký tự. Đổi mật khẩu admin sau lần đăng nhập đầu.
5. Reverse proxy và TLS
Caddy chạy trong compose, cấu hình ở Caddyfile, tự cấp và gia hạn chứng chỉ Let's Encrypt cho API_DOMAIN:
| Thiết lập | Lý do |
|---|---|
request_body max_size 10MB | Ứng dụng giới hạn upload 5 MB |
TRUST_PROXY=1 trong .env.production | Caddy gửi X-Forwarded-For; thiếu thì rate limit và phiên dùng chung IP của proxy |
| WebSocket | Caddy chuyển tiếp mặc định; Socket.IO ở /notifications cần |
flush_interval -1 | Stream chat SSE không bị gom đệm |
DNS của API_DOMAIN phải trỏ về VPS và cổng 80, 443 mở trước khi khởi động Caddy. Chưa kiểm chứng với DNS và chứng chỉ thật.
6. Cập nhật phiên bản
Quy trình đầy đủ (gắn tag image, kiểm tra readiness, điều kiện rollback): rollback. Lệnh tối thiểu khi chưa dùng IMAGE_TAG:
# sửa IMAGE_TAG trong .env.production rồi:
./scripts/deploy.sh
SIGTERM từ docker stop kích hoạt shutdown hook của Nest nên hàng đợi và kết nối database đóng gọn (app.enableShutdownHooks() trong main.ts). Quá trình này có thời gian ngừng ngắn vì chỉ có một container, và các token trong CACHE_MANAGER (đặt lại mật khẩu, hủy xóa tài khoản) mất khi khởi động lại (data-flow).
Nâng cấp Phase 1 (chạy một lần)
Sao lưu MongoDB và hai volume uploads, cv_storage trước (xem backup-and-recovery).
-
Kéo image mới (build sẵn ở CI), chưa khởi động lại backend. Chạy dedupe và tạo unique index bằng image mới:
docker compose -f docker-compose.prod.yml --env-file .env.production pull backenddocker compose -f docker-compose.prod.yml --env-file .env.production run --rm backend \node dist/databases/migrations/application-unique-index.jsĐơn trùng bị soft-delete (giữ đơn mới nhất) và có
deletedBy.email = "system:dedupe-migration". Chạy bước này trước khi code mới khởi động đểautoIndexkhông build index trên dữ liệu còn trùng. Chạy lại an toàn. -
Khởi động backend mới:
docker compose -f docker-compose.prod.yml --env-file .env.production up -d backend. -
Dời file CV cũ sang volume private:
docker compose -f docker-compose.prod.yml --env-file .env.production exec backend \node dist/databases/migrations/move-cv-files-to-private-storage.jsExit code 1 nghĩa là có file trùng tên khác nội dung; file đó vẫn nằm ở
public/images/...và cần xử lý tay. Từ bước 2 đến bước 3, CV cũ chưa mở được (404). -
Deploy frontend (nút "Xem CV" gọi
GET /resumes/:id/file).
7. Sao lưu
Xem backup-and-recovery.
Rollback
Xem Deploy và rollback: image gắn tag do CI đẩy lên Docker Hub, chọn bằng IMAGE_TAG; rollback bằng cách đặt lại tag cũ rồi chạy ./scripts/deploy.sh.
Known Limitation
- Không có CD, không có staging; mọi bước là tay.
- Một container, không có nhân bản; cần xử lý cron, Socket.IO, cache và file trước khi chạy nhiều instance (scalability).