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