ManagerAccount/DEPLOYMENT_GUIDE.md

📘 Hướng dẫn Triển khai AccManager

Tài liệu này hướng dẫn chi tiết cách build Docker image, push lên registry, và triển khai trên server.

---

📋 Mục lục

1. Chuẩn bị
2. Máy DEV: Build & Push Image
3. Máy Server: Pull & Deploy
4. Kiểm tra & Troubleshoot
5. Cập nhật bản mới
6. Public Domain qua Nginx Proxy Manager

---

🔧 Chuẩn bị

Tài khoản & Biến môi trường

1. Docker Hub Account: Tạo account tại https://hub.docker.com

   • Username: toiiiiday (dùng username của bạn)
   • Repository: accmanager

2. File .env trên máy dev - Kiểm tra nội dung:

   NODE_ENV=production
   APP_PORT=3000
   DOCKER_IMAGE=toiiiiday/accmanager:1.0.1
   PORT=3000
   DB_SERVER=172.20.235.176
   DB_USER=sa
   DB_PASSWORD=robotics@2022
   DB_NAME=AccManager
   DB_ENCRYPT=false
   DB_TRUST_CERTIFICATE=true
   DB_CONNECT_TIMEOUT=30000
   BCRYPT_ROUNDS=12
   

3. Thư mục trên server - SSH vào server tạo:

   mkdir -p ~/accmanager
   cd ~/accmanager
   

---

🖥️ Máy DEV: Build & Push Image

Bước 1: Chọn version mới

Mỗi lần sửa code và muốn deploy, chọn một tag mới theo thứ tự tăng dần.

Ví dụ:

• Bản cũ đang chạy: 1.0.2
• Bản mới sau khi sửa code: 1.0.3

Bước 2: Build image mới (trên máy DEV)

cd D:\RoboticsSource\AccManager
docker build -t toiiiiday/accmanager:"version" .

Bước 3: Push image mới lên Docker Hub

docker push toiiiiday/accmanager:"version"

Bước 4: Kiểm tra image đã có trên registry

docker image ls | findstr toiiiiday/accmanager

Hoặc kiểm tra trên Docker Hub: https://hub.docker.com/r/toiiiiday/accmanager/tags

Bước 5: Cập nhật .env

Sửa dòng DOCKER_IMAGE:

DOCKER_IMAGE=toiiiiday/accmanager:"version"

Mẹo PowerShell (cập nhật nhanh):

(Get-Content .env) -replace '^DOCKER_IMAGE=.*', 'DOCKER_IMAGE=toiiiiday/accmanager:1.0.3' | Set-Content .env

Bước 6: Copy confi lên server

Từ máy dev:

scp .env robotics@172.20.235.176:~/accmanager/.env
scp docker-compose.yml robotics@172.20.235.176:~/accmanager/docker-compose.yml
scp docker-compose.image.yml robotics@172.20.235.176:~/accmanager/docker-compose.image.yml

---

🐧 Máy Server: Pull & Deploy

Bước 1: SSH vào server

ssh robotics@172.20.235.176

Bước 2: Vào thư mục deploy

cd ~/accmanager

Bước 3: Pull image mới và chạy lại container

docker compose --env-file .env -f docker-compose.image.yml pull accmanager
docker compose --env-file .env -f docker-compose.image.yml up -d accmanager

Kiểm tra trạng thái:

docker compose -f docker-compose.image.yml ps

Xem log:

docker compose -f docker-compose.image.yml logs -f accmanager

---

✅ Kiểm tra & Troubleshoot

Kiểm tra app chạy OK

# Kiểm tra container đang running
docker compose -f docker-compose.image.yml ps

# Xem log (tìm "Server running")
docker compose -f docker-compose.image.yml logs --tail=50 accmanager


### Nếu gặp lỗi

**Lỗi: "image not found"**
- Kiểm tra: `cat .env | grep DOCKER_IMAGE`
- Đảm bảo image đã push lên Docker Hub, kiểm tra: https://hub.docker.com/r/toiiiiday/accmanager

**Lỗi: "connection refused"**
- Kiểm tra DB Server có chạy: `ssh robotics@172.20.235.176`
- Kiểm tra DB credentials trong .env

**Lỗi: Container restart liên tục**
- Xem log: `docker compose -f docker-compose.image.yml logs --tail=100 accmanager`

---

## 🔄 Cập nhật bản mới

Áp dụng đúng 8 bước sau cho mỗi lần sửa code:

### Trên máy DEV

1. Chọn version mới (ví dụ `1.0.3`)
2. Build:
```powershell
docker build -t toiiiiday/accmanager:"version" .

3. Push:

docker push toiiiiday/accmanager:"version"

4. Cập nhật .env:

DOCKER_IMAGE=toiiiiday/accmanager:"version"

5. Copy .env lên server:

scp .env robotics@172.20.235.176:~/accmanager/.env

Trên máy SERVER

6. SSH và vào thư mục deploy:

ssh robotics@172.20.235.176
cd ~/accmanager

7. Pull + Up:

docker compose --env-file .env -f docker-compose.image.yml pull accmanager
docker compose --env-file .env -f docker-compose.image.yml up -d accmanager

8. Kiểm tra bản mới đã chạy:

docker compose -f docker-compose.image.yml ps
docker compose -f docker-compose.image.yml logs --tail=50 accmanager

Có cần gắn tag/version cho mỗi phiên bản mới không?

Có, nên làm bắt buộc cho production.

Lý do:

1. Tránh đè image cũ và tránh nhầm lẫn khi deploy.
2. Rollback nhanh về bản ổn định trước đó.
3. Truy vết được bản code nào đang chạy trên server.
4. Tránh rủi ro do dùng latest (khó kiểm soát).

Quy ước khuyến nghị:

• 1.0.2 -> fix nhỏ
• 1.1.0 -> thêm tính năng
• 2.0.0 -> thay đổi lớn/breaking

Ví dụ rollback về bản cũ 1.0.2:

DOCKER_IMAGE=toiiiiday/accmanager:1.0.2

docker compose --env-file .env -f docker-compose.image.yml pull accmanager
docker compose --env-file .env -f docker-compose.image.yml up -d accmanager

---

🌐 Public Domain qua Nginx Proxy Manager

Chuẩn bị

1. Domain

   • Trỏ DNS A record về IP public nơi đặt Nginx Proxy Manager

2. Firewall/Router

   • Mở inbound port 80, 443 từ Internet
   • Port 3000 chỉ nội bộ (không public)

---

📝 Các file liên quan

• docker-compose.yml - Build local
• docker-compose.image.yml - Pull & run từ registry
• .env - Biến môi trường
• .dockerignore - Ignore file khi build
• Dockerfile - Config image
• deploy-dev.ps1 - Script build & push (Windows)
• deploy-server.sh - Script pull & deploy (Linux)

---

🎯 Tóm tắt quy trình

Máy DEV
├─ Chỉnh sửa code
├─ docker build -t toiiiiday/accmanager:X .
├─ docker push toiiiiday/accmanager:X
├─ sửa DOCKER_IMAGE trong .env
└─ scp .env server                (copy env)

Máy Server
├─ ssh vào server
├─ cd ~/accmanager
├─ docker compose pull accmanager
└─ docker compose up -d accmanager
  
Nginx Proxy Manager
└─ Forward từ domain → http://172.20.235.176:3000

---

💡 Mẹo

1. Luôn tăng version tag: 1.0.1 → 1.0.2 → 1.0.3
2. Rollback nhanh: Chỉ cần đổi DOCKER_IMAGE trong .env sang tag cũ rồi deploy lại
3. Giữ log: docker compose logs --tail=1000 > backup.log
4. Restart container: docker compose -f docker-compose.image.yml restart accmanager
5. Xóa container cũ: docker compose -f docker-compose.image.yml down
6. Không dùng latest cho production: luôn deploy bằng tag cụ thể

---

Cần giúp? Xem log chi tiết:

docker compose -f docker-compose.image.yml logs --tail=200 accmanager