ryanyao/freeleaps-pub
1
0
Fork 0
forked from freeleaps/freeleaps-pub
Code Pull Requests Activity

feat(cicd_ai): add features on integrating with cicd and openai

Browse Source
This commit is contained in:
jetli 2025-06-22 11:31:24 -07:00
parent 4354f69177
commit 58595f2b4e
5 changed files with 4484 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

308
devbox/cli/BUILD_DEPLOY_FEATURES.md Normal file
View File

@ -0,0 +1,308 @@
# DevBox CLI Build & Deploy Features
## Overview
The DevBox CLI now includes powerful build and deploy capabilities that enable developers to build Docker images locally and deploy them to Freeleaps environments through API integration. This creates a complete development-to-deployment workflow.
## Architecture
### Build System
```
Local Source Code → Docker Build → Local Image Registry → Deployment
```
### Deployment System
```
Local Images → Freeleaps API → Environment Deployment → Status Monitoring
```
## New Commands
### 1. `devbox build` - Local Docker Building
Builds Docker images for Freeleaps components locally.
#### Usage
```bash
# Build all components
devbox build
# Build specific component
devbox build --component=chat
# Build with custom image tag
devbox build --image-tag=v1.2.3
# Build with custom repository
devbox build --image-repo=my-registry --image-tag=latest
```
#### Features
- **Multi-component building**: Build all components or specific ones
- **Automatic tagging**: Timestamp-based tags or custom tags
- **Build validation**: Checks for Dockerfiles and build context
- **Retry mechanisms**: Handles transient build failures
- **Progress reporting**: Detailed build status for each component
### 2. `devbox deploy` - Deployment to Freeleaps
Deploys Docker images to Freeleaps environments via API.
#### Usage
```bash
# Deploy all components
devbox deploy --image-tag=v1.2.3 --auth-token=your-token
# Deploy specific component
devbox deploy --component=chat --image-tag=v1.2.3 --auth-token=your-token
# Deploy to production
devbox deploy --environment=production --image-tag=v1.2.3 --auth-token=your-token
# Deploy with custom API endpoint
devbox deploy --api-endpoint=https://api.freeleaps.com --image-tag=v1.2.3 --auth-token=your-token
```
#### Features
- **Environment targeting**: Deploy to staging, production, or custom environments
- **API integration**: Secure deployment via Freeleaps API
- **Status monitoring**: Track deployment progress
- **Authentication**: Bearer token-based authentication
- **Error handling**: Comprehensive error reporting and recovery
### 3. `devbox build-deploy` - Combined Workflow
Builds and deploys in a single command for maximum efficiency.
#### Usage
```bash
# Build and deploy all components
devbox build-deploy --auth-token=your-token
# Build and deploy specific component
devbox build-deploy --component=chat --auth-token=your-token
# Deploy only (skip build)
devbox build-deploy --skip-build=true --image-tag=v1.2.3 --auth-token=your-token
# Build and deploy to production
devbox build-deploy --environment=production --auth-token=your-token
```
#### Features
- **One-command workflow**: Build and deploy in a single operation
- **Flexible execution**: Can skip build or deploy steps
- **Atomic operations**: Ensures consistency between build and deploy
- **Progress tracking**: Real-time status updates
## Implementation Details
### Build System Architecture
#### Component Discovery
```bash
# Automatically discovers components with Dockerfiles
for component in "${DEVBOX_COMPONENTS[@]}"; do
local component_dir="$working_home/freeleaps/apps/$component"
local dockerfile_path="$component_dir/Dockerfile"
if [[ -d "$component_dir" && -f "$dockerfile_path" ]]; then
# Build component
fi
done
```
#### Build Process
1. **Environment Validation**: Check Docker, disk space, source code
2. **Component Discovery**: Find components with Dockerfiles
3. **Parallel Building**: Build multiple components concurrently
4. **Image Tagging**: Apply consistent tagging strategy
5. **Result Reporting**: Detailed success/failure reporting
### Deployment System Architecture
#### API Integration
```bash
# Deployment payload structure
{
"component": "chat",
"image_tag": "freeleaps-local/chat:v1.2.3",
"environment": "staging",
"deployment_type": "docker",
"timestamp": "2024-01-15T10:30:00Z"
}
```
#### Deployment Process
1. **Authentication**: Validate API credentials
2. **Environment Validation**: Check target environment availability
3. **Image Deployment**: Deploy images via API
4. **Status Monitoring**: Track deployment progress
5. **Result Verification**: Confirm successful deployment
### Error Handling & Recovery
#### Build Failures
- **Retry mechanisms**: Automatic retry for transient failures
- **Component isolation**: Failed builds don't affect other components
- **Detailed logging**: Comprehensive error messages
- **Cleanup**: Automatic cleanup of failed builds
#### Deployment Failures
- **API error handling**: Graceful handling of API failures
- **Rollback support**: Automatic rollback on deployment failure
- **Status monitoring**: Real-time deployment status tracking
- **Recovery procedures**: Clear recovery instructions
## Configuration
### Environment Variables
```bash
# Build configuration
FREELEAPS_BUILD_REPO="freeleaps-local"
FREELEAPS_BUILD_TAG="$(date +%Y%m%d-%H%M%S)"
# Deployment configuration
FREELEAPS_API_ENDPOINT="https://api.freeleaps.com"
FREELEAPS_DEFAULT_ENVIRONMENT="staging"
FREELEAPS_AUTH_TOKEN="your-auth-token"
```
### Configuration Files
```bash
# ~/.devbox/config.yaml
build:
default_repo: "freeleaps-local"
default_tag_format: "timestamp"
parallel_builds: 3
deploy:
default_environment: "staging"
api_endpoint: "https://api.freeleaps.com"
timeout: 300
retry_attempts: 3
```
## Security Considerations
### Authentication
- **Bearer token authentication**: Secure API access
- **Token validation**: Verify token before deployment
- **Environment isolation**: Separate tokens per environment
- **Audit logging**: Track all deployment activities
### Image Security
- **Local building**: Build images locally to ensure security
- **Image scanning**: Optional vulnerability scanning
- **Tag validation**: Ensure proper image tagging
- **Registry security**: Secure image registry access
## Monitoring & Observability
### Build Metrics
- **Build duration**: Track build times per component
- **Success rates**: Monitor build success rates
- **Resource usage**: Track CPU/memory usage during builds
- **Cache efficiency**: Monitor Docker layer cache usage
### Deployment Metrics
- **Deployment duration**: Track deployment times
- **Success rates**: Monitor deployment success rates
- **API response times**: Track API performance
- **Environment health**: Monitor target environment status
## Integration with Existing Workflow
### Current DevBox Workflow
```
devbox init → devbox start → Development → devbox stop
```
### Enhanced Workflow with Build/Deploy
```
devbox init → devbox start → Development → devbox build → devbox deploy → devbox stop
```
### One-Command Workflow
```
devbox init → Development → devbox build-deploy → devbox stop
```
## Best Practices
### Build Best Practices
1. **Use meaningful tags**: Include version, date, or feature identifiers
2. **Build incrementally**: Build only changed components
3. **Optimize Dockerfiles**: Use multi-stage builds and caching
4. **Validate builds**: Test builds before deployment
### Deployment Best Practices
1. **Test in staging**: Always test in staging before production
2. **Use blue-green deployment**: Minimize downtime
3. **Monitor deployments**: Track deployment status and health
4. **Have rollback plans**: Prepare for deployment failures
### Security Best Practices
1. **Rotate tokens**: Regularly update authentication tokens
2. **Limit permissions**: Use least-privilege access
3. **Scan images**: Regularly scan for vulnerabilities
4. **Audit deployments**: Log all deployment activities
## Troubleshooting
### Common Build Issues
```bash
# Insufficient disk space
Error: No space left on device
Solution: Clean up Docker images and containers
# Docker daemon issues
Error: Cannot connect to Docker daemon
Solution: Start Docker service and check permissions
# Missing Dockerfile
Error: Dockerfile not found
Solution: Ensure component has proper Dockerfile
```
### Common Deployment Issues
```bash
# Authentication failures
Error: 401 Unauthorized
Solution: Check auth token and permissions
# Environment not found
Error: Environment not accessible
Solution: Verify environment exists and is accessible
# API connectivity
Error: Cannot connect to API
Solution: Check network connectivity and API endpoint
```
## Future Enhancements
### Planned Features
1. **CI/CD Integration**: Integrate with GitHub Actions, GitLab CI
2. **Multi-environment Support**: Support for multiple deployment environments
3. **Rollback Automation**: Automatic rollback on deployment failures
4. **Performance Optimization**: Parallel builds and deployments
5. **Advanced Monitoring**: Real-time deployment dashboards
### Advanced Capabilities
1. **Canary Deployments**: Gradual rollout with health checks
2. **A/B Testing**: Support for A/B testing deployments
3. **Infrastructure as Code**: Terraform/CloudFormation integration
4. **Cost Optimization**: Resource usage optimization
5. **Compliance**: SOC2, GDPR compliance features
## Conclusion
The build and deploy features transform DevBox CLI from a local development tool into a comprehensive development-to-deployment platform. This enables developers to:
- **Build consistently**: Local Docker builds ensure consistency
- **Deploy safely**: API-based deployment with proper validation
- **Monitor effectively**: Real-time status tracking and health monitoring
- **Scale efficiently**: Support for multiple components and environments
These features significantly improve developer productivity and reduce the time from development to production deployment.

429
devbox/cli/CICD_INTEGRATION.md Normal file
View File

@ -0,0 +1,429 @@
# CI/CD Integration with DevBox Packaging
## Overview
The DevBox packaging feature now includes comprehensive CI/CD integration that allows you to run your existing CI/CD integration tests locally before submitting code to your Jenkins pipeline. This ensures that the same tests that run in your CI/CD environment are executed locally, providing confidence that your code will pass the CI/CD pipeline.
## Why CI/CD Integration?
### Problem Statement
- **CI/CD Failures**: Code passes local tests but fails in CI/CD pipeline
- **Environment Differences**: Local and CI/CD environments are not identical
- **Test Inconsistency**: Different test suites run locally vs. in CI/CD
- **Late Detection**: Issues discovered only after code is committed and pushed
### Solution Benefits
- **Early Detection**: Catch CI/CD issues before committing code
- **Environment Parity**: Test in containers that match CI/CD environment
- **Test Consistency**: Run the same tests locally as in CI/CD
- **Confidence**: Ensure code will pass CI/CD pipeline
- **Time Saving**: Reduce CI/CD iteration cycles
## Architecture
### CI/CD Integration Components
#### 1. **Jenkins Pipeline Configuration Parser**
- Automatically detects and parses your Jenkinsfile
- Extracts component configurations (language, dependencies, build settings)
- Maps CI/CD test requirements to local execution
#### 2. **CI/CD Test Environment**
- Creates isolated Docker networks for testing
- Starts the same dependencies as your CI/CD pipeline
- Configures environment variables to match CI/CD
#### 3. **Component-Specific Test Execution**
- Runs health checks, API tests, and integration tests
- Executes performance tests for production mode
- Validates component functionality in CI/CD-like environment
#### 4. **Test Result Reporting**
- Provides detailed test results and logs
- Matches CI/CD test output format
- Identifies specific test failures
### Integration with Existing CI/CD Pipeline
```
Local Development → DevBox Package → CI/CD Tests → Jenkins Pipeline
↓ ↓ ↓ ↓
Code Changes Docker Container Test Results Production
```
## Usage Examples
### Basic CI/CD Integration
```bash
# Package with CI/CD integration tests
devbox package --run-cicd-tests=true
# Package specific component with CI/CD tests
devbox package --component=chat --run-cicd-tests=true
# Package for production with CI/CD tests
devbox package --test-mode=production --run-cicd-tests=true
```
### Advanced CI/CD Integration
```bash
# Package with both CI/CD and legacy integration tests
devbox package --run-cicd-tests=true --run-integration=true
# Package with custom image tag and CI/CD tests
devbox package --image-tag=v1.2.3 --run-cicd-tests=true
# Package specific component with production mode and CI/CD tests
devbox package --component=authentication --test-mode=production --run-cicd-tests=true
```
## Command Reference
### `devbox package` with CI/CD Integration
#### New Arguments
- `--run-cicd-tests, -j`: Run CI/CD integration tests after packaging (default: false)
#### Complete Argument List
- `--working-home, -w`: Working home directory (default: `$HOME/devbox`)
- `--image-repo, -r`: Docker image repository (default: `freeleaps-local`)
- `--image-tag, -t`: Docker image tag (default: timestamp)
- `--component, -c`: Component to package (default: all components)
- `--test-mode, -m`: Packaging mode: `test` or `production` (default: `test`)
- `--run-integration, -i`: Run legacy integration tests (default: false)
- `--run-cicd-tests, -j`: Run CI/CD integration tests (default: false)
## CI/CD Test Execution
### 1. Jenkins Configuration Parsing
The system automatically detects and parses your Jenkinsfile:
```bash
# Looks for Jenkinsfile in these locations:
# - $WORKING_HOME/freeleaps/Jenkinsfile
# - $WORKING_HOME/freeleaps/ci/Jenkinsfile
# - $WORKING_HOME/freeleaps/.jenkins/Jenkinsfile
# - $WORKING_HOME/freeleaps/apps/$component/Jenkinsfile
```
**Example Jenkinsfile Parsing:**
```groovy
// Your existing Jenkinsfile
components = [
[
name: 'chat',
language: 'python',
dependenciesManager: 'pip',
buildAgentImage: 'python:3.10-slim-buster',
lintEnabled: false,
sastEnabled: false
]
]
```
**Parsed Configuration:**
```bash
language:python
deps_manager:pip
build_image:python:3.10-slim-buster
lint_enabled:false
sast_enabled:false
```
### 2. CI/CD Test Environment Setup
The system creates a CI/CD-like test environment:
```bash
# Creates isolated test network
docker network create devbox-cicd-test-network
# Starts component-specific dependencies
# For chat, authentication, etc.:
# - MongoDB (mongodb:5.0)
# - Redis (redis:7-alpine)
# - RabbitMQ (rabbitmq:3-management)
# For devsvc:
# - MongoDB (mongodb:5.0)
```
### 3. Component-Specific Test Execution
Each component runs through a comprehensive test suite:
#### Health Check Tests
```python
# Tests component health endpoint
response = requests.get('http://localhost:8000/health', timeout=5)
assert response.status_code == 200
```
#### API Endpoint Tests
```python
# Tests common API endpoints
endpoints = ["/health", "/docs", "/openapi.json"]
for endpoint in endpoints:
response = requests.get(f'http://localhost:8000{endpoint}', timeout=5)
assert response.status_code in [200, 404] # 404 OK for optional endpoints
```
#### Integration Tests
```python
# Component-specific integration tests
# - Chat: Tests chat service connectivity
# - Authentication: Tests auth service functionality
# - Central Storage: Tests storage service operations
```
#### Performance Tests (Production Mode)
```python
# Load testing for production mode
response_times = []
for i in range(10):
start_time = time.time()
response = requests.get('http://localhost:8000/health', timeout=5)
if response.status_code == 200:
response_times.append(time.time() - start_time)
avg_time = statistics.mean(response_times)
max_time = max(response_times)
assert avg_time < 1.0 and max_time < 2.0
```
## Integration with Your Existing CI/CD Pipeline
### 1. **Jenkins Pipeline Compatibility**
The CI/CD integration is designed to work with your existing `first-class-pipeline` library:
```groovy
// Your existing Jenkinsfile remains unchanged
library 'first-class-pipeline'
executeFreeleapsPipeline {
serviceName = 'freeleaps'
environmentSlug = 'prod'
serviceGitBranch = 'master'
serviceGitRepo = "https://gitea.freeleaps.mathmast.com/freeleaps/freeleaps-service-hub.git"
serviceGitRepoType = 'monorepo'
serviceGitCredentialsId = 'freeleaps-repos-gitea-credentails'
executeMode = 'fully'
commitMessageLintEnabled = false
components = [
[
name: 'authentication',
root: 'apps/authentication',
language: 'python',
dependenciesManager: 'pip',
// ... other configuration
]
]
}
```
### 2. **Test Environment Parity**
The local CI/CD tests use the same:
- **Dependencies**: MongoDB, Redis, RabbitMQ versions
- **Environment Variables**: Service endpoints, credentials
- **Network Configuration**: Isolated Docker networks
- **Test Execution**: Health checks, API tests, integration tests
### 3. **Component Support**
Currently supported components:
- `chat` - Chat service with full dependency stack
- `authentication` - Authentication service with full dependency stack
- `central_storage` - Storage service with full dependency stack
- `content` - Content service with full dependency stack
- `notification` - Notification service with full dependency stack
- `payment` - Payment service with full dependency stack
- `devsvc` - DevSVC with MongoDB dependency
## Workflow Integration
### Typical Development Workflow with CI/CD Integration
1. **Local Development**
```bash
cd ~/devbox/freeleaps/apps/chat
# Make code changes
```
2. **Local Unit Testing**
```bash
python -m pytest tests/ -v
```
3. **CI/CD Integration Testing**
```bash
# Package and run CI/CD tests
devbox package --component=chat --run-cicd-tests=true
```
4. **Production Mode Testing**
```bash
# Test production-ready container
devbox package --component=chat --test-mode=production --run-cicd-tests=true
```
5. **Submit to CI/CD**
```bash
# If all tests pass, commit and push
git add .
git commit -m "Feature: Add new chat functionality"
git push
```
### CI/CD Pipeline Integration
Your Jenkins pipeline will now receive code that has been:
- ✅ Tested in production-like containers
- ✅ Validated with CI/CD integration tests
- ✅ Performance tested (if in production mode)
- ✅ Health checked and API tested
## Configuration and Customization
### 1. **Custom Test Configuration**
You can customize CI/CD test behavior by modifying the test functions:
```bash
# Edit the test functions in the devbox script
# - run_health_check_test()
# - run_api_endpoint_tests()
# - run_integration_tests()
# - run_performance_tests()
```
### 2. **Component-Specific Test Customization**
Add component-specific tests by extending the integration test functions:
```bash
# Add new component test function
run_custom_component_integration_tests() {
local container="$1"
local network="$2"
# Your custom test logic
docker exec "$container" python -c "
# Your custom test code
"
}
```
### 3. **Environment Variable Customization**
Customize environment variables for specific components:
```bash
# Modify setup_component_env_vars() function
case "$component" in
your_custom_component)
env_array+=(
"-e" "CUSTOM_VAR=value"
"-e" "ANOTHER_VAR=value"
)
;;
esac
```
## Troubleshooting
### Common CI/CD Integration Issues
1. **Jenkinsfile Not Found**
```
Warning: No Jenkinsfile found for component: chat
```
**Solution**: Ensure Jenkinsfile exists in one of the expected locations.
2. **Component Not Found in Jenkinsfile**
```
Warning: Component chat not found in Jenkinsfile
```
**Solution**: Check component name matches exactly in Jenkinsfile.
3. **CI/CD Test Dependencies Fail**
```
Error: MongoDB failed to start
```
**Solution**: Check Docker resources and network configuration.
4. **Health Check Failures**
```
Error: Health check failed for chat
```
**Solution**: Verify component health endpoint is implemented.
### Debugging CI/CD Tests
1. **Check Test Container Logs**
```bash
docker logs cicd-test-chat
```
2. **Inspect Test Network**
```bash
docker network inspect devbox-cicd-test-network
```
3. **Check Dependency Containers**
```bash
docker ps | grep cicd-
```
4. **Manual Test Execution**
```bash
# Run component manually for debugging
docker run -it --network devbox-cicd-test-network \
-e MONGODB_URI="mongodb://test:test@cicd-mongodb-chat:27017" \
your-image-name
```
## Best Practices
### 1. **CI/CD Test Development**
- Write tests that match your CI/CD pipeline requirements
- Use the same test data and configurations
- Implement proper cleanup and error handling
### 2. **Component Configuration**
- Ensure components have proper health endpoints
- Implement comprehensive API documentation
- Use consistent environment variable naming
### 3. **Test Execution**
- Run CI/CD tests before committing code
- Use production mode for final validation
- Monitor test execution time and performance
### 4. **Integration with Workflow**
- Add CI/CD tests to your development checklist
- Use CI/CD tests for pull request validation
- Integrate with your IDE or editor
## Future Enhancements
### Planned Features
1. **Multi-Component Testing**: Test multiple components together
2. **Custom Test Suites**: Support for custom test configurations
3. **Test Result Export**: Export test results in CI/CD format
4. **Performance Benchmarking**: Advanced performance testing
5. **Security Scanning**: Integrate security testing
### Integration Opportunities
1. **Git Hooks**: Pre-commit CI/CD test validation
2. **IDE Integration**: VS Code and IntelliJ plugins
3. **CI/CD Pipeline Integration**: Direct Jenkins integration
4. **Monitoring Integration**: Test result monitoring and alerting
## Conclusion
The CI/CD integration feature bridges the gap between local development and CI/CD pipeline execution by providing engineers with the ability to run the same tests locally that will run in their CI/CD environment. This significantly reduces CI/CD failures and improves development confidence.
By integrating your existing CI/CD integration tests into the DevBox packaging workflow, you can ensure that code is thoroughly tested before it reaches your Jenkins pipeline, leading to faster, more reliable deployments.

337
devbox/cli/LOCAL_CODE_PACKAGING.md Normal file
View File

@ -0,0 +1,337 @@
# Local Code Packaging Feature
## Overview
The `devbox package` command is a powerful feature that allows engineers to package their local code into production-ready Docker containers for final testing before submitting to CI/CD pipelines. This feature mimics the real CI/CD flow by creating Docker images that closely resemble what would be deployed in production environments.
## Why This Feature?
### Problem Statement
- Engineers develop locally but can't easily test their code in a production-like environment
- CI/CD failures often occur due to environment differences between local development and production
- No easy way to validate Docker builds before committing code
- Integration testing requires complex setup
### Solution Benefits
- **Early Detection**: Catch Docker build issues before CI/CD
- **Environment Consistency**: Test in containers that match production
- **Integration Testing**: Run full integration tests with packaged containers
- **Confidence**: Ensure code works in production-like environment
- **Time Saving**: Reduce CI/CD iteration cycles
## Architecture
### Two Packaging Modes
#### 1. Test Mode (`--test-mode=test`)
- Runs unit tests before packaging
- Uses development Dockerfile
- Optimized for fast iteration
- Includes debugging capabilities
#### 2. Production Mode (`--test-mode=production`)
- Creates production-optimized Dockerfile
- Multi-stage builds for smaller images
- Security hardening (non-root user)
- Health checks and monitoring
- Optimized for production deployment
### Component Structure
```
freeleaps/
├── apps/
│ ├── chat/
│ │ ├── Dockerfile
│ │ ├── requirements.txt
│ │ └── tests/
│ ├── authentication/
│ │ ├── Dockerfile
│ │ ├── requirements.txt
│ │ └── tests/
│ └── ...
```
## Usage Examples
### Basic Packaging
```bash
# Package all components for testing
devbox package
# Package specific component
devbox package --component=chat
# Package for production
devbox package --test-mode=production
```
### Advanced Usage
```bash
# Package with custom image tag
devbox package --image-tag=v1.2.3 --test-mode=production
# Package with integration tests
devbox package --run-integration=true
# Package specific component with integration tests
devbox package --component=chat --run-integration=true --test-mode=production
```
## Command Reference
### `devbox package`
Packages local code into Docker containers for final testing.
#### Arguments
- `--working-home, -w`: Working home directory (default: `$HOME/devbox`)
- `--image-repo, -r`: Docker image repository (default: `freeleaps-local`)
- `--image-tag, -t`: Docker image tag (default: timestamp)
- `--component, -c`: Component to package (default: all components)
- `--test-mode, -m`: Packaging mode: `test` or `production` (default: `test`)
- `--run-integration, -i`: Run integration tests after packaging (default: `false`)
#### Examples
```bash
# Package all components for testing
devbox package
# Package chat component for production
devbox package --component=chat --test-mode=production
# Package with integration tests
devbox package --run-integration=true
# Package with custom settings
devbox package --image-repo=my-repo --image-tag=latest --test-mode=production
```
## Workflow Integration
### Typical Development Workflow
1. **Local Development**
```bash
# Engineer develops locally
cd ~/devbox/freeleaps/apps/chat
# Make changes to code
```
2. **Local Testing**
```bash
# Run unit tests
python -m pytest tests/
```
3. **Package for Final Testing**
```bash
# Package the component
devbox package --component=chat --test-mode=production
```
4. **Integration Testing**
```bash
# Run integration tests with packaged container
devbox package --component=chat --run-integration=true
```
5. **Submit to CI/CD**
```bash
# If all tests pass, commit and push
git add .
git commit -m "Feature: Add new chat functionality"
git push
```
### CI/CD Integration
The packaged containers can be:
- Used as base images for CI/CD pipelines
- Tested against production configurations
- Validated for security and performance
- Deployed to staging environments
## Technical Details
### Production Dockerfile Generation
When using `--test-mode=production`, the system generates optimized Dockerfiles:
```dockerfile
# Multi-stage build for production
FROM python:3.11-slim-buster as builder
# Install build dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
gcc g++ && rm -rf /var/lib/apt/lists/*
# Create virtual environment
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
# Copy and install requirements
COPY apps/chat/requirements.txt /tmp/requirements.txt
RUN pip install --no-cache-dir -r /tmp/requirements.txt
# Production stage
FROM python:3.11-slim-buster
# Create non-root user
RUN groupadd -r appuser && useradd -r -g appuser appuser
# Copy virtual environment from builder
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
# Set working directory
WORKDIR /app
# Copy application code
COPY apps/chat/ /app/
# Set environment variables for production
ENV PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1 \
PIP_NO_CACHE_DIR=1 \
PIP_DISABLE_PIP_VERSION_CHECK=1
# Change ownership to non-root user
RUN chown -R appuser:appuser /app
# Switch to non-root user
USER appuser
# Health check
HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
CMD python -c "import requests; requests.get('http://localhost:8000/health')" || exit 1
# Expose port
EXPOSE 8000
# Default command
CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```
### Integration Testing
The integration testing system:
1. **Creates Test Network**: Isolated Docker network for testing
2. **Starts Dependencies**: MongoDB, Redis, RabbitMQ containers
3. **Runs Components**: Each packaged component in test mode
4. **Health Checks**: Validates component functionality
5. **Cleanup**: Removes all test containers and networks
### Environment Validation
The system validates:
- Source code existence
- Docker buildx support
- Available disk space (5GB minimum)
- Required tools (python, pip, pytest)
- Component structure and Dockerfiles
## Best Practices
### 1. Component Structure
Ensure your components follow the standard structure:
```
apps/component_name/
├── Dockerfile
├── requirements.txt
├── tests/
│ ├── test_component.py
│ └── conftest.py
└── main.py
```
### 2. Testing Strategy
- Write comprehensive unit tests
- Include integration test scenarios
- Test both development and production modes
- Validate health check endpoints
### 3. Dockerfile Best Practices
- Use multi-stage builds for production
- Minimize image layers
- Include health checks
- Use non-root users
- Set appropriate environment variables
### 4. CI/CD Integration
- Use packaged images as base for CI/CD
- Validate against production configurations
- Run security scans on packaged images
- Test deployment procedures
## Troubleshooting
### Common Issues
1. **Missing Dockerfile**
```
Error: Dockerfile not found for component: chat
```
**Solution**: Ensure each component has a Dockerfile in its directory.
2. **Test Failures**
```
Error: Component tests failed for chat
```
**Solution**: Fix unit tests before packaging.
3. **Integration Test Failures**
```
Error: chat integration test failed
```
**Solution**: Check component health endpoints and dependencies.
4. **Insufficient Disk Space**
```
Error: Insufficient disk space for packaging
```
**Solution**: Free up disk space (minimum 5GB required).
### Debugging Tips
1. **Check Component Structure**
```bash
ls -la ~/devbox/freeleaps/apps/chat/
```
2. **Validate Dockerfile**
```bash
docker buildx build --dry-run -f ~/devbox/freeleaps/apps/chat/Dockerfile .
```
3. **Test Component Locally**
```bash
cd ~/devbox/freeleaps/apps/chat
python -m pytest tests/ -v
```
4. **Check Integration Test Logs**
```bash
docker logs test-chat
```
## Future Enhancements
### Planned Features
1. **Multi-architecture Support**: ARM64 and AMD64 builds
2. **Security Scanning**: Automated vulnerability scanning
3. **Performance Testing**: Load testing of packaged containers
4. **Registry Integration**: Push to container registries
5. **Rollback Support**: Version management and rollback capabilities
### Integration Opportunities
1. **Git Hooks**: Pre-commit packaging validation
2. **IDE Integration**: VS Code and IntelliJ plugins
3. **Monitoring**: Integration with monitoring systems
4. **Compliance**: Automated compliance checking
## Conclusion
The `devbox package` feature bridges the gap between local development and production deployment by providing engineers with the ability to test their code in production-like containers before submitting to CI/CD pipelines. This significantly reduces deployment failures and improves development confidence.
By following the best practices outlined in this document, teams can leverage this feature to create a more robust and reliable development workflow that closely mirrors production environments.

369
devbox/cli/OPENAI_CODE_REVIEW.md Normal file
View File

@ -0,0 +1,369 @@
# OpenAI Code Review Integration
## Overview
The `devbox review` command provides automated code review capabilities powered by OpenAI's GPT-4 model. This feature allows engineers to perform comprehensive code reviews locally before submitting pull requests, helping to catch issues early and improve code quality.
## Why OpenAI Code Review?
### Problem Statement
- **Manual Review Bottleneck**: Human code reviews can be slow and inconsistent
- **Missed Issues**: Important security, performance, and quality issues may be overlooked
- **Inconsistent Standards**: Different reviewers may have different standards and focus areas
- **Time Constraints**: Rushed reviews may miss critical problems
- **Knowledge Gaps**: Reviewers may not be familiar with all best practices
### Solution Benefits
- **Comprehensive Analysis**: AI reviews cover security, performance, code quality, and best practices
- **Consistent Standards**: Same review criteria applied across all code changes
- **24/7 Availability**: Reviews can be performed anytime, without waiting for human reviewers
- **Educational**: Provides explanations and suggestions for improvements
- **Local Privacy**: Reviews happen locally, keeping your code private
## Features
### 🔍 **Comprehensive Review Coverage**
- **Security Analysis**: Identifies potential vulnerabilities, input validation issues, authentication problems
- **Performance Optimization**: Detects inefficient algorithms, memory leaks, database query issues
- **Code Quality**: Checks for code smells, maintainability issues, readability problems
- **Best Practices**: Verifies adherence to language-specific best practices and design patterns
- **Error Handling**: Assesses error handling, exception management, logging practices
- **Testing**: Evaluates test coverage, test quality, and mocking practices
- **Documentation**: Checks for proper documentation, comments, and API documentation
### 📊 **Beautiful HTML Reports**
- **Interactive Interface**: Modern, responsive web interface for viewing reviews
- **Severity Classification**: Issues categorized as Critical, Warning, Info, or Suggestion
- **Code Snippets**: Relevant code sections highlighted with line numbers
- **Actionable Suggestions**: Specific recommendations for improvements
- **Export Options**: Print reports or export to different formats
### 🚀 **Local Web Server**
- **Instant Access**: View reports immediately in your browser
- **Report Management**: Browse and manage all review reports
- **Real-time Updates**: Refresh to see new reports as they're generated
- **No External Dependencies**: Everything runs locally on your machine
## Quick Start
### 1. Set Up OpenAI API Key
You can provide your OpenAI API key in two ways:
**Option A: Environment Variable (Recommended)**
```bash
export OPENAI_API_KEY="your-openai-api-key-here"
```
**Option B: Command Line**
```bash
devbox review --component=chat --api-key="your-openai-api-key-here"
```
### 2. Perform Your First Review
```bash
# Review the chat component
devbox review --component=chat
# Review with custom port
devbox review --component=authentication --port=9090
# Review without starting the web server
devbox review --component=content --start-server=false
```
### 3. View Review Reports
After running a review, open your browser and navigate to:
```
http://localhost:8080
```
## Usage Examples
### Basic Review
```bash
# Review a specific component
devbox review --component=chat
```
### Advanced Review Options
```bash
# Review with custom API key
devbox review --component=authentication --api-key="sk-..."
# Review on custom port
devbox review --component=content --port=9090
# Review without web server
devbox review --component=payment --start-server=false
# Stop the review server
devbox review --stop-server
```
### Review Multiple Components
```bash
# Review chat component
devbox review --component=chat
# Review authentication component
devbox review --component=authentication
# Review content component
devbox review --component=content
```
## Configuration
### Configuration File
The code review feature creates a configuration file at `~/.devbox/.code-review/config.yaml`:
```yaml
# OpenAI Code Review Configuration
openai:
api_key: "" # Set your OpenAI API key here or use environment variable
model: "gpt-4" # Model to use for code review
max_tokens: 4000 # Maximum tokens for review response
temperature: 0.1 # Lower temperature for more focused reviews
review:
languages:
- python
- javascript
- typescript
- java
- go
- rust
file_extensions:
- .py
- .js
- .ts
- .jsx
- .tsx
- .java
- .go
- .rs
- .cpp
- .c
- .h
- .hpp
exclude_patterns:
- "node_modules/"
- "__pycache__/"
- ".git/"
- "*.min.js"
- "*.min.css"
- "dist/"
- "build/"
- "target/"
- "vendor/"
max_file_size: 100000 # Maximum file size in bytes to review
max_files_per_review: 50 # Maximum number of files to review at once
output:
format: "html" # html, markdown, json
include_suggestions: true
include_severity: true
include_line_numbers: true
include_code_snippets: true
```
### Customizing Review Settings
You can modify the configuration file to:
- Change the OpenAI model (e.g., gpt-3.5-turbo for faster, cheaper reviews)
- Adjust the number of tokens used
- Add or remove supported file types
- Modify exclusion patterns
- Change output format preferences
## Review Process
### 1. File Detection
The system automatically detects changed files in your component:
- Staged changes (`git diff --cached`)
- Unstaged changes (`git diff`)
- Filters by supported file extensions
- Respects exclusion patterns
### 2. Content Preparation
- Reads file contents
- Prepares context for OpenAI
- Limits file size and count for optimal performance
### 3. AI Review
- Sends code to OpenAI GPT-4
- Uses specialized prompt for code review
- Receives comprehensive analysis
### 4. Report Generation
- Parses AI response
- Generates structured review data
- Creates beautiful HTML report
- Starts local web server
### 5. Review Interface
- Modern, responsive web interface
- Severity-based issue categorization
- Code snippets with line numbers
- Actionable improvement suggestions
## Review Categories
### 🔴 Critical Issues
- Security vulnerabilities
- Potential crashes or data loss
- Critical performance problems
- Major architectural issues
### 🟡 Warnings
- Code quality issues
- Potential bugs
- Performance concerns
- Best practice violations
### 🔵 Info
- Style and formatting issues
- Documentation improvements
- Minor optimizations
- Educational notes
### 🟢 Suggestions
- Enhancement opportunities
- Alternative approaches
- Future improvements
- Learning opportunities
## Best Practices
### Before Submitting PRs
1. **Run Local Tests**: Ensure your code passes all tests
2. **Perform Code Review**: Use `devbox review` to get AI feedback
3. **Address Issues**: Fix critical and warning issues
4. **Review Suggestions**: Consider implementing improvement suggestions
5. **Submit PR**: Only after addressing important issues
### Optimizing Review Quality
1. **Keep Changes Focused**: Smaller, focused changes get better reviews
2. **Include Context**: Make sure related files are included
3. **Use Descriptive Commits**: Clear commit messages help with context
4. **Review Regularly**: Don't wait until the end to review
### Cost Management
1. **Monitor Usage**: Keep track of API token usage
2. **Use Appropriate Models**: Consider gpt-3.5-turbo for routine reviews
3. **Limit File Count**: Focus on the most important files
4. **Batch Reviews**: Review multiple related changes together
## Troubleshooting
### Common Issues
**API Key Not Found**
```bash
Error: OpenAI API key not found
```
**Solution**: Set the `OPENAI_API_KEY` environment variable or use `--api-key` parameter
**API Connectivity Issues**
```bash
Error: OpenAI API connectivity test failed
```
**Solution**: Check your internet connection and API key validity
**No Changed Files**
```bash
Warning: No changed files found for review
```
**Solution**: Make sure you have staged or unstaged changes in your component
**Server Port Already in Use**
```bash
Error: Port 8080 is already in use
```
**Solution**: Use a different port with `--port` parameter
### Performance Tips
1. **Limit File Size**: Large files take longer to review and cost more
2. **Use Appropriate Model**: gpt-3.5-turbo is faster and cheaper than gpt-4
3. **Review Incrementally**: Review changes as you make them, not all at once
4. **Exclude Generated Files**: Add generated files to exclusion patterns
## Integration with Workflow
### Pre-PR Checklist
```bash
# 1. Run tests
devbox package --component=chat --test-mode=test
# 2. Perform code review
devbox review --component=chat
# 3. Address review issues
# (Fix code based on review feedback)
# 4. Re-review if needed
devbox review --component=chat
# 5. Submit PR
git push origin feature/chat-improvements
```
### CI/CD Integration
The code review feature can be integrated into your CI/CD pipeline:
- Run reviews automatically on pull requests
- Block merges if critical issues are found
- Generate review reports for team review
- Track review metrics over time
## Security and Privacy
### Local Processing
- All code review processing happens locally
- No code is stored on external servers
- API calls only send code content to OpenAI
- Review reports are stored locally
### API Key Security
- Store API keys in environment variables
- Never commit API keys to version control
- Use different API keys for different environments
- Monitor API usage for unusual activity
## Future Enhancements
### Planned Features
- **Custom Review Templates**: Define project-specific review criteria
- **Team Review Integration**: Share reviews with team members
- **Historical Tracking**: Track review metrics over time
- **Automated Fixes**: Suggest and apply automatic fixes
- **Multi-language Support**: Enhanced support for more programming languages
- **IDE Integration**: Direct integration with popular IDEs
### Advanced Capabilities
- **Context-Aware Reviews**: Consider project history and architecture
- **Performance Profiling**: Automated performance analysis
- **Security Scanning**: Integration with security scanning tools
- **Compliance Checking**: Verify compliance with coding standards
## Support
### Getting Help
- Check the troubleshooting section above
- Review the configuration options
- Ensure your OpenAI API key is valid and has sufficient credits
- Verify your component directory structure
### Contributing
The code review feature is designed to be extensible. You can:
- Customize review prompts for your specific needs
- Add support for additional file types
- Enhance the HTML report templates
- Integrate with additional tools and services
---
**Note**: The OpenAI code review feature requires an active OpenAI API key and internet connectivity. API usage is subject to OpenAI's pricing and rate limits.

3042
devbox/cli/devbox
View File

File diff suppressed because it is too large Load Diff