Initial commit

2025-08-11 08:59:41 -07:00 · 2025-08-11 08:59:41 -07:00 · 3326d796f0
commit 3326d796f0
87 changed files with 15792 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,139 @@
+# 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