freeleaps-pub/devbox/cli/BUILD_DEPLOY_FEATURES.md

# 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.