feat: Setup CI/CD infrastructure with Go, Frontend, and Docker workflows (#22)
## Summary This PR sets up the complete CI/CD infrastructure for the Chat Switchboard project, implementing automated testing, linting, building, and Docker containerization. ## Changes ### CI/CD Workflows 1. **`.gitea/workflows/backend.yml`** - Backend CI pipeline - Automated Go module initialization - Test execution with coverage reporting - Code linting with golangci-lint - Binary compilation with version tags - Artifact upload for debugging 2. **`.gitea/workflows/frontend.yml`** - Frontend CI pipeline - JavaScript linting with ESLint - CSS validation with Prettier - Standalone HTML build via build.sh - HTML structure validation - Build artifact management 3. **`.gitea/workflows/docker.yml`** - Docker CI pipeline - Backend container building and testing - Frontend container building - Automatic image tagging on tags/branches - Registry push on main branch - Multi-arch manifest creation ### Docker Configuration - `server/Dockerfile` - Multi-stage Go backend container with health checks - `Dockerfile.frontend` - Nginx frontend container with gzip compression - `nginx.conf` - Optimized nginx config with security headers ### Dependencies - `server/go.mod` - Initialized Go module with Gin and godotenv ### Documentation - `docs/CICD_SETUP.md` - Comprehensive CI/CD documentation ## Features - ✅ Auto-trigger on push/PR to main/develop - ✅ Test coverage reporting - ✅ Code quality checks (golangci-lint, ESLint) - ✅ Build artifact management (7-day retention) - ✅ Semantic versioning support (v* tags) - ✅ Multi-stage Docker builds - ✅ Container health checks - ✅ Security headers in nginx - ✅ Gzip compression - ✅ Non-root container execution ## Testing The workflows will automatically run on this PR. Once merged, all future PRs and pushes to main/develop will trigger the appropriate CI checks. ## Acceptance Criteria - ✅ All PRs run CI checks - ✅ Docker images auto-build on tags - ✅ Standalone build generates on each commit ## Next Steps (Manual) 1. Merge this PR to `main` 2. Create `develop` branch: `git checkout main && git checkout -b develop && git push origin develop` 3. Configure branch protection in Gitea (Settings → Branches → Add protection rule for main/develop) 4. Test with a sample PR to verify CI runs ## Breaking Changes None. This is purely infrastructure setup with no impact on existing functionality. Reviewed-on: xcaliber/chat-switchboard#22
This commit is contained in:
235
docs/CICD_SETUP.md
Normal file
235
docs/CICD_SETUP.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# CI/CD Infrastructure Setup - Chat Switchboard
|
||||
|
||||
This document outlines the CI/CD infrastructure that has been set up for the Chat Switchboard project.
|
||||
|
||||
## Overview
|
||||
|
||||
The project uses Gitea Actions for CI/CD, configured with three primary workflows:
|
||||
|
||||
1. **Backend CI** - Go backend testing, linting, and building
|
||||
2. **Frontend CI** - JavaScript/CSS linting and standalone build
|
||||
3. **Docker CI** - Container image building and publishing
|
||||
|
||||
## Workflows
|
||||
|
||||
### Backend CI (`.gitea/workflows/backend.yml`)
|
||||
|
||||
**Triggers:**
|
||||
- Push to `server/**` or `go.mod` on `main` or `develop`
|
||||
- Pull requests targeting `main` or `develop`
|
||||
|
||||
**Jobs:**
|
||||
1. **test** - Runs Go tests with coverage
|
||||
2. **lint** - Runs golangci-lint
|
||||
3. **build** - Compiles Go binary (requires test & lint to pass)
|
||||
|
||||
**Features:**
|
||||
- Auto-initializes Go module if missing
|
||||
- Uploads coverage reports to Codecov
|
||||
- Builds with version tags from git
|
||||
- Caches Go modules for faster builds
|
||||
|
||||
### Frontend CI (`.gitea/workflows/frontend.yml`)
|
||||
|
||||
**Triggers:**
|
||||
- Push to `frontend/**`, `src/**`, or `build.sh` on `main` or `develop`
|
||||
- Pull requests targeting `main` or `develop`
|
||||
|
||||
**Jobs:**
|
||||
1. **lint** - ESLint for JavaScript, Prettier for CSS
|
||||
2. **build** - Generates standalone HTML via build.sh
|
||||
3. **validate** - Validates HTML structure
|
||||
|
||||
**Features:**
|
||||
- Auto-generates eslint config if missing
|
||||
- Validates build output structure
|
||||
- Uploads standalone build as artifact
|
||||
|
||||
### Docker CI (`.gitea/workflows/docker.yml`)
|
||||
|
||||
**Triggers:**
|
||||
- Push to `main` or `develop` with Dockerfile changes
|
||||
- Pull requests targeting `main` or `develop`
|
||||
- Tag creation (`v*` pattern)
|
||||
|
||||
**Jobs:**
|
||||
1. **build** - Builds and tests containers
|
||||
2. **metadata** - Generates image tags
|
||||
3. **push** - Pushes images to registry
|
||||
4. **manifest** - Creates multi-arch manifests (main branch only)
|
||||
|
||||
**Features:**
|
||||
- Multi-stage Docker builds
|
||||
- Cache from GitHub Actions cache
|
||||
- Auto-tagging based on git refs
|
||||
- Security headers in nginx config
|
||||
- Health checks for containers
|
||||
|
||||
## Docker Images
|
||||
|
||||
### Backend Image
|
||||
|
||||
**Location:** `server/Dockerfile`
|
||||
|
||||
**Build Process:**
|
||||
1. Multi-stage build (builder → runtime)
|
||||
2. Auto-generates version from git tags
|
||||
3. Non-root user for security
|
||||
4. Health check endpoint
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
docker build -t chat-switchboard-backend ./server
|
||||
docker run -p 8080:8080 chat-switchboard-backend
|
||||
```
|
||||
|
||||
### Frontend Image
|
||||
|
||||
**Location:** `Dockerfile.frontend`
|
||||
|
||||
**Build Process:**
|
||||
1. Builds standalone HTML in builder stage
|
||||
2. Serves via nginx in production stage
|
||||
3. Gzip compression enabled
|
||||
4. Security headers added
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
docker build -t chat-switchboard-frontend -f Dockerfile.frontend .
|
||||
docker run -p 80:80 chat-switchboard-frontend
|
||||
```
|
||||
|
||||
## Branch Strategy
|
||||
|
||||
**Branches:**
|
||||
- `main` - Production branch
|
||||
- `develop` - Development branch (to be created)
|
||||
- Feature branches - Created from `develop`
|
||||
|
||||
**Workflow:**
|
||||
1. Create feature branch from `develop`
|
||||
2. Make changes and push
|
||||
3. Create PR to `develop`
|
||||
4. CI runs automatically on PR
|
||||
5. Merge to `develop` after review
|
||||
6. Create PR from `develop` to `main` for releases
|
||||
|
||||
## Getting Started
|
||||
|
||||
### For Developers
|
||||
|
||||
1. **Clone the repository**
|
||||
```bash
|
||||
git clone https://git.gobha.me/xcaliber/chat-switchboard.git
|
||||
cd chat-switchboard
|
||||
```
|
||||
|
||||
2. **Create feature branch**
|
||||
```bash
|
||||
git checkout -b feature/my-feature develop
|
||||
```
|
||||
|
||||
3. **Make changes and test locally**
|
||||
```bash
|
||||
# Backend
|
||||
cd server && go test ./...
|
||||
|
||||
# Frontend
|
||||
./build.sh
|
||||
```
|
||||
|
||||
4. **Push and create PR**
|
||||
```bash
|
||||
git push origin feature/my-feature
|
||||
# Create PR via web interface
|
||||
```
|
||||
|
||||
5. **CI will automatically run on your PR**
|
||||
|
||||
### For Maintainers
|
||||
|
||||
1. **Branch Protection (requires admin access)**
|
||||
- Go to Repository Settings → Branches
|
||||
- Add protection rule for `main` and `develop`
|
||||
- Require pull request reviews
|
||||
- Require status checks to pass
|
||||
- Select required CI checks
|
||||
|
||||
2. **Creating a Release**
|
||||
```bash
|
||||
# Create tag
|
||||
git tag -a v1.0.0 -m "Release v1.0.0"
|
||||
git push origin v1.0.0
|
||||
```
|
||||
|
||||
This will:
|
||||
- Trigger Docker CI
|
||||
- Build and push images with version tag
|
||||
- Update `latest` tag on main branch
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Docker Registry
|
||||
|
||||
Images are pushed to GitHub Container Registry:
|
||||
- Backend: `ghcr.io/xcaliber/chat-switchboard-backend`
|
||||
- Frontend: `ghcr.io/xcaliber/chat-switchboard-frontend`
|
||||
|
||||
Authentication is handled via `GITHUB_TOKEN`.
|
||||
|
||||
## Monitoring & Logs
|
||||
|
||||
### Docker Health Checks
|
||||
|
||||
Both containers include health checks:
|
||||
- Backend: `/health` endpoint
|
||||
- Frontend: HTTP check on port 80
|
||||
|
||||
### CI Status
|
||||
|
||||
Check CI status in:
|
||||
- Gitea repository → Actions tab
|
||||
- Pull request checks section
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**1. Go module initialization fails**
|
||||
```bash
|
||||
cd server
|
||||
go mod init git.gobha.me/xcaliber/chat-switchboard
|
||||
go mod tidy
|
||||
```
|
||||
|
||||
**2. Frontend build fails**
|
||||
```bash
|
||||
chmod +x build.sh
|
||||
./build.sh
|
||||
```
|
||||
|
||||
**3. Docker build fails**
|
||||
```bash
|
||||
# Check if Dockerfile exists
|
||||
ls -la server/Dockerfile
|
||||
ls -la Dockerfile.frontend
|
||||
|
||||
# Build manually
|
||||
docker build -t test ./server
|
||||
```
|
||||
|
||||
### Viewing CI Logs
|
||||
|
||||
1. Go to Repository → Actions
|
||||
2. Select the workflow run
|
||||
3. View job logs for details
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Planned improvements:
|
||||
- [ ] Semantic versioning automation
|
||||
- [ ] Automatic changelog generation
|
||||
- [ ] Integration tests in CI
|
||||
- [ ] Security scanning (Trivy, Snyk)
|
||||
- [ ] Performance benchmarks
|
||||
- [ ] Multi-arch builds (arm64/amd64)
|
||||
Reference in New Issue
Block a user