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

# 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

# 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

# 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

# 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

# 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

# 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

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

# 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

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