[CLAUDE] Phase5 prep: production infra + deploy scripts + 4 guides + FE refresh token
Backend production infra:
- Packages: Serilog.Sinks.File, HealthChecks.EntityFrameworkCore (RateLimiting built-in .NET 10)
- appsettings.Production.json MOI: placeholder __SET_VIA_SECRETS__, AllowedOrigins, Serilog File sink rolling daily retention 30d, RateLimit config
- appsettings.json + Development.json: them Serilog WriteTo Console
- Program.cs REWRITE:
- Serilog ReadFrom.Configuration (prod file / dev console)
- Rate limiter: policy auth-login 5/min/IP (AuthController.Login) + GlobalLimiter 300/min/IP
- Health checks: /health/live liveness (empty predicate) + /health/ready DB probe (AddDbContextCheck)
- HSTS production 1 year
- CORS origins from config AllowedOrigins (default dev 2 localhost)
- AuthController.Login gắn [EnableRateLimiting("auth-login")]
Deploy scripts:
- scripts/deploy-iis.ps1: stop pool → backup current → clean+extract artifact → start pool → health check loop 30s timeout → rollback instruction if fail
- scripts/backup-sql.ps1: BACKUP DATABASE voi INIT+COMPRESSION+CHECKSUM + retention 30d auto cleanup
- .gitea/workflows/deploy.yml MOI: 4 job build BE (Windows) + build 2 FE (Ubuntu, pin .nvmrc 20) + deploy-iis qua WinRM PSSession (secrets IIS_HOST/USER/PASSWORD/JWT_SECRET/DB_CONNECTION)
Docs guides MOI (4 file):
- deployment-iis.md: prereqs (IIS features, Hosting Bundle, SQL, WinRM) + setup lan dau (app pool, 3 site, HTTPS win-acme, user-secrets) + deploy hang ngay (CI/CD + manual) + rollback + monitoring + troubleshooting + SPA web.config sample
- cicd.md: pipeline overview 4 job, secrets setup, runner Windows+Ubuntu, branch strategy, build optimizations, common CI/CD issues
- security-checklist.md: OWASP top 10 2021 mapping voi status + pre go-live checklist + incident response
- runbook.md: daily ops (health/logs), restart/rollback, DB backup/restore/migration revert, user management (reset password, unlock, disable), monitoring (CPU/disk/connection pool), deployment checklist, common gotcha
Frontend refresh token (ca 2 app fe-admin + fe-user):
- lib/api.ts REWRITE: them REFRESH_KEY, axios response interceptor 401 → POST /auth/refresh → retry request goc. Queue pattern cho nhieu request song song chi 1 refresh call chay. Skip retry /auth/login + /auth/refresh tranh infinite loop. _retry flag tren original config.
- contexts/AuthContext.tsx: luu+xoa REFRESH_KEY trong login/logout
E2E verified:
- GET /health/live → 200 Healthy
- GET /health/ready → 200 Healthy (DB probe)
- Rate limit flood 7 POST /auth/login → #1-5 HTTP 400 (cred sai) + #6-7 HTTP 429 Too Many Requests ✅
- TS check fe-admin + fe-user → pass
- dotnet build → 0 errors
Docs updates:
- docs/STATUS.md: Phase 5 prep done, next Phase 5 deploy production + Phase 5.1 security hardening, cumulative stats 8 commits
- docs/HANDOFF.md: phase table them Phase 5 prep row, file tree update voi guides + scripts + workflows, git state commit 8
- docs/changelog/migration-todos.md: tick Phase 5 prep items (12 items done) + Phase 5 deploy items remaining + Phase 5.1 security hardening list
- docs/changelog/sessions/2026-04-21-1530-phase5-prep.md: session log chi tiet
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
pqhuy1987
123
docs/guides/cicd.md
Normal file
123
docs/guides/cicd.md
Normal file
@ -0,0 +1,123 @@
|
||||
# CI/CD — Gitea Actions
|
||||
|
||||
> Automation pipeline từ push → build → test → deploy. Chạy trên Windows self-hosted runner (cần cho WinRM + Word COM).
|
||||
|
||||
## 1. Pipeline overview
|
||||
|
||||
```
|
||||
Push main
|
||||
├─ build-backend (Windows runner)
|
||||
│ └─ dotnet restore/build/publish → artifact "backend-api"
|
||||
├─ build-fe-admin (Ubuntu runner)
|
||||
│ └─ npm ci + npm run build → artifact "fe-admin-dist"
|
||||
├─ build-fe-user (Ubuntu runner)
|
||||
│ └─ npm ci + npm run build → artifact "fe-user-dist"
|
||||
└─ deploy-iis (Windows runner) — chỉ khi ref = main
|
||||
├─ download 3 artifact
|
||||
├─ Compress-Archive → 3 zip
|
||||
├─ Copy-Item via PSSession WinRM → target server
|
||||
└─ Invoke-Command → scripts/deploy-iis.ps1
|
||||
```
|
||||
|
||||
File spec: `.gitea/workflows/deploy.yml` (đã có).
|
||||
|
||||
## 2. Secrets setup
|
||||
|
||||
Trong Gitea repo → Settings → Actions → Secrets, thêm:
|
||||
|
||||
| Secret | Ví dụ | Mô tả |
|
||||
|---|---|---|
|
||||
| `IIS_HOST` | `10.0.0.100` | Hostname/IP target IIS server |
|
||||
| `IIS_USER` | `solution-erp\deploy` | Windows user có admin + WinRM enabled |
|
||||
| `IIS_PASSWORD` | `...` | Password tương ứng |
|
||||
| `JWT_SECRET` | 64+ random chars | Pass vào user-secrets khi deploy |
|
||||
| `DB_CONNECTION` | `Server=.;Database=SolutionErp;...` | ConnectionString production |
|
||||
|
||||
**KHÔNG** echo secret ra log (Gitea auto-mask nhưng vẫn cẩn thận).
|
||||
|
||||
## 3. Runner setup
|
||||
|
||||
### Windows self-hosted runner (cho build BE + deploy)
|
||||
|
||||
Trên Windows VM:
|
||||
```powershell
|
||||
# Download Gitea Act runner
|
||||
# https://gitea.com/gitea/act_runner/releases
|
||||
.\act_runner register --instance https://gitea.yourcorp.local --token <token>
|
||||
.\act_runner daemon
|
||||
```
|
||||
|
||||
Prereqs trên runner:
|
||||
- .NET 10 SDK
|
||||
- Git 2.40+
|
||||
- PowerShell 7+
|
||||
- Node 20 (cho test/build nếu cần BE test với FE proxy)
|
||||
- WinRM client: `winrm quickconfig`
|
||||
- Test connectivity: `Test-NetConnection $env:IIS_HOST -Port 5985`
|
||||
|
||||
### Ubuntu runner (cho build FE)
|
||||
|
||||
```bash
|
||||
# Docker runner
|
||||
docker run -d --name gitea-runner \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
-e GITEA_INSTANCE_URL=https://gitea.yourcorp.local \
|
||||
-e GITEA_RUNNER_REGISTRATION_TOKEN=<token> \
|
||||
gitea/act_runner:latest
|
||||
```
|
||||
|
||||
Prereqs:
|
||||
- Node 20 (qua `actions/setup-node` — KHÔNG dùng latest, xem [`gotchas.md #5`](../gotchas.md))
|
||||
- npm cache
|
||||
|
||||
## 4. Branch strategy + trigger
|
||||
|
||||
| Branch | Trigger | Action |
|
||||
|---|---|---|
|
||||
| `main` | push | full build + deploy production |
|
||||
| `staging` | push | full build + deploy staging (nếu có) |
|
||||
| `feature/*` | push | chỉ build + test, không deploy |
|
||||
| PR merge | merge_request | build + test, optional auto-merge nếu pass |
|
||||
| Manual | `workflow_dispatch` | re-deploy current main |
|
||||
|
||||
## 5. Build optimizations
|
||||
|
||||
- Node cache qua `actions/setup-node@v4` với `cache: 'npm'` + `cache-dependency-path`
|
||||
- NuGet cache qua `actions/cache@v4` path `~/.nuget/packages` (Windows: `%USERPROFILE%\.nuget\packages`)
|
||||
- Parallel build 3 job FE/BE độc lập
|
||||
|
||||
## 6. Pre-commit checks (Phase 5.1 — khi có thời gian)
|
||||
|
||||
Thêm job `verify` chạy trước deploy:
|
||||
- `dotnet format --verify-no-changes`
|
||||
- `dotnet test` (khi có unit test)
|
||||
- `npm run lint`
|
||||
- `npm run build` (both FE)
|
||||
|
||||
## 7. Rollback qua CI/CD
|
||||
|
||||
1. Gitea repo → Actions → tìm run cũ đã deploy thành công
|
||||
2. Re-run job đó (re-runner download artifact cũ + deploy lại)
|
||||
|
||||
Hoặc revert git:
|
||||
```bash
|
||||
git revert <bad-commit>
|
||||
git push
|
||||
```
|
||||
|
||||
## 8. Common CI/CD issues
|
||||
|
||||
| Problem | Fix |
|
||||
|---|---|
|
||||
| Node build fail trên CI nhưng OK local | Pin Node 20 qua `.nvmrc` (gotcha #5) |
|
||||
| WinRM timeout | Check firewall port 5985/5986, increase `Test-NetConnection -TimeoutSec` |
|
||||
| NuGet restore slow | Add cache action |
|
||||
| Artifact size > 100MB | Exclude `bin/`, `obj/`, `node_modules/` trong `dotnet publish` |
|
||||
| Deploy không thấy file mới | App pool chưa restart — xem log `scripts/deploy-iis.ps1` xem Stop+Start có chạy không |
|
||||
|
||||
## 9. Liên quan
|
||||
|
||||
- [`deployment-iis.md`](deployment-iis.md) — IIS setup chi tiết
|
||||
- [`runbook.md`](runbook.md) — operations
|
||||
- `.gitea/workflows/deploy.yml` — workflow YAML
|
||||
- `scripts/deploy-iis.ps1` — deploy script
|
||||
Reference in New Issue
Block a user