dance-lessons-coach/doc/local-ci-cd-testing.md

# Local CI/CD Testing Guide

This guide explains how to test the CI/CD pipeline locally without requiring a Gitea instance.

## Overview

The local CI/CD testing allows you to:
- Test the entire build process locally
- Simulate version bumping based on commit conventions
- Build Docker images with the correct version tags
- Test the container before pushing to production

## Available Testing Methods

### 1. Interactive Local Testing Script

**File:** `scripts/test-local-ci-cd.sh`

**What it does:**
- Installs dependencies
- Generates Swagger documentation
- Runs compilation and tests
- Builds binaries
- Simulates version bumping
- Provides Docker build instructions
- Optionally builds and runs Docker container

**Usage:**
```bash
./scripts/test-local-ci-cd.sh
```

**Features:**
- Interactive prompts for Docker build and run
- Automatic endpoint testing
- Clear instructions for each step
- Version-aware Docker image tagging

### 2. Local CI/CD Workflow

**File:** `.gitea/workflows/test-local-ci-cd.yaml`

**What it does:**
- Simulates the CI/CD pipeline in a workflow format
- Provides detailed instructions for local Docker builds
- Shows version bump simulation
- Lists all test results

**Usage:**
This workflow can be triggered manually or on test/feature branches.

### 3. Workflow Validation

**File:** `scripts/cicd/validate-workflow.sh`

**What it does:**
- Validates YAML syntax
- Checks required workflow fields
- Validates job structure
- Verifies Arcodange-specific configurations

**Usage:**
```bash
./scripts/cicd/validate-workflow.sh
```

## Step-by-Step Local Testing

### 1. Run the Interactive Script

```bash
cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach
./scripts/test-local-ci-cd.sh
```

### 2. Follow the Prompts

The script will guide you through:
- Environment setup
- Dependency installation
- Code compilation and testing
- Binary building
- Version bump simulation
- Docker build options

### 3. Docker Testing (Optional)

If you choose to build the Docker image:

```bash
# Build with current version
docker build -t dance-lessons-coach:$CURRENT_VERSION .

# Tag as latest
docker tag dance-lessons-coach:$CURRENT_VERSION dance-lessons-coach:latest

# Check if port is available
./scripts/check-port.sh 8080 8081 8082

# Run the container (use available port)
docker run -d -p 8080:8080 --name dance-lessons-coach-test dance-lessons-coach:$CURRENT_VERSION
# Or use alternative port if 8080 is in use
docker run -d -p 8081:8080 --name dance-lessons-coach-test dance-lessons-coach:$CURRENT_VERSION

# Branch-specific naming (recommended for multiple branches)
BRANCH=$(git rev-parse --abbrev-ref HEAD | tr '/' '-')
docker run -d -p 8080:8080 --name "dance-lessons-coach-$BRANCH" dance-lessons-coach:$CURRENT_VERSION
```

**Port Checking:**
The script automatically checks if port 8080 is available and suggests alternatives.

**Container Management:**
- Automatically removes existing containers with the same name
- Uses branch-based naming to avoid conflicts
- Supports multiple branch testing simultaneously

### 4. Test the Container

```bash
# Health check
curl http://localhost:8080/api/health

# Greet endpoint
curl http://localhost:8080/api/v1/greet/YourName

# Swagger UI
open http://localhost:8080/swagger/
```

### 5. Clean Up

```bash
# Stop and remove container (generic)
docker stop dance-lessons-coach-test
docker rm dance-lessons-coach-test

# Stop and remove branch-specific container
BRANCH=$(git rev-parse --abbrev-ref HEAD | tr '/' '-')
docker stop "dance-lessons-coach-$BRANCH"
docker rm "dance-lessons-coach-$BRANCH"

# Remove all test containers
docker stop $(docker ps -aq --filter "name=dance-lessons-coach")
docker rm $(docker ps -aq --filter "name=dance-lessons-coach")

# Remove images (optional)
docker rmi dance-lessons-coach:$CURRENT_VERSION
docker rmi dance-lessons-coach:latest
```

**Cleanup Tips:**
- Use `docker ps -a` to see all containers
- Use `docker images` to see all images
- Use `docker system prune` to clean up unused objects

## Version Management

The local testing respects the same version conventions as the production CI/CD:

- **feat:** commits → MINOR version bump
- **fix:** commits → PATCH version bump  
- **BREAKING CHANGE:** → MAJOR version bump
- Other commits → No automatic bump

**Manual version bump:**
```bash
# Bump patch version
./scripts/version-bump.sh patch

# Bump minor version  
./scripts/version-bump.sh minor

# Bump major version
./scripts/version-bump.sh major
```

## Docker Build Optimization

The Dockerfile is optimized to:
- Only install swag if swagger.json doesn't exist
- Reuse existing swagger.json from CI/CD workflow
- Generate documentation only when needed

This means:
- **Local builds:** Will generate swagger docs if missing
- **CI/CD builds:** Will reuse existing swagger.json
- **Production builds:** Most efficient path

## Testing Different Scenarios

### Test Version Bumping

```bash
# Make a feature commit
git commit -m "feat: add new feature"
./scripts/test-local-ci-cd.sh  # Will show MINOR bump suggestion

# Make a fix commit
git commit -m "fix: resolve issue"
./scripts/test-local-ci-cd.sh  # Will show PATCH bump suggestion
```

### Test Without Docker

```bash
# Run tests without Docker
./scripts/test-local-ci-cd.sh
# Answer 'n' when asked about Docker build
```

### Test Specific Components

```bash
# Just build and test
go build ./...
go test ./... -cover

# Just generate swagger docs
cd pkg/server && go generate

# Just build binaries
./scripts/build.sh

# Check port availability
./scripts/check-port.sh 8080 8081 8082
```

## Production Deployment

When you're ready to deploy:

1. **Commit your changes** with appropriate commit message
2. **Push to main branch** to trigger production CI/CD
3. **Monitor the workflow** in Gitea Actions
4. **Verify the Docker image** in Gitea Container Registry

```bash
# Example production deployment
git add .
git commit -m "feat: add new API endpoint"
git push origin main
```

## Troubleshooting

### Port Conflicts

```bash
# Check what's using port 8080
./scripts/check-port.sh 8080

# Find and kill process on port 8080
kill -9 $(lsof -ti :8080)

# Use alternative port
docker run -d -p 8081:8080 --name dance-lessons-coach-test dance-lessons-coach:$CURRENT_VERSION
```

### Docker Build Issues

```bash
# Clean build
docker system prune -a --volumes
rm -rf pkg/server/docs/
./scripts/test-local-ci-cd.sh
```

### Dependency Issues

```bash
# Clean and reinstall
go clean -cache
go mod tidy
./scripts/test-local-ci-cd.sh
```

### Test Failures

```bash
# Run specific test
go test ./pkg/greet/ -v

# Run with race detector
go test ./... -race
```

## Best Practices

1. **Test locally first** before pushing to CI/CD
2. **Use commit conventions** for automatic version bumping
3. **Test Docker images** before production deployment
4. **Clean up containers** after testing
5. **Monitor CI/CD logs** for any issues

## Summary

The local CI/CD testing provides:
- ✅ Full build pipeline simulation
- ✅ Version-aware Docker builds
- ✅ Interactive testing experience
- ✅ Production-like environment
- ✅ Easy troubleshooting

Use these tools to ensure your changes work correctly before deploying to production!