freeleaps-pub/devbox/cli/LOCAL_CODE_PACKAGING.md

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

# Package all components for testing
devbox package

# Package specific component
devbox package --component=chat

# Package for production
devbox package --test-mode=production

Advanced Usage

# 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

# 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

   # Engineer develops locally
   cd ~/devbox/freeleaps/apps/chat
   # Make changes to code
   

2. Local Testing

   # Run unit tests
   python -m pytest tests/
   

3. Package for Final Testing

   # Package the component
   devbox package --component=chat --test-mode=production
   

4. Integration Testing

   # Run integration tests with packaged container
   devbox package --component=chat --run-integration=true
   

5. Submit to CI/CD

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

# 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

   ls -la ~/devbox/freeleaps/apps/chat/
   

2. Validate Dockerfile

   docker buildx build --dry-run -f ~/devbox/freeleaps/apps/chat/Dockerfile .
   

3. Test Component Locally

   cd ~/devbox/freeleaps/apps/chat
   python -m pytest tests/ -v
   

4. Check Integration Test Logs

   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.