diff --git a/CICD.md b/CICD.md new file mode 100644 index 0000000..b0c4a24 --- /dev/null +++ b/CICD.md @@ -0,0 +1,491 @@ +# DevOps CI/CD Pipeline Summary + +This document provides an overview of the continuous integration and deployment (CI/CD) pipeline for the GlyphDiff SvelteKit project using Gitea Actions. + +## 📋 Table of Contents + +- [Pipeline Overview](#pipeline-overview) +- [Quick Reference](#quick-reference) +- [Architecture](#architecture) +- [Workflow Details](#workflow-details) +- [Deployment Strategy](#deployment-strategy) +- [Monitoring & Observability](#monitoring--observability) +- [Self-Hosted Runner Setup](#self-hosted-runner-setup) +- [Getting Started](#getting-started) + +## Pipeline Overview + +### DevOps Solution: Gitea Actions CI/CD Pipeline + +#### Architecture Overview + +The GlyphDiff project uses Gitea Actions (GitHub Actions compatible) for CI/CD on a self-hosted Gitea instance. The pipeline is designed to be: + +- **Automated**: Every push and PR triggers validation workflows +- **Fast**: Caching strategies optimize execution time +- **Reliable**: Multiple quality gates ensure code quality +- **Secure**: Secrets management and least-privilege access +- **Observable**: Artifacts and logs for debugging + +#### CI/CD Pipeline Stages + +1. **Source**: Trigger on commits, PRs, or manual dispatch +2. **Lint**: Code quality checks (oxlint, dprint) +3. **Test**: Type checking and E2E tests (Playwright) +4. **Build**: Production build verification +5. **Deploy**: Automated deployment (optional/template) + +#### Quality Gates + +- ✅ All linting checks must pass +- ✅ Type checking must have no errors +- ✅ All E2E tests must pass +- ✅ Production build must complete successfully +- ✅ Health check on preview server must succeed + +## Quick Reference + +| Workflow | Purpose | Trigger | Duration | +| ------------ | ---------------------- | ------------ | -------- | +| `lint.yml` | Code quality checks | Push/PR | 30-60s | +| `test.yml` | Type check & E2E tests | Push/PR | 3-6min | +| `build.yml` | Production build | Push/PR | 1-3min | +| `deploy.yml` | Deployment to prod | Push to main | 2-10min | + +### Branch Strategy + +| Branch | Workflows | Deployment | +| ----------- | ----------------- | ------------- | +| `main` | All workflows | Yes (on push) | +| `develop` | Lint, Test, Build | No | +| `feature/*` | Lint, Test | No | + +### Environment Configuration + +| Environment | Branch | Purpose | +| ----------- | --------- | ------------------- | +| Production | `main` | Live deployment | +| Development | `develop` | Integration testing | + +## Architecture + +### Pipeline Flowchart + +``` +┌─────────────┐ +│ Push/PR │ +└──────┬──────┘ + │ + ├──────────────┬──────────────┬──────────────┐ + ▼ ▼ ▼ ▼ +┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ +│ Lint │ │ Test │ │ Build │ │ Deploy │ +│ (30s) │ │ (3-6min) │ │ (1-3min) │ │ (2-10min) │ +└───────────┘ └───────────┘ └───────────┘ └───────────┘ + │ │ │ │ + │ │ │ │ + └──────────────┴──────────────┴──────────────┘ + │ + ▼ + ┌────────────────┐ + │ All Pass ✅ │ + └────────────────┘ +``` + +### Technology Stack + +| Component | Technology | Version | +| ------------------- | ------------- | ------- | +| **CI/CD Platform** | Gitea Actions | Latest | +| **Runner** | act_runner | 0.2.11+ | +| **Package Manager** | Yarn | Latest | +| **Runtime** | Node.js | 20.x | +| **Framework** | SvelteKit | 2.49.1+ | +| **Build Tool** | Vite | 7.2.6+ | +| **Linter** | oxlint | 1.35.0+ | +| **Formatter** | dprint | 0.50.2+ | +| **E2E Testing** | Playwright | 1.57.0+ | +| **TypeScript** | TypeScript | 5.9.3+ | +| **Git Hooks** | lefthook | 2.0.13+ | + +## Workflow Details + +### 1. Lint Workflow (`lint.yml`) + +**Purpose**: Ensure code quality and formatting standards + +**Checks**: + +- `oxlint` - Fast JavaScript/TypeScript linting +- `dprint check` - Code formatting verification + +**Triggers**: + +- Push to `main`, `develop`, `feature/*` +- Pull requests to `main`, `develop` +- Manual dispatch + +**Features**: + +- Yarn caching for fast dependency installation +- Concurrency control (cancels in-progress runs) +- ~30-60 second execution time + +**Quality Gate**: + +```yaml +Exit on: Failure +Prevents: Build and deployment +``` + +--- + +### 2. Test Workflow (`test.yml`) + +**Purpose**: Verify type safety and application behavior + +**Jobs**: + +#### Type Check Job + +- `tsc --noEmit` - TypeScript type checking +- `svelte-check --threshold warning` - Svelte component type checking + +#### E2E Tests Job + +- Install Playwright browsers with system dependencies +- Run E2E tests using Playwright +- Upload test report artifacts (7-day retention) +- Upload screenshots on test failure + +**Triggers**: Same as lint workflow + +**Artifacts**: + +- `playwright-report` - HTML test report +- `playwright-screenshots` - Screenshots from failed tests + +**Quality Gates**: + +```yaml +Exit on: Failure +Prevents: Build and deployment +``` + +--- + +### 3. Build Workflow (`build.yml`) + +**Purpose**: Verify production build success + +**Steps**: + +1. Setup Node.js v20 with Yarn caching +2. Install dependencies with `--frozen-lockfile` +3. Run `svelte-kit sync` to prepare SvelteKit +4. Build with `NODE_ENV=production` +5. Upload build artifacts (`.svelte-kit/output`, `.svelte-kit/build`) +6. Run preview server and health check + +**Triggers**: + +- Push to `main` or `develop` +- Pull requests to `main` or `develop` +- Manual dispatch + +**Artifacts**: + +- `build-artifacts` - Compiled SvelteKit output (7-day retention) + +**Quality Gate**: + +```yaml +Exit on: Failure +Prevents: Deployment +``` + +--- + +### 4. Deploy Workflow (`deploy.yml`) + +**Purpose**: Automated deployment to production + +**Current State**: Template configuration (requires customization) + +**Pre-deployment Checks**: + +- Must pass linting workflow +- Must pass testing workflow +- Must pass build workflow + +**Triggers**: + +- Push to `main` branch +- Manual dispatch with environment selection (staging/production) + +**Deployment Options** (uncomment one): + +1. **Docker Container Registry** + - Build and push Docker image + - Supports GitHub Actions cache + - Requires: `REGISTRY_URL`, `REGISTRY_USERNAME`, `REGISTRY_PASSWORD` + +2. **SSH Deployment** + - Deploy to server via SSH + - Supports custom deployment scripts + - Requires: `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_SSH_KEY` + +3. **Vercel** + - Deploy to Vercel platform + - Zero-configuration deployment + - Requires: `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID` + +**Features**: + +- Environment-based deployment (staging/production) +- Post-deployment health check (template) +- Prevents concurrent deployments (concurrency group) + +## Deployment Strategy + +**Strategy**: Manual Trigger with Environment Gates (Template) + +### Description + +The deployment workflow is designed as a template that can be customized based on your deployment needs. It requires manual approval and successful completion of all CI checks before deployment. + +### Pros + +- ✅ Flexibility to choose deployment method +- ✅ Multiple deployment options (Docker, SSH, Vercel) +- ✅ Environment separation (staging/production) +- ✅ Pre-deployment gates ensure quality +- ✅ Prevents concurrent deployments + +### Cons + +- ⚠️ Requires manual configuration +- ⚠️ No automated rollback mechanism (can be added) +- ⚠️ No blue-green deployment (can be implemented) + +### Recommended Future Enhancements + +1. **Automated Rollback**: Detect failures and auto-rollback +2. **Blue-Green Deployment**: Zero downtime deployment +3. **Canary Releases**: Gradual traffic rollout +4. **Slack Notifications**: Notify team on deployment status +5. **Deployment Dashboard**: Visual deployment tracking + +## Monitoring & Observability + +### Metrics + +**Workflow Execution**: + +- Success/failure rates +- Execution duration +- Resource usage (CPU, memory) +- Queue times + +**Application Metrics** (to be added): + +- Response times +- Error rates +- Throughput +- Custom business metrics + +### Logs + +**Workflow Logs**: + +- Available in Gitea Actions UI +- Retention: 90 days (configurable) +- Searchable and filterable + +**Application Logs** (to be added): + +- Centralized log aggregation (ELK, Loki) +- Structured logging (JSON) +- Log levels (debug, info, warn, error) + +### Alerts + +**Current**: + +- Email notifications on workflow failure (Gitea feature) + +**Recommended**: + +- Slack/Mattermost integration +- PagerDuty for critical failures +- Health check alerts (uptime monitoring) + +## Self-Hosted Runner Setup + +### Runner Architecture + +``` +┌─────────────────────────────────────┐ +│ Gitea Instance │ +│ (Actions Enabled, Self-Hosted) │ +└──────────────┬──────────────────────┘ + │ + │ HTTPS/Webhook + │ + ▼ +┌─────────────────────────────────────┐ +│ act_runner (Linux/Ubuntu) │ +│ - Systemd service │ +│ - Labels: ubuntu-latest │ +│ - Docker enabled │ +└──────────────┬──────────────────────┘ + │ + │ Executes workflows + │ + ▼ +┌─────────────────────────────────────┐ +│ Docker Containers │ +│ - Node.js 20 container │ +│ - Playwright browsers │ +│ - Build environment │ +└─────────────────────────────────────┘ +``` + +### Installation Steps + +#### 1. Install act_runner + +```bash +wget -O /usr/local/bin/act_runner \ + https://gitea.com/act_runner/releases/download/v0.2.11/act_runner-0.2.11-linux-amd64 +chmod +x /usr/local/bin/act_runner +``` + +#### 2. Register Runner + +```bash +act_runner register \ + --instance https://your-gitea-instance.com \ + --token YOUR_TOKEN \ + --name "linux-runner-1" \ + --labels ubuntu-latest,linux,docker \ + --no-interactive +``` + +#### 3. Configure as Service + +```bash +sudo tee /etc/systemd/system/gitea-runner.service > /dev/null <