From 520ea57489f992267b3defc1fbd65256ec25788f Mon Sep 17 00:00:00 2001 From: robojerk Date: Tue, 12 Aug 2025 00:26:49 -0700 Subject: [PATCH] docs: Add bootc-image-builder integration and CI/CD workflows - Added comprehensive explanation of osbuild + bootc-image-builder integration - Included GitHub Actions workflow for automated image building - Added GitLab CI configuration with multi-stage pipeline - Included Forgejo Actions workflow for open source CI/CD - Enhanced documentation with real-world deployment examples - Added container-native booting and infrastructure as code benefits --- README.md | 226 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 226 insertions(+) diff --git a/README.md b/README.md index 2ccaea2..9e30088 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,42 @@ particle-os extends osbuild with **10 Debian-specific stages** and **Debian-spec - **`org.osbuild.debian.qemu`** - Bootable disk image creation (raw, qcow2, vmdk, vdi) +## 🔗 osbuild and bootc-image-builder Integration + +### What is bootc-image-builder? + +**bootc-image-builder** is a tool that uses osbuild to create bootable container images that can be deployed using bootc. It provides a higher-level interface for building OSTree-based systems with container-native booting capabilities. + +### How They Work Together + +``` +bootc-image-builder → osbuild → particle-os stages → Debian OSTree system + ↓ ↓ ↓ ↓ + Container config Manifest Debian stages Bootable image +``` + +### Integration Benefits + +1. **Container-native booting** - Images can be deployed as containers +2. **Atomic updates** - OSTree provides rollback and update capabilities +3. **Infrastructure as code** - Declarative image definitions +4. **CI/CD integration** - Automated image building and testing +5. **Multi-platform support** - Build for different architectures and cloud providers + +### Example bootc-image-builder Usage + +```bash +# Install bootc-image-builder +sudo apt install bootc-image-builder + +# Build a Debian OSTree image using particle-os +bootc-image-builder build \ + --type qcow2 \ + --config config.toml \ + --output-dir ./outputs \ + debian-ostree.json +``` + ## 🚀 Quick Start ### 1. Installation @@ -138,6 +174,196 @@ osbuild examples/debian-ostree-bootable.json 9. **GRUB2** → Configure bootloader 10. **OSTree** → Create OSTree repository and commit +## 🔄 CI/CD Workflows + +### GitHub Actions + +```yaml +name: Build Debian OSTree Image + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + build-image: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + sudo apt update + sudo apt install -y python3-pip python3-venv + python3 -m venv venv + source venv/bin/activate + pip install -r requirements.txt + + - name: Install particle-os + run: | + source venv/bin/activate + make install + + - name: Run tests + run: | + source venv/bin/activate + make test + + - name: Build Debian OSTree image + run: | + source venv/bin/activate + osbuild examples/debian-ostree-bootable.json + + - name: Upload artifacts + uses: actions/upload-artifact@v3 + with: + name: debian-ostree-image + path: debian-ostree-bootable.qcow2 +``` + +### GitLab CI + +```yaml +stages: + - test + - build + - deploy + +variables: + PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip-cache" + +cache: + paths: + - .pip-cache/ + +test: + stage: test + image: python:3.11 + before_script: + - pip install -r requirements.txt + - make install + script: + - make test + artifacts: + reports: + junit: test-results.xml + +build: + stage: build + image: python:3.11 + before_script: + - pip install -r requirements.txt + - make install + script: + - osbuild examples/debian-ostree-bootable.json + artifacts: + paths: + - "*.qcow2" + - "*.raw" + expire_in: 1 week + only: + - main + +deploy: + stage: deploy + image: python:3.11 + script: + - echo "Deploying image to production..." + # Add your deployment logic here + only: + - main + when: manual +``` + +### Forgejo Actions + +```yaml +name: Build and Test Debian OSTree Image + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Install system dependencies + run: | + sudo apt update + sudo apt install -y python3-pip python3-venv build-essential + + - name: Install Python dependencies + run: | + python3 -m venv venv + source venv/bin/activate + pip install -r requirements.txt + + - name: Install particle-os + run: | + source venv/bin/activate + make install + + - name: Run test suite + run: | + source venv/bin/activate + make test + + build: + needs: test + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + sudo apt update + sudo apt install -y python3-pip python3-venv + python3 -m venv venv + source venv/bin/activate + pip install -r requirements.txt + make install + + - name: Build Debian OSTree image + run: | + source venv/bin/activate + osbuild examples/debian-ostree-bootable.json + + - name: Upload build artifacts + uses: actions/upload-artifact@v3 + with: + name: debian-ostree-images + path: | + *.qcow2 + *.raw + *.vmdk +``` + ## 🔧 Advanced Usage ### Custom Stage Configuration