core/docs/CICD_SETUP.md

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:

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:

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

   git clone https://git.gobha.me/xcaliber/chat-switchboard.git
   cd chat-switchboard
   

2. Create feature branch

   git checkout -b feature/my-feature develop
   

3. Make changes and test locally

   # Backend
   cd server && go test ./...
   
   # Frontend
   ./build.sh
   

4. Push and create PR

   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

   # 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

cd server
go mod init git.gobha.me/xcaliber/chat-switchboard
go mod tidy

2. Frontend build fails

chmod +x build.sh
./build.sh

3. Docker build fails

# 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)