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:**
```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)