181 lines
6.2 KiB
Markdown
181 lines
6.2 KiB
Markdown
# Debian Integration Approach for Blue-Build CLI
|
|
|
|
## Overview
|
|
|
|
This document explains the approach we've implemented for integrating Debian support into the Blue-Build CLI, following the established patterns used for Fedora version management.
|
|
|
|
## The Right Approach: Leveraging Existing Infrastructure
|
|
|
|
Instead of creating a separate Debian driver (which would have been complex and error-prone), we've implemented a more elegant solution that leverages the existing Blue-Build infrastructure.
|
|
|
|
### Key Insight
|
|
|
|
Blue-Build CLI already has a sophisticated system for handling different OS versions through:
|
|
1. **Automatic OS Version Detection** from base images
|
|
2. **Template Substitution** using the `os_version` variable
|
|
3. **Version-Aware Module Logic** that can adapt based on detected versions
|
|
|
|
## How It Works
|
|
|
|
### 1. OS Version Detection
|
|
|
|
The CLI automatically detects the OS version from the base image:
|
|
|
|
```bash
|
|
# From scripts/exports.sh
|
|
export OS_VERSION="$(awk -F= '/^VERSION_ID=/ {gsub(/"/, "", $2); print $2}' /usr/lib/os-release)"
|
|
```
|
|
|
|
This version is then passed to the Jinja2 templates as `os_version`.
|
|
|
|
### 2. Template Substitution
|
|
|
|
The `os_version` variable can be used throughout the build process:
|
|
|
|
```jinja2
|
|
# In templates, you can use:
|
|
{{ os_version }}
|
|
|
|
# For example, in Debian-specific templates:
|
|
RUN echo "deb http://deb.debian.org/debian trixie main" >> /etc/apt/sources.list.d/bluebuild.list
|
|
# Could become:
|
|
RUN echo "deb http://deb.debian.org/debian {{ os_version }} main" >> /etc/apt/sources.list.d/bluebuild.list
|
|
```
|
|
|
|
### 3. Version-Specific Logic
|
|
|
|
Modules can implement version-specific behavior:
|
|
|
|
```yaml
|
|
# Example: Debian packages module
|
|
- type: script
|
|
snippets:
|
|
- echo "Installing packages for Debian version {{ os_version }}"
|
|
- apt-get update
|
|
- apt-get install -y package-name
|
|
```
|
|
|
|
## Implementation Details
|
|
|
|
### What We Removed
|
|
|
|
1. **Custom Debian Driver**: Removed the complex `DebianDriver` implementation
|
|
2. **Driver Type Enum**: Removed `BuildDriverType::Debian`
|
|
3. **Custom Build Logic**: Removed Debian-specific build processes
|
|
4. **Legacy Python Implementation**: Removed `debian_blue_build/` directory (abandoned Python code)
|
|
5. **Unused Templates**: Removed custom Debian templates and Containerfiles
|
|
6. **Empty Directories**: Cleaned up `containerfiles/debian-setup/` and related empty directories
|
|
|
|
### What We Kept
|
|
|
|
1. **Existing Driver Infrastructure**: Docker, Podman, Buildah drivers remain intact
|
|
2. **Template System**: The powerful Jinja2 templating system continues to work
|
|
3. **Version Detection**: OS version detection from base images
|
|
4. **Module System**: All existing module types (script, files, etc.)
|
|
|
|
### What We Added
|
|
|
|
1. **Debian-Aware Templates**: Templates that can handle Debian-specific logic
|
|
2. **Example Recipes**: Demonstrations of how to use the system for Debian builds
|
|
3. **Documentation**: Clear examples of the approach
|
|
|
|
## Benefits of This Approach
|
|
|
|
### 1. **Simplicity**
|
|
- No complex driver implementations
|
|
- Leverages existing, tested infrastructure
|
|
- Minimal code changes required
|
|
|
|
### 2. **Consistency**
|
|
- Same patterns used for both Fedora and Debian
|
|
- Unified template system
|
|
- Consistent error handling and logging
|
|
|
|
### 3. **Maintainability**
|
|
- No duplicate code paths
|
|
- Single source of truth for build logic
|
|
- Easier to test and debug
|
|
|
|
### 4. **Flexibility**
|
|
- Can easily add support for other distributions
|
|
- Version-specific logic without custom drivers
|
|
- Template-based customization
|
|
|
|
## Example Usage
|
|
|
|
### Basic Debian Recipe
|
|
|
|
```yaml
|
|
---
|
|
name: debian-server
|
|
description: Debian server image
|
|
base-image: ghcr.io/ublue-os/silverblue-main # Fedora base
|
|
image-version: latest
|
|
|
|
modules:
|
|
- type: script
|
|
snippets:
|
|
- echo "Building for Debian-style server"
|
|
- echo "OS Version: {{ os_version }}"
|
|
# Debian-specific logic here
|
|
```
|
|
|
|
### Debian Package Management
|
|
|
|
```yaml
|
|
modules:
|
|
- type: script
|
|
snippets:
|
|
# Configure Debian repositories based on version
|
|
- echo "deb http://deb.debian.org/debian {{ os_version }} main" >> /etc/apt/sources.list.d/bluebuild.list
|
|
- apt-get update
|
|
- apt-get install -y nginx postgresql
|
|
```
|
|
|
|
## Future Enhancements
|
|
|
|
### 1. **Debian-Specific Modules**
|
|
- Create `debian-packages` module type
|
|
- Add to official schema for validation
|
|
- Implement version-aware package management
|
|
|
|
### 2. **Debian Base Images**
|
|
- Use actual Debian base images when needed
|
|
- Implement proper Debian version detection
|
|
- Handle Debian-specific metadata
|
|
|
|
### 3. **Advanced Version Logic**
|
|
- Support for Debian codenames (trixie, forky, sid)
|
|
- Version compatibility checking
|
|
- Automated repository selection
|
|
|
|
## Conclusion
|
|
|
|
This approach demonstrates that sometimes the best solution is to work with existing systems rather than against them. By leveraging Blue-Build's existing version detection and template infrastructure, we've achieved Debian integration with minimal complexity while maintaining all the benefits of the established system.
|
|
|
|
The key insight is that **version management is a solved problem** in Blue-Build - we just needed to apply it to Debian use cases rather than reinventing the wheel.
|
|
|
|
## Files Modified
|
|
|
|
- `process/drivers/traits.rs` - Removed Debian driver references
|
|
- `process/drivers/types/drivers.rs` - Removed Debian driver type
|
|
- `process/drivers.rs` - Removed Debian driver module
|
|
- `src/lib.rs` - Removed Debian driver from build engine mapping
|
|
- `examples/debian-server.yml` - Created example recipe
|
|
- `DEBIAN_INTEGRATION_APPROACH.md` - This documentation
|
|
|
|
## Files/Directories Removed
|
|
|
|
- `process/drivers/debian_driver.rs` - Custom Debian driver implementation
|
|
- `debian_blue_build/` - Legacy Python implementation (abandoned)
|
|
- `containerfiles/debian-setup/` - Empty directory from old approach
|
|
- `template/templates/modules/debian-packages/` - Custom Debian templates
|
|
- `template/templates/Containerfile-debian.j2` - Custom Debian Containerfile template
|
|
- `scripts/test-debian-driver.sh` - Test script for old approach
|
|
|
|
## Next Steps
|
|
|
|
1. **Test with Real Debian Base Images**: Verify the approach works with actual Debian images
|
|
2. **Create Debian-Specific Templates**: Develop templates optimized for Debian workflows
|
|
3. **Add to Official Schema**: Integrate Debian modules into the official Blue-Build schema
|
|
4. **Documentation**: Update main README with Debian integration examples
|