139 lines
4.8 KiB
Markdown
139 lines
4.8 KiB
Markdown
# Debian bootc-image-builder
|
|
|
|
A fork of the original bootc-image-builder adapted to support Debian-based container images, enabling the creation of Particle OS - an immutable, Debian-based atomic desktop system.
|
|
|
|
## Project Overview
|
|
|
|
This project is fundamentally an **osbuild module development project**, not a simple bootc-image-builder fork. The bootc-image-builder tool is merely a thin Go wrapper that orchestrates osbuild manifests. The real work involves creating new osbuild stages that can handle Debian's mutable toolchain within an immutable paradigm.
|
|
|
|
### Critical Insight
|
|
We're not just porting from Fedora to Debian; we're adapting a mutable toolchain (apt/dpkg, initramfs-tools) to work within an immutable system architecture (OSTree). This is a paradigm shift, not a simple translation.
|
|
|
|
## Source Code Structure
|
|
|
|
```
|
|
debian-bootc-image-builder/
|
|
├── bib/ # Main Go application (from original)
|
|
│ ├── cmd/ # Command-line interfaces
|
|
│ ├── internal/ # Internal packages
|
|
│ │ ├── aptsolver/ # APT package solver
|
|
│ │ ├── debian-patch/ # Debian-specific patches
|
|
│ │ ├── solver/ # Generic solver interface
|
|
│ │ ├── distrodef/ # Distribution definitions
|
|
│ │ └── imagetypes/ # Image type handling
|
|
│ └── data/ # Distribution definitions
|
|
│ └── defs/ # YAML definition files
|
|
├── osbuild-stages/ # Debian-specific osbuild stages
|
|
│ ├── apt-stage/ # Debian package management
|
|
│ ├── debian-kernel-stage/ # Debian kernel handling
|
|
│ ├── debian-grub-stage/ # Debian GRUB configuration
|
|
│ └── debian-filesystem-stage/ # Debian filesystem setup
|
|
├── tests/ # Test suite
|
|
│ ├── unit/ # Unit tests for osbuild stages
|
|
│ ├── integration/ # Integration tests
|
|
│ └── performance/ # Performance tests
|
|
├── scripts/ # Build and development scripts
|
|
├── containerfiles/ # Example container definitions
|
|
├── calamares/ # Installer integration
|
|
└── customization/ # Customization examples
|
|
```
|
|
|
|
## Development Setup
|
|
|
|
### Prerequisites
|
|
- **Go**: >= 1.20
|
|
- **Python**: >= 3.8 (for osbuild development)
|
|
- **Podman**: Container runtime
|
|
- **Git**: Version control
|
|
|
|
### Quick Start
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/your-org/debian-bootc-image-builder.git
|
|
cd debian-bootc-image-builder
|
|
|
|
# Set up development environment
|
|
make setup-dev
|
|
|
|
# Build the project
|
|
make build
|
|
|
|
# Run tests
|
|
make test
|
|
```
|
|
|
|
## Key Components
|
|
|
|
### osbuild Stages
|
|
- **`apt-stage`**: Debian package management using APT/dpkg
|
|
- **`debian-kernel-stage`**: Kernel handling with initramfs-tools
|
|
- **`debian-grub-stage`**: GRUB configuration for Debian
|
|
- **`debian-filesystem-stage`**: Filesystem setup for immutable Debian
|
|
|
|
### Go Integration
|
|
- **`bootc_validation.go`**: Debian bootc image validation
|
|
- **`aptsolver/`**: APT package solver implementation
|
|
- **`debian-patch/`**: Debian-specific patches and extensions
|
|
|
|
### Distribution Definitions
|
|
- **`debian-13.yaml`**: Complete Debian Trixie distribution definition
|
|
- Multiple image types: qcow2, desktop, server
|
|
- Proper stage dependencies and execution order
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run unit tests
|
|
make test-unit
|
|
|
|
# Run integration tests
|
|
make test-integration
|
|
|
|
# Run performance tests
|
|
make test-performance
|
|
|
|
# Run all tests
|
|
make test
|
|
```
|
|
|
|
## Building
|
|
|
|
```bash
|
|
# Build the binary
|
|
make build
|
|
|
|
# Build container image
|
|
make build-container
|
|
|
|
# Build all components
|
|
make all
|
|
```
|
|
|
|
## Contributing
|
|
|
|
This project follows the roadmap outlined in the main documentation. Please review the current phase and contribute accordingly.
|
|
|
|
### Development Workflow
|
|
1. Check the current phase in the main documentation
|
|
2. Review the tasks and deliverables for that phase
|
|
3. Create feature branches for specific tasks
|
|
4. Write tests for new osbuild stages
|
|
5. Submit pull requests with comprehensive testing
|
|
|
|
## Documentation
|
|
|
|
For comprehensive documentation, see:
|
|
- **[Documentation Index](../docs/README.md)** - Complete documentation overview
|
|
- **[Advanced Usage Guide](../docs/usage-advanced-debian.md)** - Complete Debian adaptation guide
|
|
- **[Project Status](../dev_phases/PROJECT_STATUS.md)** - Current development status
|
|
- **[Implementation Summary](../dev_phases/IMPLEMENTATION_SUMMARY.md)** - Technical implementation details
|
|
|
|
## License
|
|
|
|
This project is licensed under the same terms as the original bootc-image-builder project.
|
|
|
|
## Acknowledgments
|
|
|
|
- Original bootc-image-builder team for the foundational work
|
|
- osbuild community for the excellent build system
|
|
- Debian community for the robust package management system
|