📁 refactor: consolidate doc/ into documentation/ directory
Some checks failed
CI/CD Pipeline / CI Pipeline (push) Has been cancelled
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
This commit is contained in:
305
documentation/local-ci-cd-testing.md
Normal file
305
documentation/local-ci-cd-testing.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user