📝 docs: update comprehensive documentation and project infrastructure
Documentation Updates: - Enhanced AGENTS.md with user authentication details - Updated README.md with authentication API documentation - Added CONTRIBUTING.md guidelines for BDD testing - Version management guide improvements - Local CI/CD testing documentation Project Infrastructure: - Updated .gitignore for new file patterns - Enhanced git hooks documentation - YAML linting configuration - Script improvements and organization - Configuration management updates API Enhancements: - Greet service integration with authentication - Server middleware for JWT validation - Telemetry improvements - Version management utilities Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
215
scripts/LOCAL_CI_GUIDE.md
Normal file
215
scripts/LOCAL_CI_GUIDE.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# Local CI/CD Testing Guide
|
||||
|
||||
This guide explains how to test the CI/CD pipeline locally using the available scripts.
|
||||
|
||||
## 📁 Available Scripts
|
||||
|
||||
### Core CI Scripts
|
||||
- `test-local-ci-cd.sh` - Complete local CI/CD simulation
|
||||
- `test-docker-cache.sh` - Test Docker build cache functionality
|
||||
- `ci-update-coverage-badge.sh` - Test coverage badge updates
|
||||
- `ci-version-bump.sh` - Test version bump logic
|
||||
|
||||
### Existing Test Scripts
|
||||
- `run-bdd-tests.sh` - Run BDD tests locally
|
||||
- `test-graceful-shutdown.sh` - Test graceful shutdown
|
||||
- `test-opentelemetry.sh` - Test OpenTelemetry integration
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### 1. Test Docker Build Cache
|
||||
```bash
|
||||
# Test the Docker cache functionality
|
||||
./scripts/test-docker-cache.sh
|
||||
|
||||
# This will:
|
||||
# 1. Calculate dependency hash (same as CI)
|
||||
# 2. Build Docker cache image
|
||||
# 3. Test commands in Docker
|
||||
# 4. Compare performance
|
||||
```
|
||||
|
||||
### 2. Full Local CI/CD Test
|
||||
```bash
|
||||
# Run complete local CI/CD simulation
|
||||
./scripts/test-local-ci-cd.sh
|
||||
|
||||
# This will:
|
||||
# 1. Install dependencies
|
||||
# 2. Generate Swagger docs
|
||||
# 3. Build and test code
|
||||
# 4. Build binaries
|
||||
# 5. Simulate version bump
|
||||
# 6. Optionally build Docker image
|
||||
```
|
||||
|
||||
### 3. Test Specific Components
|
||||
|
||||
#### Coverage Badge Updates
|
||||
```bash
|
||||
# Test coverage badge update logic
|
||||
./scripts/ci-update-coverage-badge.sh 75.5
|
||||
```
|
||||
|
||||
#### Version Bump Logic
|
||||
```bash
|
||||
# Test version bump with different commit messages
|
||||
./scripts/ci-version-bump.sh "✨ feat: add new feature"
|
||||
./scripts/ci-version-bump.sh "🐛 fix: resolve bug"
|
||||
./scripts/ci-version-bump.sh "Regular commit message"
|
||||
```
|
||||
|
||||
## 🐳 Docker Build Cache Testing
|
||||
|
||||
The Docker build cache system works by:
|
||||
|
||||
1. **Calculating dependency hash**: `sha256sum go.mod go.sum`
|
||||
2. **Building cache image**: Only when dependencies change
|
||||
3. **Using cached image**: For all subsequent CI runs
|
||||
|
||||
### Local Testing
|
||||
```bash
|
||||
# Build the cache image locally
|
||||
docker build -t dance-lessons-coach-build-cache -f Dockerfile.build .
|
||||
|
||||
# Test running commands in the cached environment
|
||||
docker run --rm -v "$(pwd):/workspace" -w /workspace \
|
||||
dance-lessons-coach-build-cache \
|
||||
go test ./... -cover
|
||||
```
|
||||
|
||||
### CI Integration
|
||||
The CI workflow automatically:
|
||||
- Calculates the same hash
|
||||
- Checks if image exists in registry
|
||||
- Builds new image only when needed
|
||||
- Uses cached image for all builds
|
||||
|
||||
## 🔄 CI/CD Workflow Simulation
|
||||
|
||||
To simulate the full CI/CD workflow locally:
|
||||
|
||||
```bash
|
||||
# 1. Run local CI tests
|
||||
./scripts/test-local-ci-cd.sh
|
||||
|
||||
# 2. When prompted, build Docker image
|
||||
# 3. Test the running container
|
||||
# 4. Verify all endpoints work
|
||||
|
||||
# 5. Test BDD scenarios
|
||||
./scripts/run-bdd-tests.sh
|
||||
|
||||
# 6. Test graceful shutdown
|
||||
./scripts/test-graceful-shutdown.sh
|
||||
|
||||
# 7. Test OpenTelemetry
|
||||
./scripts/test-opentelemetry.sh
|
||||
```
|
||||
|
||||
## 📊 Performance Comparison
|
||||
|
||||
### Without Docker Cache
|
||||
```
|
||||
First run: ~90 seconds
|
||||
Subsequent: ~90 seconds (no caching)
|
||||
```
|
||||
|
||||
### With Docker Cache
|
||||
```
|
||||
First run: ~120 seconds (build cache)
|
||||
Subsequent: ~30 seconds (use cache)
|
||||
Savings: ~60 seconds per run!
|
||||
```
|
||||
|
||||
## 🎯 Best Practices
|
||||
|
||||
1. **Test locally first**: Always run `test-local-ci-cd.sh` before pushing
|
||||
2. **Check Docker cache**: Run `test-docker-cache.sh` after dependency changes
|
||||
3. **Verify coverage**: Test coverage badge updates with different percentages
|
||||
4. **Test version bumps**: Verify version logic with different commit types
|
||||
5. **Clean up**: Remove test containers and images when done
|
||||
|
||||
## 🧪 Advanced Testing
|
||||
|
||||
### Test Race Conditions
|
||||
```bash
|
||||
# Simulate concurrent CI runs
|
||||
./scripts/ci-update-coverage-badge.sh 75.5 &
|
||||
./scripts/ci-update-coverage-badge.sh 75.5 &
|
||||
wait
|
||||
```
|
||||
|
||||
### Test Version Bump Scenarios
|
||||
```bash
|
||||
# Test all version bump scenarios
|
||||
echo "✨ feat: new feature" > /tmp/test_commit
|
||||
./scripts/ci-version-bump.sh "$(cat /tmp/test_commit)"
|
||||
|
||||
echo "🐛 fix: bug fix" > /tmp/test_commit
|
||||
./scripts/ci-version-bump.sh "$(cat /tmp/test_commit)"
|
||||
|
||||
echo "BREAKING CHANGE: major update" > /tmp/test_commit
|
||||
./scripts/ci-version-bump.sh "$(cat /tmp/test_commit)"
|
||||
```
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Docker Issues
|
||||
- **Permission denied**: Add user to docker group or use `sudo`
|
||||
- **Port conflicts**: Change test port or stop conflicting services
|
||||
- **Image not found**: Build the image first with `docker build`
|
||||
|
||||
### CI Script Issues
|
||||
- **Missing dependencies**: Install required tools (Go, Docker, etc.)
|
||||
- **Script permissions**: Run `chmod +x scripts/*.sh`
|
||||
- **Path issues**: Use full paths or correct working directory
|
||||
|
||||
### Performance Issues
|
||||
- **Slow Docker builds**: Use `--no-cache` for fresh builds
|
||||
- **Large images**: Check Dockerfile for unnecessary layers
|
||||
- **Memory issues**: Increase Docker resources in settings
|
||||
|
||||
## 📖 Reference
|
||||
|
||||
### Docker Commands
|
||||
```bash
|
||||
# List images
|
||||
docker images
|
||||
|
||||
# List containers
|
||||
docker ps -a
|
||||
|
||||
# Remove container
|
||||
docker rm <container_id>
|
||||
|
||||
# Remove image
|
||||
docker rmi <image_id>
|
||||
|
||||
# View logs
|
||||
docker logs <container_id>
|
||||
|
||||
# Exec into container
|
||||
docker exec -it <container_id> sh
|
||||
```
|
||||
|
||||
### CI Commands
|
||||
```bash
|
||||
# Run specific CI job
|
||||
act -j <job_name>
|
||||
|
||||
# Test workflow locally
|
||||
act
|
||||
|
||||
# Dry run (show what would run)
|
||||
act -n
|
||||
```
|
||||
|
||||
## 🎓 Learning Resources
|
||||
|
||||
- [Docker Documentation](https://docs.docker.com/)
|
||||
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
|
||||
- [Go Testing Documentation](https://pkg.go.dev/testing)
|
||||
- [CI/CD Best Practices](https://github.com/goldbergyoni/nodebestpractices)
|
||||
|
||||
This guide provides everything you need to test the CI/CD pipeline locally before pushing to the repository!
|
||||
Reference in New Issue
Block a user