Hướng dẫn Build & Deploy

Tài liệu hướng dẫn build và deploy Automation Guide Generator lên VPS.

Tổng quan kiến trúc

┌─────────────────────────────────────────────────────────┐
│                    VPS Production                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
│  │   Nginx     │  │ API Server  │  │    MongoDB      │  │
│  │   :80/443   │──│   :8000     │──│  (Atlas/Local)  │  │
│  │  (WebUI +   │  │  (Docker)   │  │                 │  │
│  │   Proxy)    │  │             │  │                 │  │
│  └─────────────┘  └─────────────┘  └─────────────────┘  │
└─────────────────────────────────────────────────────────┘
                          ▲
                          │ Internet
                          ▼
┌─────────────────────────────────────────────────────────┐
│                   Client Machine                         │
│  ┌─────────────────┐      ┌─────────────────────────┐   │
│  │     Browser     │      │      Local Agent        │   │
│  │   (Web UI)      │      │   (Tray App :8001)      │   │
│  └─────────────────┘      └─────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Yêu cầu

Máy local (build)

Node.js 18+
Python 3.8+
Docker (nếu build Docker image)

VPS Production

Ubuntu 20.04+
Docker & Docker Compose
Nginx
2GB RAM minimum

Phần 1: Build API Server (Docker)

1.1. Chuẩn bị files

Tạo archive chứa các files cần thiết:

bash

cd automation-guide

# Tạo archive
tar -czvf server-build.tar.gz \
  Dockerfile.server \
  .env.example \
  requirements.txt \
  run_server.py \
  src/ \
  build/docker/ \
  --exclude='__pycache__' \
  --exclude='*.pyc' \
  --exclude='.pytest_cache' \
  --exclude='src/local_agent'

1.2. Upload lên VPS build

bash

# Upload (thay port và IP theo server của bạn)
scp -P 24700 server-build.tar.gz root@your-server:/tmp/

1.3. Build Docker image trên VPS

bash

# SSH vào server
ssh -p 24700 root@your-server

# Giải nén
cd /tmp
mkdir -p automation-guide && cd automation-guide
tar -xzvf ../server-build.tar.gz

# Build image
docker build -f Dockerfile.server -t automation-guide-server:latest .

# Tag cho registry (thay registry URL)
docker tag automation-guide-server:latest registry.inet.vn/automation-guide-server:latest
docker tag automation-guide-server:latest registry.inet.vn/automation-guide-server:v1.0.0

# Push lên registry
docker login registry.inet.vn
docker push registry.inet.vn/automation-guide-server:latest
docker push registry.inet.vn/automation-guide-server:v1.0.0

1.4. Hoặc dùng script tự động

bash

chmod +x build/docker/build_and_push.sh
./build/docker/build_and_push.sh --push --tag v1.0.0 --registry registry.inet.vn

Phần 2: Build Web UI

2.1. Build trên máy local

bash

cd interactive-doc-creator

# Cài dependencies
npm install

# (Optional) Cấu hình API URL nếu khác domain
# Tạo file .env:
# VITE_API_URL=https://guide-api.yourdomain.com

# Build production
npm run build

Output: dist/ folder

2.2. Đóng gói và upload

bash

# Nén dist folder
tar -czvf webui-dist.tar.gz dist/

# Upload lên VPS
scp -P 24700 webui-dist.tar.gz root@your-server:/tmp/

Phần 3: Deploy trên VPS Production

3.1. Chuẩn bị môi trường

bash

# SSH vào VPS production
ssh -p 24700 root@your-server

# Cài Docker (nếu chưa có)
curl -fsSL https://get.docker.com | sh

# Cài Nginx
apt update && apt install -y nginx

# Tạo thư mục
mkdir -p /opt/automation-guide
mkdir -p /var/www/automation-guide

3.2. Cấu hình environment

bash

# Tạo file .env
cat > /opt/automation-guide/.env << 'EOF'
# MongoDB
MONGODB_URI=mongodb+srv://user:password@cluster.mongodb.net
MONGODB_DATABASE=autodocs

# AI Keys (optional)
GOOGLE_API_KEY=your-gemini-api-key
OPENAI_API_KEY=your-openai-api-key

# Upload API (optional)
UPLOAD_API_URL=https://helpdesk.inet.vn/api/upload

# Server
HOST=0.0.0.0
PORT=8000
EOF

# Bảo mật file
chmod 600 /opt/automation-guide/.env

3.3. Deploy API Server (Docker)

bash

# Pull image từ registry
docker login registry.inet.vn
docker pull registry.inet.vn/automation-guide-server:latest

# Chạy container
docker run -d \
  --name guide-api-server \
  --restart unless-stopped \
  -p 8000:8000 \
  -v /opt/automation-guide/.env:/app/.env:ro \
  -v /opt/automation-guide/output:/app/output \
  -v /opt/automation-guide/data:/app/data \
  registry.inet.vn/automation-guide-server:latest

# Kiểm tra
docker logs -f guide-api-server
curl http://localhost:8000/health

3.4. Deploy Web UI

bash

# Giải nén WebUI
cd /var/www/automation-guide
tar -xzvf /tmp/webui-dist.tar.gz --strip-components=1

# Set permissions
chown -R www-data:www-data /var/www/automation-guide

3.5. Cấu hình Nginx

bash

# Tạo config
cat > /etc/nginx/sites-available/guide.conf << 'EOF'
server {
    listen 80;
    server_name guide.yourdomain.com;  # Thay domain

    # Web UI
    root /var/www/automation-guide;
    index index.html;

    gzip on;
    gzip_types text/plain text/css application/json application/javascript;

    # SPA routing
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API proxy
    location /api/ {
        proxy_pass http://127.0.0.1:8000/api/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }

    # WebSocket proxy
    location /ws/ {
        proxy_pass http://127.0.0.1:8000/ws/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400s;
    }

    # Health check
    location /health {
        proxy_pass http://127.0.0.1:8000/health;
    }

    # Static caching
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
EOF

# Enable site
ln -sf /etc/nginx/sites-available/guide.conf /etc/nginx/sites-enabled/
rm -f /etc/nginx/sites-enabled/default

# Test và reload
nginx -t
systemctl reload nginx

3.6. (Optional) Cài SSL với Certbot

bash

apt install -y certbot python3-certbot-nginx
certbot --nginx -d guide.yourdomain.com

Phần 4: Quản lý & Bảo trì

4.1. Xem logs

bash

# API Server logs
docker logs -f guide-api-server

# Nginx logs
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log

4.2. Restart services

bash

# API Server
docker restart guide-api-server

# Nginx
systemctl restart nginx

4.3. Update API Server

bash

# Pull image mới
docker pull registry.inet.vn/automation-guide-server:latest

# Stop và remove container cũ
docker stop guide-api-server
docker rm guide-api-server

# Chạy lại với image mới
docker run -d \
  --name guide-api-server \
  --restart unless-stopped \
  -p 8000:8000 \
  -v /opt/automation-guide/.env:/app/.env:ro \
  -v /opt/automation-guide/output:/app/output \
  -v /opt/automation-guide/data:/app/data \
  registry.inet.vn/automation-guide-server:latest

4.4. Update Web UI

bash

# Upload file mới
scp -P 24700 webui-dist.tar.gz root@your-server:/tmp/

# Trên server
cd /var/www/automation-guide
rm -rf *
tar -xzvf /tmp/webui-dist.tar.gz --strip-components=1
chown -R www-data:www-data .

4.5. Backup

bash

# Backup .env
cp /opt/automation-guide/.env /opt/automation-guide/.env.backup

# Backup output
tar -czvf /backup/output-$(date +%Y%m%d).tar.gz /opt/automation-guide/output/

Phần 5: Build Local Agent (Windows)

Cho người dùng cuối cài trên máy Windows.

5.1. Build trên máy Windows

bash

cd automation-guide

# Cài dependencies
pip install -r requirements.txt
pip install pyinstaller pillow

# Build
python build/agent/build_agent.py --tray

Output: dist/agent/windows/GuideAgent.exe

5.2. Build Installer (Optional)

Cần cài Inno Setup:

bash

python build/installer/build_installer.py

Output: dist/installer/GuideAgentSetup-1.0.0.exe

Troubleshooting

API Server không start

bash

# Kiểm tra logs
docker logs guide-api-server

# Kiểm tra .env
cat /opt/automation-guide/.env

# Kiểm tra port
netstat -tlnp | grep 8000

WebSocket không kết nối

Kiểm tra nginx config có proxy WebSocket
Kiểm tra firewall cho phép port 80/443

Local Agent không kết nối

Kiểm tra agent đang chạy: http://127.0.0.1:8001/health
Kiểm tra firewall không chặn port 8001

Ports Summary

Service	Port	Description
Nginx	80/443	Web UI + Reverse Proxy
API Server	8000	REST API + WebSocket
Local Agent	8001	Local WebSocket (client)
MongoDB	27017	Database (nếu local)

Files Reference

automation-guide/
├── Dockerfile.server           # Docker build cho API Server
├── docker-compose.server.yml   # Docker Compose config
├── build/
│   ├── docker/
│   │   ├── build_and_push.sh   # Script build & push image
│   │   ├── deploy.sh           # Script deploy trên VPS
│   │   └── README.md
│   ├── nginx/
│   │   ├── guide.conf          # Nginx config template
│   │   └── setup.sh            # Script setup nginx
│   ├── agent/
│   │   └── build_agent.py      # Build Local Agent
│   └── installer/
│       └── build_installer.py  # Build Windows Installer
└── DEPLOYMENT.md               # File này

Maintainer: iNET Software DevOps Team
Last Updated: December 2024

Hướng dẫn Build & Deploy ​

Tổng quan kiến trúc ​

Yêu cầu ​

Máy local (build) ​

VPS Production ​

Phần 1: Build API Server (Docker) ​

1.1. Chuẩn bị files ​

1.2. Upload lên VPS build ​

1.3. Build Docker image trên VPS ​

1.4. Hoặc dùng script tự động ​

Phần 2: Build Web UI ​

2.1. Build trên máy local ​

2.2. Đóng gói và upload ​

Phần 3: Deploy trên VPS Production ​

3.1. Chuẩn bị môi trường ​

3.2. Cấu hình environment ​

3.3. Deploy API Server (Docker) ​

3.4. Deploy Web UI ​

3.5. Cấu hình Nginx ​

3.6. (Optional) Cài SSL với Certbot ​

Phần 4: Quản lý & Bảo trì ​

4.1. Xem logs ​

4.2. Restart services ​

4.3. Update API Server ​

4.4. Update Web UI ​

4.5. Backup ​

Phần 5: Build Local Agent (Windows) ​

5.1. Build trên máy Windows ​

5.2. Build Installer (Optional) ​

Troubleshooting ​

API Server không start ​

WebSocket không kết nối ​

Local Agent không kết nối ​

Ports Summary ​

Files Reference ​

Hướng dẫn Build & Deploy

Tổng quan kiến trúc

Yêu cầu

Máy local (build)

VPS Production

Phần 1: Build API Server (Docker)

1.1. Chuẩn bị files

1.2. Upload lên VPS build

1.3. Build Docker image trên VPS

1.4. Hoặc dùng script tự động

Phần 2: Build Web UI

2.1. Build trên máy local

2.2. Đóng gói và upload

Phần 3: Deploy trên VPS Production

3.1. Chuẩn bị môi trường

3.2. Cấu hình environment

3.3. Deploy API Server (Docker)

3.4. Deploy Web UI

3.5. Cấu hình Nginx

3.6. (Optional) Cài SSL với Certbot

Phần 4: Quản lý & Bảo trì

4.1. Xem logs

4.2. Restart services

4.3. Update API Server

4.4. Update Web UI

4.5. Backup

Phần 5: Build Local Agent (Windows)

5.1. Build trên máy Windows

5.2. Build Installer (Optional)

Troubleshooting

API Server không start

WebSocket không kết nối

Local Agent không kết nối

Ports Summary

Files Reference