done ver1.0.0
This commit is contained in:
315
DEPLOYMENT_GUIDE.md
Normal file
315
DEPLOYMENT_GUIDE.md
Normal file
@@ -0,0 +1,315 @@
|
||||
# 📘 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ị](#chuẩn-bị)
|
||||
2. [Máy DEV: Build & Push Image](#máy-dev-build--push-image)
|
||||
3. [Máy Server: Pull & Deploy](#máy-server-pull--deploy)
|
||||
4. [Kiểm tra & Troubleshoot](#kiểm-tra--troubleshoot)
|
||||
5. [Cập nhật bản mới](#cập-nhật-bản-mới)
|
||||
6. [Public Domain qua Nginx Proxy Manager](#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:
|
||||
```env
|
||||
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:
|
||||
```bash
|
||||
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)
|
||||
|
||||
```powershell
|
||||
cd D:\RoboticsSource\AccManager
|
||||
docker build -t toiiiiday/accmanager:1.0.3 .
|
||||
```
|
||||
|
||||
### Bước 3: Push image mới lên Docker Hub
|
||||
|
||||
```powershell
|
||||
docker push toiiiiday/accmanager:1.0.3
|
||||
```
|
||||
|
||||
### Bước 4: Kiểm tra image đã có trên registry
|
||||
|
||||
```powershell
|
||||
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:1.0.3
|
||||
```
|
||||
|
||||
Mẹo PowerShell (cập nhật nhanh):
|
||||
```powershell
|
||||
(Get-Content .env) -replace '^DOCKER_IMAGE=.*', 'DOCKER_IMAGE=toiiiiday/accmanager:1.0.3' | Set-Content .env
|
||||
```
|
||||
|
||||
### Bước 6: Copy .env lên server
|
||||
|
||||
Từ máy dev:
|
||||
```powershell
|
||||
scp .env robotics@172.20.235.176:~/accmanager/.env
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐧 Máy Server: Pull & Deploy
|
||||
|
||||
### Bước 1: SSH vào server
|
||||
|
||||
```bash
|
||||
ssh robotics@172.20.235.176
|
||||
```
|
||||
|
||||
### Bước 2: Vào thư mục deploy
|
||||
|
||||
```bash
|
||||
cd ~/accmanager
|
||||
```
|
||||
|
||||
### Bước 3: Pull image mới và chạy lại container
|
||||
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
docker compose -f docker-compose.image.yml ps
|
||||
```
|
||||
|
||||
Xem log:
|
||||
```bash
|
||||
docker compose -f docker-compose.image.yml logs -f accmanager
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Kiểm tra & Troubleshoot
|
||||
|
||||
### Kiểm tra app chạy OK
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
# Test HTTP
|
||||
curl -I http://127.0.0.1:3000
|
||||
```
|
||||
|
||||
### 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:1.0.3 .
|
||||
```
|
||||
3. Push:
|
||||
```powershell
|
||||
docker push toiiiiday/accmanager:1.0.3
|
||||
```
|
||||
4. Cập nhật `.env`:
|
||||
```env
|
||||
DOCKER_IMAGE=toiiiiday/accmanager:1.0.3
|
||||
```
|
||||
5. Copy `.env` lên server:
|
||||
```powershell
|
||||
scp .env robotics@172.20.235.176:~/accmanager/.env
|
||||
```
|
||||
|
||||
### Trên máy SERVER
|
||||
|
||||
6. SSH và vào thư mục deploy:
|
||||
```bash
|
||||
ssh robotics@172.20.235.176
|
||||
cd ~/accmanager
|
||||
```
|
||||
7. Pull + Up:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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`:
|
||||
```env
|
||||
DOCKER_IMAGE=toiiiiday/accmanager:1.0.2
|
||||
```
|
||||
```bash
|
||||
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)
|
||||
|
||||
### Trong Nginx Proxy Manager
|
||||
|
||||
1. **Add Proxy Host**
|
||||
- Domain Names: `pnkr.asia` (domain của bạn)
|
||||
- Scheme: `http`
|
||||
- Forward Hostname/IP: `172.20.235.176`
|
||||
- Forward Port: `3000`
|
||||
- Websocket Support: ON
|
||||
- Block Common Exploits: ON
|
||||
|
||||
2. **SSL**
|
||||
- Request a new SSL Certificate (Let's Encrypt)
|
||||
- Force SSL: ON
|
||||
- HTTP/2 Support: ON
|
||||
- HSTS: ON (sau khi test ổn định)
|
||||
|
||||
3. **Access**
|
||||
- http://pnkr.asia → auto redirect sang https
|
||||
- https://pnkr.asia ✅
|
||||
|
||||
---
|
||||
|
||||
## 📝 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:**
|
||||
```bash
|
||||
docker compose -f docker-compose.image.yml logs --tail=200 accmanager
|
||||
```
|
||||
Reference in New Issue
Block a user