poc_system/doc/DEPLOYMENT_GUIDE.md

🚀 Hướng dẫn Triển khai & Cấu hình Hệ thống

Tài liệu này hướng dẫn cấu hình manual, biến môi trường, và các lưu ý khi triển khai từ PoC lên Production.

---

0. Chạy hệ thống trên Localhost

Yêu cầu

• Python 3.10+ với venv đã cài dependencies
• Docker (cho OpenSearch)
• Azure AD App Registration đã cấu hình

Các bước khởi động

# 1. Khởi động OpenSearch
docker-compose up -d opensearch

# 2. Khởi động Backend (serves cả API + Frontend)
source venv/bin/activate
python3 api/main.py

# 3. Mở trình duyệt
# http://localhost:8000

Truy cập

URL	Mô tả
http://localhost:8000	Frontend (Login + Chat)
http://localhost:8000/docs	Swagger API Documentation
http://localhost:8000/health	Health check
http://localhost:8000/auth/login	SSO Azure AD redirect

Đăng nhập

• SSO: Bấm "Đăng nhập Microsoft SSO" → đăng nhập bằng tài khoản Microsoft 365
• Email: Nhập email bất kỳ (fallback, không cần password)

---

1. Cấu hình Azure AD App Registration (MANUAL)

1.1 Tạo App Registration (nếu chưa có)

1. Vào Azure Portal → Azure Active Directory → App registrations → New registration
2. Điền thông tin:
   • Name: VibeCode-RAG-PoC (hoặc tên tuỳ chọn)
   • Supported account types: Single tenant (chỉ tenant công ty)
   • Redirect URI: Để trống, sẽ thêm sau
3. Bấm Register
4. Ghi lại:
   • Application (client) ID → dùng cho CLIENT_ID
   • Directory (tenant) ID → dùng cho TENANT_ID

1.2 Tạo Client Secret

1. App Registration → Certificates & secrets → New client secret
2. Điền Description: RAG PoC Secret
3. Chọn thời hạn: 24 months (hoặc tuỳ nhu cầu)
4. Bấm Add
5. Copy ngay giá trị Secret → dùng cho CLIENT_SECRET (chỉ hiện 1 lần)

1.3 Cấp quyền Application Permissions

1. App Registration → API permissions → Add a permission
2. Chọn Microsoft Graph → Application permissions
3. Tìm và tích:
   • Sites.Read.All (đọc SharePoint sites)
   • Files.Read.All (đọc files trong drives)
4. Bấm Add permissions
5. Quan trọng: Bấm Grant admin consent for [tenant] → Confirm

1.4 Cấu hình Redirect URI cho SSO ✅ ĐÃ CẤU HÌNH

1. App Registration → Authentication → Add a platform → Web
2. Nhập Redirect URI:
   • PoC (localhost): http://localhost:8000/auth/callback ✅
   • Production: https://your-domain.com/auth/callback (thêm khi có domain)
3. Tích chọn: ✅ ID tokens (implicit grant) ✅
4. Bấm Save

1.5 Kiểm tra Token Claims

Sau khi cấu hình xong, decode token JWT và kiểm tra:

aud   : https://graph.microsoft.com
appid : <client-id-của-bạn>
idtyp : app
roles :
  - Sites.Read.All
  - Files.Read.All

Nếu token không có roles → quyền chưa đúng, kiểm tra lại bước 1.3.

---

2. Biến môi trường (.env)

2.1 File mẫu

# ===== Azure AD / Microsoft Graph =====
TENANT_ID=your-tenant-id-guid
CLIENT_ID=your-client-id-guid
CLIENT_SECRET=your-client-secret-value

# ===== SharePoint =====
# Site path để ingestion (đổi thành site SharePoint của bạn)
# Format: hostname:/sites/site-name
# Ví dụ: 285pdg.sharepoint.com:/sites/poc_system

# ===== OpenSearch =====
OPENSEARCH_HOST=opensearch        # Docker: "opensearch", Local: "localhost"
OPENSEARCH_PORT=9200
OPENSEARCH_USER=admin
OPENSEARCH_PASS=admin

# ===== VLM OCR Server (Vintern-3B) =====
VLM_ENDPOINT=http://10.202.50.3:8080/v1/chat/completions
VLM_TEMPERATURE=0.1
VLM_MAX_TOKENS=2000
VLM_TIMEOUT=120.0

# ===== Chat LLM =====
LLM_PROVIDER=gemini              # Options: gemini, groq, local
GEMINI_API_KEY=your-gemini-api-key
GROQ_API_KEY=your-groq-api-key
GROQ_MODEL=llama-3.3-70b-versatile
LOCAL_LLM_ENDPOINT=http://10.202.50.3:8081/v1/chat/completions

# ===== General =====
LOG_LEVEL=INFO
ENVIRONMENT=development           # development hoặc production

2.2 Giải thích từng biến

Biến	Bắt buộc	Mô tả
TENANT_ID	✅	Azure AD Tenant ID
CLIENT_ID	✅	Azure AD App Registration Client ID
CLIENT_SECRET	✅	Azure AD App Registration Client Secret
OPENSEARCH_HOST	✅	Hostname OpenSearch
OPENSEARCH_PORT	✅	Port OpenSearch (mặc định 9200)
VLM_ENDPOINT	✅	URL server VLM OCR (Vintern-3B)
LLM_PROVIDER	✅	LLM provider: gemini, groq, hoặc local
GEMINI_API_KEY	Nếu dùng Gemini	API key từ Google AI Studio
GROQ_API_KEY	Nếu dùng Groq	API key từ Groq Console
ENVIRONMENT	✅	development hoặc production

---

3. Kết nối SharePoint khác

3.1 Thay đổi Site Path

Chỉnh sửa trong file ingestion/providers/sharepoint_provider.py:

# Dòng 14 - Thay đổi hostname và site_path
def __init__(self, hostname: str = "your-company.sharepoint.com", site_path: str = "/sites/your-site-name"):

Hoặc gọi từ bên ngoài:

provider = SharePointProvider(
    hostname="your-company.sharepoint.com",
    site_path="/sites/your-site-name"
)

3.2 Kiểm tra quyền truy cập

App Registration phải có quyền trên site mới:

1. Nếu dùng Application Permissions (Sites.Read.All) → tự động truy cập mọi site
2. Nếu muốn giới hạn site cụ thể → dùng SharePoint App-Only Policy (nâng cao)

3.3 Xoá dữ liệu cũ

Khi đổi SharePoint site, cần xoá index cũ:

curl -X DELETE -u admin:admin "http://localhost:9200/poc_sharepoint_docs"

Sau đó chạy lại python3 test_rag_pipeline.py để nạp dữ liệu mới.

---

4. Triển khai Production

4.1 Yêu cầu hạ tầng

Component	Yêu cầu tối thiểu	Khuyến nghị
Server chính	4 CPU, 8GB RAM	8 CPU, 16GB RAM
OpenSearch	2 CPU, 4GB RAM	4 CPU, 8GB RAM
VLM OCR Server	GPU 8GB VRAM	GPU 16GB VRAM
Domain	Có SSL certificate	Let's Encrypt

4.2 Docker Compose Production

# docker-compose.prod.yml
version: '3.8'
services:
  opensearch:
    image: opensearchproject/opensearch:2.11.1
    environment:
      - discovery.type=single-node
      - OPENSEARCH_INITIAL_ADMIN_PASSWORD=StrongPassword123!
    ports:
      - "9200:9200"
    volumes:
      - opensearch-data:/usr/share/opensearch/data

  rag-api:
    build: .
    ports:
      - "8000:8000"
    env_file: .env
    environment:
      - ENVIRONMENT=production
      - OPENSEARCH_HOST=opensearch
    depends_on:
      - opensearch

  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./certs:/etc/nginx/certs
      - ./frontend:/usr/share/nginx/html
    depends_on:
      - rag-api

volumes:
  opensearch-data:

4.3 Nginx config mẫu

# nginx.conf
events {
    worker_connections 1024;
}

http {
    server {
        listen 443 ssl;
        server_name your-domain.com;

        ssl_certificate /etc/nginx/certs/fullchain.pem;
        ssl_certificate_key /etc/nginx/certs/privkey.pem;

        # Frontend
        location / {
            root /usr/share/nginx/html;
            index index.html;
            try_files $uri $uri/ /index.html;
        }

        # API
        location /api/ {
            proxy_pass http://rag-api:8000/;
            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;
        }
    }

    # Redirect HTTP → HTTPS
    server {
        listen 80;
        server_name your-domain.com;
        return 301 https://$host$request_uri;
    }
}

4.4 Thay đổi khi Production

1. Frontend: Sửa API_BASE trong app.js:

   const API_BASE = '/api';  // Thay vì 'http://localhost:8000'
   

2. SSO Redirect URI: Cập nhật trong Azure AD:

   https://your-domain.com/auth/callback
   

3. .env:

   OPENSEARCH_HOST=opensearch
   ENVIRONMENT=production
   

4. OpenSearch password: Đổi password mặc định:

   OPENSEARCH_USER=admin
   OPENSEARCH_PASS=YourStrongPassword123!
   

5. CORS: Giới hạn origins trong api/main.py:

   allow_origins=["https://your-domain.com"]
   

---

5. Kiểm tra sau triển khai

5.1 Kiểm tra kết nối

# 1. OpenSearch
curl -u admin:admin http://localhost:9200/_cluster/health

# 2. API
curl http://localhost:8000/health

# 3. Frontend
curl -I http://localhost/

5.2 Kiểm tra SSO

1. Mở https://your-domain.com
2. Bấm "Đăng nhập Microsoft SSO"
3. Đăng nhập bằng tài khoản Microsoft 365
4. Kiểm tra user info hiển thị đúng

5.3 Kiểm tra Pipeline

# Trigger sync
curl -X POST http://localhost:8000/sync

# Kiểm tra sync status
curl http://localhost:8000/sync/status

# Kiểm tra chunks trong OpenSearch
curl -u admin:admin http://localhost:9200/poc_sharepoint_docs/_count

5.4 Kiểm tra ACL

# Test search với user có quyền
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -H "X-User-Email: user@yourcompany.com" \
  -H "X-User-Role: user" \
  -d '{"query": "test"}'

# Test search với admin (bypass ACL)
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -H "X-User-Role: admin" \
  -d '{"query": "test"}'

---

6. Xử lý lỗi thường gặp

Lỗi	Nguyên nhân	Giải pháp
SSO redirect_uri_mismatch	Redirect URI chưa đúng	Kiểm tra URI trong Azure AD khớp với callback URL
Token không có roles	App dùng Delegated thay vì Application permissions	Đổi sang Application permissions + Grant admin consent
OpenSearch connection refused	Chưa khởi động Docker	docker-compose up -d opensearch
VLM OCR timeout	Server VLM quá tải hoặc offline	Kiểm tra VLM_ENDPOINT có truy cập được
Search trả 0 kết quả	Chưa nạp dữ liệu hoặc sai index name	Chạy python3 test_rag_pipeline.py

---

7. Checklist trước khi Production

• Azure AD App Registration đã cấu hình đúng permissions
• Client Secret còn hạn sử dụng
• Redirect URI đã thêm cho localhost (http://localhost:8000/auth/callback)
• ID tokens đã bật (implicit grant)
• Redirect URI cho production domain (khi có domain thật)
• OpenSearch đã đổi password mặc định
• SSL certificate đã cài đặt
• CORS đã giới hạn origins
• .env đã cấu hình cho production
• Docker Compose production đã test
• Backup strategy cho OpenSearch data
• Monitoring (CPU, RAM, disk) đã setup

---

Tài liệu này cần được cập nhật khi có thay đổi về hạ trúc hoặc cấu hình.