Gabriel Radureau
b309fa1f0d
Some checks failed
CI/CD Pipeline / CI Pipeline (push) Has been cancelled
- Moved all documentation files from doc/ to documentation/ - Removed empty doc/ directory - Single unified location for all project documentation - Includes BDD guide, CI/CD testing guide, version management guide Refs: #documentation, #organization, #cleanup
305 lines
7.1 KiB
Markdown
305 lines
7.1 KiB
Markdown
# 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! |