System Guide

Deployment Guide

UP: 07/04/2026

AI MODERATOR

~15 MINS

DEPLOYMENT — Nhà Cộng

Phiên bản: 2026-03-17

Tài liệu này là bản hướng dẫn tổng hợp để triển khai và vận hành hệ thống Nhà Cộng (backend + frontend + DB), được xây dựng sau khi rà soát nhanh repository.

Mục lục

Tổng quan kiến trúc
Yêu cầu hạ tầng
Biến môi trường cần thiết
Build & Run (local và production)
Docker / Docker Compose
Migrations & Seed
CI/CD (gợi ý GitHub Actions)
Healthchecks, logging, backup & rollback
Checklist triển khai
Các bước tiếp theo (tùy chọn)

1. Tổng quan kiến trúc

Backend: NestJS 10 + TypeScript + TypeORM (MySQL)
- Thư mục:
  DOCUMENTATION CODE
  backend/
- Scripts chính: xem
  DOCUMENTATION CODE
  backend/package.json
  (ví dụ
  DOCUMENTATION CODE
  npm run build
  ,
  DOCUMENTATION CODE
  npm run start:prod
  ,
  DOCUMENTATION CODE
  migration:run
  )
Frontend: Next.js 16 (App Router) + Tailwind + Ant Design
- Thư mục:
  DOCUMENTATION CODE
  frontend/
- Scripts chính:
  DOCUMENTATION CODE
  npm run dev
  ,
  DOCUMENTATION CODE
  npm run build
  ,
  DOCUMENTATION CODE
  npm run start
  (standalone)
Containerization:
DOCUMENTATION CODE
```
Dockerfile
```
,
DOCUMENTATION CODE
```
Dockerfile.dev
```
trong từng service;
DOCUMENTATION CODE
```
docker-compose.yml
```
và
DOCUMENTATION CODE
```
docker-compose.staging.yml
```
ở root.

2. Yêu cầu hạ tầng

Linux server (Ubuntu 22.04+ recommended)
Docker & Docker Compose (v2+)
MySQL 8.x (có thể RDS)
Node.js (chỉ cần khi build ngoài container)
(Optional) Redis, S3-compatible storage
Access: SSH key cho CI/CD hoặc deploy user

3. Biến môi trường quan trọng

Lưu secrets ngoài repo (Vault / GH Secrets / env file trên server). Dưới đây là danh sách tối thiểu:

Backend (ít nhất):

DOCUMENTATION CODE
```
DB_HOST
```
,
DOCUMENTATION CODE
```
DB_PORT
```
,
DOCUMENTATION CODE
```
DB_USER
```
,
DOCUMENTATION CODE
```
DB_PASS
```
,
DOCUMENTATION CODE
```
DB_NAME
```
DOCUMENTATION CODE
```
DB_SYNCHRONIZE=false
```
(PHẢI luôn false trên production)
DOCUMENTATION CODE
```
JWT_SECRET
```
DOCUMENTATION CODE
```
CORS_ORIGIN
```
DOCUMENTATION CODE
```
STORAGE_TYPE
```
(
DOCUMENTATION CODE
```
local
```
|
DOCUMENTATION CODE
```
s3
```
) +
DOCUMENTATION CODE
```
STORAGE_S3_BUCKET
```
,
DOCUMENTATION CODE
```
STORAGE_S3_REGION
```
,
DOCUMENTATION CODE
```
STORAGE_S3_ACCESS_KEY_ID
```
,
DOCUMENTATION CODE
```
STORAGE_S3_SECRET_ACCESS_KEY
```
DOCUMENTATION CODE
```
MAIL_DRIVER
```
(
DOCUMENTATION CODE
```
smtp
```
|
DOCUMENTATION CODE
```
resend
```
) +
DOCUMENTATION CODE
```
RESEND_API_KEY
```
nếu dùng resend
DOCUMENTATION CODE
```
VNPAY_*
```
,
DOCUMENTATION CODE
```
ZALO_*
```
nếu dùng các gateway tương ứng

Frontend (ít nhất):

DOCUMENTATION CODE
```
NEXT_PUBLIC_API_URL
```
(ví dụ: https://api.example.com/api)
DOCUMENTATION CODE
```
NEXT_PUBLIC_SITE_URL
```
DOCUMENTATION CODE
```
NEXT_PUBLIC_GOOGLE_CLIENT_ID
```

Ghi chú: kiểm tra

DOCUMENTATION CODE

backend/.env.example

và

DOCUMENTATION CODE

frontend/env.example

để biết chi tiết.

4. Build & Run

A. Không dùng container (local/VM)

Backend:

DOCUMENTATION CODE
cd backend
npm install
npm run build
# kiểm tra migration/seed nếu cần
npm run migration:run
NODE_ENV=production npm run start:prod

Frontend:

DOCUMENTATION CODE
cd frontend
npm install
npm run build
# (tạo standalone nếu cần)
npm run start

B. Với Docker (khuyến nghị dùng trên server)

Build images (ví dụ để đẩy lên registry):

DOCUMENTATION CODE
docker build -t myregistry/nhacong-backend:latest -f backend/Dockerfile ./backend
docker build -t myregistry/nhacong-frontend:latest -f frontend/Dockerfile ./frontend

Chạy local via compose:

DOCUMENTATION CODE
docker compose -f docker-compose.yml up -d --build

5. Migrations & Seed

Tạo migration (dev):

DOCUMENTATION CODE

npm run migration:generate -- src/database/migrations/DescribeChange

Chạy migration (staging/prod):
DOCUMENTATION CODE
```
npm run migration:run
```
Revert (cẩn trọng):
DOCUMENTATION CODE
```
npm run migration:revert
```
Seed data:
DOCUMENTATION CODE
```
npm run seed
```
hoặc
DOCUMENTATION CODE
```
npm run seed:refresh
```
(xem
DOCUMENTATION CODE
```
backend/package.json
```
)

Luôn backup DB trước khi áp migration quan trọng.

6. CI/CD — Mẫu workflow

Gợi ý pipeline GitHub Actions:

Trigger: push vào
DOCUMENTATION CODE
```
main
```
(production) hoặc
DOCUMENTATION CODE
```
staging
```
(staging)
Steps:
1. Checkout
2. Setup Node
3. Install & run lint/tests
4. Build frontend (next build) and archive standalone
5. Build backend (npm run build)
6. Build & push Docker images (GHCR/ECR)
7. SSH vào server:
  DOCUMENTATION CODE
  docker compose pull && docker compose up -d
  và
  DOCUMENTATION CODE
  docker compose exec backend npm run migration:run

( Nếu muốn, tôi có thể tạo

DOCUMENTATION CODE

/.github/workflows/deploy.yml

mẫu )

7. Healthchecks, logging & monitoring

Health: kiểm tra endpoint (nếu backend có route health), hoặc kiểm tra swagger
DOCUMENTATION CODE
```
/docs
```
để xác nhận service.
Logs: dùng
DOCUMENTATION CODE
```
docker logs -f <container>
```
hoặc chuyển sang log driver/ELK.
Monitoring: Uptime checks (UptimeRobot), metrics (Prometheus/Grafana) nếu cần.

8. Backup & Rollback

Backup DB:

DOCUMENTATION CODE
mysqldump -h $DB_HOST -u $DB_USER -p$DB_PASS $DB_NAME > backup-$(date +%F).sql

Rollback nhanh: redeploy image cũ hoặc restore DB từ dump.
Nếu migration gây lỗi:
DOCUMENTATION CODE
```
npm run migration:revert
```
(nếu migration hỗ trợ revert) hoặc restore DB.

9. Checklist triển khai (ngắn)

Cập nhật
DOCUMENTATION CODE
```
main
```
branch và build trên CI
Đảm bảo tất cả secret đã có trên server/GH Secrets
Backup DB
Pull & chạy migration trên staging trước
Kiểm tra API & UI trên staging
Deploy production, run migration, kiểm tra health

10. Gợi ý bước tiếp theo tôi có thể làm cho bạn

Tạo
DOCUMENTATION CODE
```
deploy.sh
```
(SSH + pull + compose + migrate) mẫu trong repo.
Tạo GitHub Actions workflow mẫu để build/push & deploy.
Làm runbook chi tiết cho DevOps (kịch bản rollback, monitoring, run commands).

Cho tôi biết muốn mình làm mục nào (1/2/3) — mình sẽ tạo file tương ứng.

Affiliate Management