feat: implement complete CI/CD with base image strategy
- Add Woodpecker pipeline with base image support - Separate base image build (.woodpecker-base.yml) from app build (.woodpecker.yml) - Implement build/push separation in application pipeline - Create Docker base image with Python 3.11, Node.js 20, and bun - Update Dockerfile to use pre-built base image for faster builds - Remove GitHub Actions (not needed, using Woodpecker) - Fix Docker contexts and paths for new structure - Update docker-compose.yml build contexts - Fix rxconfig.py DB path for container environment - Add ArgoCD application manifests for staging/production - Create comprehensive documentation: - docs/WOODPECKER_CI_CD.md (CI/CD guide) - docs/BASE_IMAGE_MANAGEMENT.md (Base image management) - helm/peikarband/argocd/README.md (ArgoCD deployment) Benefits: - Build time: 8-10min → 2-3min (60-70% faster) - Better reliability (no repeated npm/bun downloads) - Separation of concerns (base vs application builds) - Full pipeline: check → build → push → verify → notify - Complete deployment automation with Helm + ArgoCD Pipeline stages: 1. check-base-image: Verify base image availability 2. build-image: Build application (no push) 3. push-image: Push with multi-tags (latest, sha, branch) 4. verify-push: Verify successful push 5. notify: Success/failure notifications Base image can be rebuilt via: - Manual trigger in Woodpecker UI - Auto trigger when Dockerfile.base changes
This commit is contained in:
Ehsan.Asadi
586
docs/WOODPECKER_CI_CD.md
Normal file
586
docs/WOODPECKER_CI_CD.md
Normal file
@@ -0,0 +1,586 @@
|
||||
# Woodpecker CI/CD Documentation
|
||||
|
||||
این مستند راهنمای کامل برای راهاندازی و استفاده از Woodpecker CI/CD pipeline برای پروژه Peikarband است.
|
||||
|
||||
## نمای کلی Pipeline
|
||||
|
||||
Pipeline ما شامل 8 مرحله اصلی است:
|
||||
|
||||
```
|
||||
1. Code Quality & Linting
|
||||
├── flake8 (Python linting)
|
||||
├── black (Code formatting check)
|
||||
├── isort (Import sorting)
|
||||
└── mypy (Type checking)
|
||||
|
||||
2. Security Scanning
|
||||
├── bandit (Security vulnerability scan)
|
||||
└── safety (Dependency vulnerability check)
|
||||
|
||||
3. Testing
|
||||
└── pytest (Unit & Integration tests with coverage)
|
||||
|
||||
4. Helm Validation
|
||||
├── helm lint
|
||||
└── helm template
|
||||
|
||||
5. Docker Build & Push
|
||||
└── Multi-platform build with caching
|
||||
|
||||
6. Deploy to Staging
|
||||
└── Auto-deploy on main/develop branches
|
||||
|
||||
7. Deploy to Production
|
||||
└── Manual trigger on version tags (v*)
|
||||
|
||||
8. Notifications
|
||||
└── Success/Failure notifications
|
||||
```
|
||||
|
||||
## تنظیمات Secrets
|
||||
|
||||
برای اجرای کامل pipeline، باید secrets زیر را در Woodpecker تنظیم کنید:
|
||||
|
||||
### 1. Registry Secrets (الزامی برای Build)
|
||||
|
||||
```bash
|
||||
HARBOR_USERNAME=admin
|
||||
HARBOR_PASSWORD=your_harbor_password
|
||||
```
|
||||
|
||||
**نحوه تنظیم در Woodpecker UI:**
|
||||
1. رفتن به Repository Settings
|
||||
2. کلیک روی "Secrets"
|
||||
3. اضافه کردن secret جدید:
|
||||
- Name: `HARBOR_USERNAME`
|
||||
- Value: `admin`
|
||||
- Events: `push, tag`
|
||||
4. تکرار برای `HARBOR_PASSWORD`
|
||||
|
||||
### 2. Kubernetes Secrets (الزامی برای Deployment)
|
||||
|
||||
#### Staging Environment
|
||||
|
||||
```bash
|
||||
# Generate base64 encoded kubeconfig
|
||||
cat ~/.kube/config-staging | base64 -w 0 > kubeconfig-staging-base64.txt
|
||||
|
||||
# Add to Woodpecker as secret
|
||||
KUBECONFIG_STAGING=<content_of_kubeconfig-staging-base64.txt>
|
||||
```
|
||||
|
||||
#### Production Environment
|
||||
|
||||
```bash
|
||||
# Generate base64 encoded kubeconfig
|
||||
cat ~/.kube/config-production | base64 -w 0 > kubeconfig-production-base64.txt
|
||||
|
||||
# Add to Woodpecker as secret
|
||||
KUBECONFIG_PRODUCTION=<content_of_kubeconfig-production-base64.txt>
|
||||
```
|
||||
|
||||
**⚠️ نکات امنیتی:**
|
||||
- هرگز kubeconfig را در Git commit نکنید
|
||||
- از RBAC برای محدود کردن دسترسی kubeconfig استفاده کنید
|
||||
- بهطور منظم kubeconfig را rotate کنید
|
||||
- فقط namespace های staging و production دسترسی داشته باشند
|
||||
|
||||
### 3. Optional: ArgoCD Integration
|
||||
|
||||
اگر میخواهید از ArgoCD برای deployment استفاده کنید:
|
||||
|
||||
```bash
|
||||
ARGOCD_SERVER=argocd.peikarband.ir
|
||||
ARGOCD_AUTH_TOKEN=your_argocd_token
|
||||
```
|
||||
|
||||
## Branch Strategy
|
||||
|
||||
Pipeline بر اساس branch و event متفاوت رفتار میکند:
|
||||
|
||||
### Pull Request (PR)
|
||||
|
||||
```yaml
|
||||
Stages: Lint + Test + Security + Helm Lint
|
||||
Skip: Build, Deploy
|
||||
Purpose: Code quality validation
|
||||
```
|
||||
|
||||
**مثال:**
|
||||
|
||||
```bash
|
||||
# Create PR
|
||||
git checkout -b feature/new-feature
|
||||
git push origin feature/new-feature
|
||||
# Open PR in GitLab/GitHub -> Pipeline runs automatically
|
||||
```
|
||||
|
||||
### Main Branch (Push)
|
||||
|
||||
```yaml
|
||||
Stages: All stages
|
||||
Deploy: Staging (automatic)
|
||||
Tags: latest, main-<sha>, <sha>
|
||||
```
|
||||
|
||||
**مثال:**
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git merge feature/new-feature
|
||||
git push origin main
|
||||
# -> Automatic: Test -> Build -> Deploy to Staging
|
||||
```
|
||||
|
||||
### Develop Branch (Push)
|
||||
|
||||
```yaml
|
||||
Stages: All stages
|
||||
Deploy: Staging (automatic)
|
||||
Tags: develop, develop-<sha>, <sha>
|
||||
```
|
||||
|
||||
**مثال:**
|
||||
|
||||
```bash
|
||||
git checkout develop
|
||||
git push origin develop
|
||||
# -> Automatic: Test -> Build -> Deploy to Staging
|
||||
```
|
||||
|
||||
### Version Tags (Production)
|
||||
|
||||
```yaml
|
||||
Stages: All stages
|
||||
Deploy: Production (automatic)
|
||||
Tags: latest, v1.2.3, <sha>
|
||||
```
|
||||
|
||||
**مثال:**
|
||||
|
||||
```bash
|
||||
# Create and push version tag
|
||||
git checkout main
|
||||
git tag -a v1.0.0 -m "Release v1.0.0"
|
||||
git push origin v1.0.0
|
||||
# -> Automatic: Test -> Build -> Deploy to Production
|
||||
```
|
||||
|
||||
## Pipeline Triggers
|
||||
|
||||
### Automatic Triggers
|
||||
|
||||
1. **Push به branch:**
|
||||
```bash
|
||||
git push origin main # Trigger full pipeline + deploy staging
|
||||
git push origin develop # Trigger full pipeline + deploy staging
|
||||
git push origin feature/* # No trigger (manual only)
|
||||
```
|
||||
|
||||
2. **Tag push:**
|
||||
```bash
|
||||
git push origin v1.0.0 # Trigger full pipeline + deploy production
|
||||
```
|
||||
|
||||
3. **Pull Request:**
|
||||
```bash
|
||||
# Any PR -> Triggers lint/test/security only
|
||||
```
|
||||
|
||||
### Manual Triggers
|
||||
|
||||
در Woodpecker UI:
|
||||
1. رفتن به Repository
|
||||
2. کلیک روی "Pipelines"
|
||||
3. کلیک روی "New Pipeline"
|
||||
4. انتخاب branch/commit
|
||||
5. کلیک روی "Start"
|
||||
|
||||
## Docker Image Tagging
|
||||
|
||||
Pipeline بهطور خودکار images را با تگهای مختلف میسازد:
|
||||
|
||||
### Main Branch
|
||||
|
||||
```
|
||||
hub.peikarband.ir/peikarband/landing:latest
|
||||
hub.peikarband.ir/peikarband/landing:main
|
||||
hub.peikarband.ir/peikarband/landing:a1b2c3d4 # commit SHA
|
||||
```
|
||||
|
||||
### Develop Branch
|
||||
|
||||
```
|
||||
hub.peikarband.ir/peikarband/landing:develop
|
||||
hub.peikarband.ir/peikarband/landing:develop-a1b2c3d4
|
||||
hub.peikarband.ir/peikarband/landing:a1b2c3d4
|
||||
```
|
||||
|
||||
### Version Tags
|
||||
|
||||
```
|
||||
hub.peikarband.ir/peikarband/landing:latest
|
||||
hub.peikarband.ir/peikarband/landing:v1.0.0
|
||||
hub.peikarband.ir/peikarband/landing:a1b2c3d4
|
||||
```
|
||||
|
||||
## Deployment Process
|
||||
|
||||
### Staging Deployment
|
||||
|
||||
**Trigger:** هر push به `main` یا `develop`
|
||||
|
||||
**فرایند:**
|
||||
1. Tests pass
|
||||
2. Build Docker image
|
||||
3. Push to registry with tag `<branch>-<sha>`
|
||||
4. Helm upgrade to `staging` namespace
|
||||
5. Wait for rollout (timeout: 5 minutes)
|
||||
6. Show pod status
|
||||
|
||||
**Rollback:**
|
||||
|
||||
```bash
|
||||
# List helm releases
|
||||
helm list -n staging
|
||||
|
||||
# Rollback to previous version
|
||||
helm rollback peikarband-staging -n staging
|
||||
|
||||
# Or rollback to specific revision
|
||||
helm rollback peikarband-staging 5 -n staging
|
||||
```
|
||||
|
||||
### Production Deployment
|
||||
|
||||
**Trigger:** Push tag با pattern `v*` (مثل `v1.0.0`)
|
||||
|
||||
**فرایند:**
|
||||
1. Tests pass
|
||||
2. Build Docker image
|
||||
3. Push to registry with tags `latest`, `v1.0.0`, `<sha>`
|
||||
4. Helm upgrade to `production` namespace with production values
|
||||
5. Wait for rollout (timeout: 10 minutes)
|
||||
6. Verify deployment
|
||||
7. Show pod status
|
||||
|
||||
**Rollback:**
|
||||
|
||||
```bash
|
||||
# Check current status
|
||||
kubectl get pods -n production
|
||||
|
||||
# Rollback via Helm
|
||||
helm rollback peikarband -n production
|
||||
|
||||
# Or rollback via kubectl
|
||||
kubectl rollout undo deployment/peikarband -n production
|
||||
|
||||
# Check rollout status
|
||||
kubectl rollout status deployment/peikarband -n production
|
||||
```
|
||||
|
||||
## Monitoring Pipeline
|
||||
|
||||
### Via Woodpecker UI
|
||||
|
||||
1. رفتن به: `https://woodpecker.peikarband.ir` (یا آدرس Woodpecker شما)
|
||||
2. انتخاب repository
|
||||
3. مشاهده لیست pipeline runs
|
||||
4. کلیک روی یک run برای مشاهده جزئیات
|
||||
|
||||
### Via CLI
|
||||
|
||||
```bash
|
||||
# Install Woodpecker CLI
|
||||
curl -L https://github.com/woodpecker-ci/woodpecker/releases/latest/download/woodpecker-cli_linux_amd64.tar.gz | tar xz
|
||||
sudo mv woodpecker-cli /usr/local/bin/
|
||||
|
||||
# Configure
|
||||
export WOODPECKER_SERVER=https://woodpecker.peikarband.ir
|
||||
export WOODPECKER_TOKEN=your_token
|
||||
|
||||
# List pipelines
|
||||
woodpecker pipeline ls
|
||||
|
||||
# Show pipeline info
|
||||
woodpecker pipeline info <number>
|
||||
|
||||
# Show logs
|
||||
woodpecker pipeline logs <number>
|
||||
|
||||
# Approve waiting pipeline
|
||||
woodpecker pipeline approve <number>
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Pipeline Fails at Lint Stage
|
||||
|
||||
**مشکل:** کد formatting یا linting مشکل دارد
|
||||
|
||||
**راهحل:**
|
||||
|
||||
```bash
|
||||
cd peikarband
|
||||
|
||||
# Fix formatting
|
||||
black src/
|
||||
isort src/
|
||||
|
||||
# Check linting
|
||||
flake8 src/
|
||||
|
||||
# Commit fixes
|
||||
git add .
|
||||
git commit -m "fix: code formatting and linting"
|
||||
git push
|
||||
```
|
||||
|
||||
### Pipeline Fails at Test Stage
|
||||
|
||||
**مشکل:** تستها fail میشوند
|
||||
|
||||
**راهحل:**
|
||||
|
||||
```bash
|
||||
cd peikarband
|
||||
|
||||
# Run tests locally
|
||||
pytest tests/ -v
|
||||
|
||||
# Run with coverage
|
||||
pytest tests/ -v --cov=src
|
||||
|
||||
# Fix tests and re-run
|
||||
git add .
|
||||
git commit -m "fix: failing tests"
|
||||
git push
|
||||
```
|
||||
|
||||
### Pipeline Fails at Docker Build
|
||||
|
||||
**مشکل:** Docker build error
|
||||
|
||||
**راهحل:**
|
||||
|
||||
```bash
|
||||
# Test build locally
|
||||
docker build -f docker/Dockerfile -t test:latest .
|
||||
|
||||
# Check Dockerfile syntax
|
||||
docker build --check -f docker/Dockerfile .
|
||||
|
||||
# Check build context
|
||||
ls -la peikarband/
|
||||
|
||||
# Common issues:
|
||||
# 1. Missing files in context
|
||||
# 2. COPY path wrong
|
||||
# 3. Build args missing
|
||||
```
|
||||
|
||||
### Pipeline Fails at Deployment
|
||||
|
||||
**مشکل:** Helm deployment fail
|
||||
|
||||
**راهحل:**
|
||||
|
||||
```bash
|
||||
# Test Helm locally
|
||||
helm lint helm/peikarband
|
||||
helm template peikarband helm/peikarband -f helm/peikarband/values-staging.yaml
|
||||
|
||||
# Check kubectl access
|
||||
kubectl get pods -n staging
|
||||
|
||||
# Check secrets
|
||||
kubectl get secrets -n staging
|
||||
|
||||
# Check image pull
|
||||
kubectl describe pod <pod-name> -n staging
|
||||
```
|
||||
|
||||
### Secret Not Found Error
|
||||
|
||||
**مشکل:** `Secret not found: HARBOR_USERNAME`
|
||||
|
||||
**راهحل:**
|
||||
1. رفتن به Woodpecker UI > Repository > Settings > Secrets
|
||||
2. بررسی که secret با نام درست اضافه شده
|
||||
3. بررسی که secret برای event درست (push, tag, etc.) فعال است
|
||||
4. بررسی که secret برای branch درست در دسترس است
|
||||
|
||||
### Kubeconfig Invalid
|
||||
|
||||
**مشکل:** `Unable to connect to the server`
|
||||
|
||||
**راهحل:**
|
||||
|
||||
```bash
|
||||
# Test kubeconfig locally
|
||||
export KUBECONFIG=/path/to/your/kubeconfig
|
||||
kubectl get pods
|
||||
|
||||
# Re-encode kubeconfig
|
||||
cat ~/.kube/config | base64 -w 0
|
||||
|
||||
# Update secret in Woodpecker
|
||||
# Copy new base64 string to KUBECONFIG_STAGING or KUBECONFIG_PRODUCTION
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Build Cache
|
||||
|
||||
Pipeline از Docker layer caching استفاده میکند:
|
||||
|
||||
```yaml
|
||||
cache_from: type=registry,ref=hub.peikarband.ir/peikarband/landing:buildcache
|
||||
cache_to: type=inline
|
||||
```
|
||||
|
||||
**بهینهسازی بیشتر:**
|
||||
|
||||
1. **Dependencies Caching:** requirements.txt را قبل از کد اصلی COPY کنید
|
||||
2. **Multi-stage Build:** از multi-stage builds استفاده کنید
|
||||
3. **Parallel Stages:** مراحل مستقل را parallel اجرا کنید
|
||||
|
||||
### Pipeline Duration
|
||||
|
||||
زمان تقریبی هر stage:
|
||||
|
||||
```
|
||||
Lint stages: ~1-2 minutes
|
||||
Security scan: ~2-3 minutes
|
||||
Tests: ~3-5 minutes
|
||||
Helm validation: ~30 seconds
|
||||
Docker build: ~5-10 minutes (first time), ~2-3 minutes (cached)
|
||||
Deployment: ~2-5 minutes
|
||||
Total: ~15-30 minutes (full pipeline)
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Commit Messages
|
||||
|
||||
از conventional commits استفاده کنید:
|
||||
|
||||
```bash
|
||||
feat: add new feature
|
||||
fix: bug fix
|
||||
docs: documentation changes
|
||||
style: formatting changes
|
||||
refactor: code refactoring
|
||||
test: test changes
|
||||
chore: build/CI changes
|
||||
```
|
||||
|
||||
### 2. Version Tagging
|
||||
|
||||
```bash
|
||||
# Semantic versioning
|
||||
v1.0.0 # Major.Minor.Patch
|
||||
v1.0.1 # Patch release
|
||||
v1.1.0 # Minor release
|
||||
v2.0.0 # Major release
|
||||
|
||||
# Pre-release versions
|
||||
v1.0.0-rc.1 # Release candidate
|
||||
v1.0.0-beta.1 # Beta release
|
||||
v1.0.0-alpha.1 # Alpha release
|
||||
```
|
||||
|
||||
### 3. Feature Branches
|
||||
|
||||
```bash
|
||||
# Create feature branch
|
||||
git checkout -b feature/user-authentication
|
||||
# ... make changes ...
|
||||
git add .
|
||||
git commit -m "feat: add user authentication"
|
||||
git push origin feature/user-authentication
|
||||
|
||||
# Create PR
|
||||
# After approval, merge to develop
|
||||
git checkout develop
|
||||
git merge feature/user-authentication
|
||||
git push origin develop
|
||||
# -> Triggers pipeline + deploy to staging
|
||||
|
||||
# After testing in staging, merge to main
|
||||
git checkout main
|
||||
git merge develop
|
||||
git push origin main
|
||||
# -> Triggers pipeline + deploy to staging
|
||||
|
||||
# Create production release
|
||||
git tag -a v1.1.0 -m "Release v1.1.0: Add user authentication"
|
||||
git push origin v1.1.0
|
||||
# -> Triggers pipeline + deploy to production
|
||||
```
|
||||
|
||||
### 4. Hotfix Process
|
||||
|
||||
```bash
|
||||
# Create hotfix branch from main
|
||||
git checkout -b hotfix/critical-bug main
|
||||
|
||||
# Fix the bug
|
||||
git add .
|
||||
git commit -m "fix: critical security vulnerability"
|
||||
|
||||
# Merge to main
|
||||
git checkout main
|
||||
git merge hotfix/critical-bug
|
||||
|
||||
# Tag immediately
|
||||
git tag -a v1.0.1 -m "Hotfix v1.0.1: Security patch"
|
||||
git push origin main v1.0.1
|
||||
# -> Triggers pipeline + deploy to production
|
||||
|
||||
# Merge back to develop
|
||||
git checkout develop
|
||||
git merge hotfix/critical-bug
|
||||
git push origin develop
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Available in Pipeline
|
||||
|
||||
```bash
|
||||
CI=woodpecker # Always set
|
||||
CI_REPO=username/peikarband # Repository name
|
||||
CI_REPO_LINK=https://git.../peikarband # Repository URL
|
||||
CI_COMMIT_SHA=a1b2c3d4e5f6... # Full commit hash
|
||||
CI_COMMIT_BRANCH=main # Branch name
|
||||
CI_COMMIT_TAG=v1.0.0 # Tag (if triggered by tag)
|
||||
CI_COMMIT_MESSAGE=feat: new feature # Commit message
|
||||
CI_PIPELINE_CREATED=2024-01-01T... # Pipeline creation time
|
||||
CI_PIPELINE_NUMBER=123 # Pipeline number
|
||||
```
|
||||
|
||||
### Usage Example
|
||||
|
||||
```bash
|
||||
# In pipeline step
|
||||
echo "Building commit ${CI_COMMIT_SHA:0:8} from branch ${CI_COMMIT_BRANCH}"
|
||||
echo "Image tag: hub.peikarband.ir/peikarband/landing:${CI_COMMIT_SHA:0:8}"
|
||||
```
|
||||
|
||||
## Support & Contact
|
||||
|
||||
برای مشکلات و سوالات:
|
||||
- **Documentation:** این فایل
|
||||
- **Issues:** GitLab/GitHub Issues
|
||||
- **Team Contact:** dev@peikarband.ir
|
||||
|
||||
## مراجع
|
||||
|
||||
- [Woodpecker CI Documentation](https://woodpecker-ci.org/docs/intro)
|
||||
- [Docker Build Best Practices](https://docs.docker.com/develop/dev-best-practices/)
|
||||
- [Helm Documentation](https://helm.sh/docs/)
|
||||
- [Kubernetes Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
|
||||
|
||||
Reference in New Issue
Block a user