# 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
```bash
# 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
```bash
# 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
```bash
# 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.*