starter-kit/docs/secrets.md

CI/CD Workflows

ULFlow Starter Kit sử dụng Gitea Actions để tự động hóa quy trình CI/CD. Tài liệu này mô tả các workflow được cấu hình và các biến cần thiết.

Tổng quan về quy trình

Quy trình CI/CD được thiết kế để hoạt động như sau:

1. CI Pipeline chạy trên tất cả các nhánh ngoại trừ main
2. Docker Build chạy khi đánh tag hoặc sau khi merge vào main
3. Deploy to VPS chỉ chạy khi đánh tag phiên bản (format v*)

Workflow Files

1. CI Pipeline (.gitea/workflows/ci.yml)

CI Pipeline chạy trên tất cả các nhánh ngoại trừ main và bao gồm các job:

• Lint: Kiểm tra chất lượng mã với golangci-lint
• Security Scan: Quét lỗ hổng bảo mật với govulncheck
• Test: Chạy unit tests và tạo báo cáo coverage
• Build: Build ứng dụng và tạo artifact
• Notify: Thông báo kết quả

2. Docker Build & Deploy (.gitea/workflows/docker.yml)

Workflow này chạy khi:

• Đánh tag phiên bản (format v*)
• Sau khi CI Pipeline thành công trên nhánh main

Bao gồm các job:

• Docker Build: Build và push Docker image lên Gitea Container Registry
• Deploy to VPS: Triển khai ứng dụng lên VPS (chỉ khi đánh tag)

Cấu hình Secrets

Để các workflow hoạt động đúng, bạn cần cấu hình các secrets sau trong Gitea:

Secrets cho Runner

Secret	Mô tả	Mặc định
RUNNER_LABEL	Label của runner cho các job CI	ubuntu-latest
DEPLOY_RUNNER	Label của runner cho job deploy	ubuntu-latest

Secrets cho Docker Registry

Secret	Mô tả	Bắt buộc
REGISTRY_URL	URL của Gitea Container Registry	✅
REGISTRY_USERNAME	Username để đăng nhập vào registry	✅
REGISTRY_PASSWORD	Password để đăng nhập vào registry	✅
REPOSITORY_PATH	Đường dẫn repository trong registry	✅

Secrets cho Deployment

Secret	Mô tả	Mặc định
CONTAINER_NAME	Tên container	ulflow-api-container
DOCKER_NETWORK	Tên network Docker	ulflow-network
APP_PORT	Port để expose	3000
APP_ENV	Môi trường ứng dụng	production
CONTAINER_MEMORY	Giới hạn bộ nhớ	1g
CONTAINER_CPU	Giới hạn CPU	1
HEALTH_CMD	Command kiểm tra health	`curl -f http://localhost:3000/health
HEALTH_INTERVAL	Khoảng thời gian kiểm tra health	30s

Secrets cho Database

Secret	Mô tả	Bắt buộc
DB_HOST	Hostname của database	✅
DB_USER	Username database	✅
DB_PASSWORD	Password database	✅
DB_NAME	Tên database	✅

Secrets cho Security

Secret	Mô tả	Bắt buộc
JWT_SECRET_KEY	Secret key cho JWT	✅
REFRESH_TOKEN_SECRET	Secret key cho refresh token	✅
API_KEY	API key	✅
ENCRYPTION_KEY	Key mã hóa dữ liệu	✅

Cấu hình Gitea

Tạo Secrets trong Gitea

1. Truy cập repository trong Gitea
2. Vào Settings > Secrets
3. Thêm từng secret với tên và giá trị tương ứng

Cấu hình Runner

1. Đảm bảo Gitea Runner đã được cài đặt và kết nối với Gitea
2. Nếu sử dụng custom runner, cập nhật RUNNER_LABEL và DEPLOY_RUNNER tương ứng

Ví dụ quy trình làm việc

1. Phát triển tính năng:

   git checkout -b feat/new-feature
   # Làm việc và commit
   git push origin feat/new-feature
   

   → CI Pipeline tự động chạy

2. Merge vào main:

   • Tạo Pull Request từ feat/new-feature vào main
   • Sau khi merge, Docker Build tự động chạy

3. Release phiên bản:

   git tag v1.0.0
   git push origin v1.0.0
   

   → Docker Build và Deploy tự động chạy

Troubleshooting

Workflow không chạy

• Kiểm tra Gitea Runner đã được cấu hình đúng
• Kiểm tra quyền của repository và runner

Docker Build thất bại

• Kiểm tra thông tin đăng nhập registry
• Kiểm tra quyền truy cập vào registry

Deploy thất bại

• Kiểm tra kết nối đến VPS
• Kiểm tra Docker đã được cài đặt trên VPS
• Kiểm tra các biến môi trường đã được cấu hình đúng