deb-bootc-image-builder/containerfiles/readme.md

Containerfiles Directory

This directory contains container definitions for building different variants of Particle OS - a Debian-native immutable operating system built with OSTree and bootc.

Overview

These containerfiles define the base images that will be processed by your deb-bootc-image-builder tool to create bootable disk images. Each containerfile represents a different system variant with specific characteristics and use cases.

Container Variants

1. Containerfile.debian-trixie-minimal

Purpose: Minimal base system for server and embedded deployments

Characteristics:

• Base: Debian Trixie (testing)
• Desktop: None (headless)
• Size: Minimal footprint
• Use Case: Servers, containers, embedded systems, CI/CD runners

Key Features:

• Core system packages only
• OSTree integration for atomic updates
• Bootc compatibility
• Network management tools
• Essential system utilities

Target Audience: System administrators, DevOps engineers, embedded developers

---

2. Containerfile.debian-trixie-kde

Purpose: Full desktop environment with KDE Plasma

Characteristics:

• Base: Debian Trixie (testing)
• Desktop: KDE Plasma Desktop Environment
• Size: Full desktop installation
• Use Case: Desktop workstations, development machines, user-facing systems

Key Features:

• Complete KDE Plasma desktop
• Full application suite (Dolphin, Konsole, Kate, Firefox)
• Audio and graphics support
• Auto-login configuration for testing
• OSTree + bootc integration

Target Audience: Desktop users, developers, content creators, general users

---

3. Containerfile.particle-os

Purpose: Core Particle OS system (original reference implementation)

Characteristics:

• Base: Debian Trixie-slim
• Desktop: None (minimal)
• Size: Lightweight but complete
• Use Case: Reference implementation, base for other variants

Key Features:

• Core system components
• OSTree boot configuration
• Systemd services
• Basic user environment
• Clean, minimal approach

Target Audience: Developers, system integrators, reference implementation

---

How They Work Together

Build Process

1. Container Build: Each containerfile builds a specific system variant
2. Image Processing: Your deb-bootc-image-builder tool processes these containers
3. Bootable Image: Creates bootable disk images (raw, qcow2, vmdk, vdi)
4. Deployment: Images can be deployed to physical hardware or virtual machines

Variant Selection

• Minimal: Choose for servers, embedded systems, or when you need a small footprint
• KDE: Choose for desktop workstations or when you need a full GUI environment
• Core: Choose as a base for custom variants or when you need the reference implementation

Technical Details

OSTree Integration

All variants include OSTree configuration for:

• Atomic system updates
• Rollback capability
• Immutable system design
• Bootc compatibility

Bootc Compatibility

Each container is designed to work with the bootc system:

• Proper filesystem structure
• Bootloader configuration
• Kernel and initramfs setup
• Systemd service configuration

Debian Foundation

All variants are built on Debian Trixie:

• Latest testing packages
• Debian package ecosystem
• Debian security updates
• Debian community support

Usage Examples

Building a Minimal Server

# Build the minimal container
podman build -f containerfiles/Containerfile.debian-trixie-minimal -t particle-os-minimal .

# Process with deb-bootc-image-builder
./bib/particle-os build --base-image particle-os-minimal recipes/server.yml

Building a Desktop System

# Build the KDE desktop container
podman build -f containerfiles/Containerfile.debian-trixie-kde -t particle-os-kde .

# Process with deb-bootc-image-builder
./bib/particle-os build --base-image particle-os-kde recipes/desktop.yml

Custom Variants

# Use the core container as a base
podman build -f containerfiles/Containerfile.particle-os -t particle-os-core .

# Add your custom packages and configuration
# Then process with deb-bootc-image-builder

Development Workflow

1. Modify Containerfiles: Adjust package selection, configuration, or features
2. Build Containers: Test your changes with podman build
3. Test Integration: Verify OSTree and bootc compatibility
4. Create Images: Use deb-bootc-image-builder to create bootable images
5. Test Boot: Verify the images boot correctly in QEMU or on hardware

Contributing

When adding new container variants:

• Follow the existing naming convention
• Include comprehensive documentation
• Test OSTree and bootc integration
• Update this readme with new variant information
• Ensure compatibility with deb-bootc-image-builder

Related Documentation

• Main README: Project overview and getting started
• HACKING.md: Development guidelines
• Recipes: YAML configuration files for image building
• OSTree Workspace: OSTree development and testing tools

---

These containerfiles represent the foundation of Particle OS - a Debian-native approach to immutable operating systems, built with the same principles as Fedora Atomic but adapted for the Debian ecosystem.