debian-atomic/README.md

Debian Atomic

A pure Debian-based immutable operating system, bringing the benefits of atomic updates and immutable deployments to the Debian ecosystem.

🎯 Project Status: Foundation Complete, Tools in Development

Current State: We have a working build system that can create Debian-based container images with OSTree tools installed. The core immutable OS foundation is solid and tested, but we're building the atomic functionality piece by piece.

What This Means: You get a solid foundation that's ready for the next phase of development, with core tools actively being developed in parallel.

📋 Debian Atomic vs Fedora Atomic: Realistic Assessment

✅ What's Actually Working (Proven & Tested)

Feature	Debian Atomic	Fedora Atomic	Status
Build System	✅ Working justfile-based recipes	✅ Working justfile-based recipes	Identical
Container Images	✅ All variants build successfully	✅ All variants build successfully	Identical
OSTree Tools	✅ ostree, ostree-boot installed	✅ ostree, ostree-boot installed	Identical
Unified /usr	✅ Symlinks: /bin -> /usr/bin	✅ Symlinks: /bin -> /usr/bin	Identical
Pure Debian Base	✅ Debian 13 (Trixie) stable	✅ Fedora 42+	Different
UEFI Boot Support	✅ efibootmgr, shim-signed	✅ efibootmgr, shim-signed	Identical
Registry Integration	✅ Push to Forgejo registry	✅ Push to container registry	Parallel

🔄 What's In Active Development (Separate Repositories)

Component	Repository	Status	Description
apt-ostree	particle-os/apt-ostree	🔄 Active Development	Debian equivalent of rpm-ostree for atomic package management
deb-bootc-image-builder	particle-os/deb-bootc-image-builder	🔄 Active Development	Debian-native bootc image builder for deployment workflows
deb-bootupd	particle-os/deb-bootupd	🔄 Active Development	Debian-native bootloader update daemon
bootc	particle-os/bootc	🔄 Active Development	Debian-native bootable container deployment tool

❓ What's Planned (Not Yet Implemented)

Feature	Debian Atomic	Fedora Atomic	Status
Atomic Updates	❓ apt-ostree integration needed	✅ rpm-ostree working	Planned
System Rollbacks	❓ apt-ostree integration needed	✅ Instant rollback working	Planned
Immutable Base	❓ apt-ostree integration needed	✅ Read-only /usr working	Planned
Deployment Workflow	❓ deb-bootc-image-builder needed	✅ bootc-image-builder working	Planned
Bootloader Updates	❓ deb-bootupd integration needed	✅ bootupd working	Planned

🔍 What's Different (Debian-Specific Choices)

Aspect	Debian Atomic	Fedora Atomic	Status
Security Model	🔄 AppArmor (planned)	✅ SELinux enabled	Different
Firewall	🔄 iptables/nftables (planned)	✅ firewalld	Different
Package Ecosystem	🔄 Debian repositories (planned)	✅ Fedora repositories	Different

🚀 Quick Start

Prerequisites

• Host System: Debian 13 (Trixie) or newer, Ubuntu 24.04 (Noble) or newer
• Container Runtime: Podman 4.0+ or Docker 24.0+
• Build Tools: just command runner
• Registry Access: Forgejo registry (or configure for your preferred registry)

Clone and Setup

# Clone the repository
git clone https://git.raines.xyz/particle-os/debian-atomic.git
cd debian-atomic

# Install just command runner (if not already installed)
cargo install just

# Configure registry (optional - defaults to git.raines.xyz/robojerk)
# Edit variants/*/Containerfile to change registry URLs

Build All Variants

# Build all variants (base, workstation, server, testing, debian-bootc-base)
just build-all

# Check build status
just status

# Clean all images
just clean

Individual Variant Builds

# Build specific variants
just compose-base
just compose-workstation
just compose-server
just compose-testing
just compose-debian-bootc-base

# Build and push to registry
just build-deploy base
just build-deploy workstation

🏗️ Repository Structure

debian-atomic/
├── variants/                    # Container image definitions
│   ├── base/                   # Minimal Debian base
│   ├── workstation/            # Desktop environment
│   ├── server/                 # Server tools
│   ├── testing/                # Testing/development tools
│   └── debian-bootc-base/     # OSTree-enabled base
├── treefiles/                  # Package group definitions
│   ├── common.yaml            # Common packages for all variants
│   ├── tasks.yaml             # Debian task definitions
│   └── *.yaml                 # Variant-specific packages
├── scripts/                    # Build and utility scripts
│   └── comps-sync.py         # Package synchronization
├── docs/                       # Documentation
│   ├── process-overview.md    # Technical manual
│   └── ostree-reference-investigation.md
├── reports/                    # Component status reports
├── justfile                    # Build system orchestration
└── README.md                   # This file

🔧 Build System

Available Just Recipes

# Core build commands
just compose-{variant}          # Build specific variant
just build-all                  # Build all variants
just build-deploy {variant}     # Build and push to registry

# Utility commands
just status                     # Show build status
just clean                      # Remove all images
just sync-packages              # Sync package groups
just build-iso                  # Generate ISO (planned)

Package Management

# Sync package groups from Debian tasks
just sync-packages

# This updates treefiles/*.yaml with current Debian package groups
# Based on Debian's official task definitions

📊 Current Status

✅ What's Working Today

• Build System: All variants build successfully and push to registry
• OSTree Foundation: Basic OSTree tools and structure in debian-bootc-base
• Container Images: Pure Debian 13 (Trixie) base with no Fedora dependencies
• Registry Integration: Successfully pushing to Forgejo registry
• Package Synchronization: Automated sync with Debian task definitions

🔄 What's In Development

• apt-ostree: Atomic package management (separate repository)
• deb-bootc-image-builder: Deployment workflow (separate repository)
• deb-bootupd: Bootloader updates (separate repository)
• bootc: Container deployment (separate repository)

❓ What's Planned Next

• Integration Testing: Test core tools with our images
• Deployment Workflow: End-to-end atomic deployment
• System Administration: SSH, user management, networking
• Performance Validation: Boot time, memory usage, update speed

🛠️ Development Workflow

Phase 1: Foundation (✅ Complete)

• Build system working
• Container images building
• Registry integration working
• OSTree tools installed

Phase 2: Core Tools (🔄 In Progress)

• apt-ostree development
• deb-bootc-image-builder development
• deb-bootupd development
• bootc development

Phase 3: Integration (❓ Planned)

• Tool integration testing
• Deployment workflow validation
• System administration tools
• Performance optimization

Phase 4: Production (❓ Future)

• Production deployment testing
• Community documentation
• Performance benchmarking
• Security hardening

🔍 What We Don't Do

• Fedora Dependencies: We're building pure Debian, not Fedora-based
• Traditional Package Management: We're building atomic, not traditional
• Application Containers: We're building OS images, not app containers
• Legacy Support: We're building modern, not legacy-compatible

📚 Technical Details

OSTree Repository Structure

Our debian-bootc-base variant includes:

• /ostree/repo with proper OSTree repository structure
• debian-atomic/base ref for bootc compatibility
• Bare repository mode for container images

Container Build Process

1. Base Image: Start with debian:trixie-slim
2. Package Installation: Install OSTree tools and system packages
3. OSTree Setup: Initialize repository and create base commit
4. Image Finalization: Clean up and optimize for deployment

Package Synchronization

We automatically sync with Debian's official task definitions:

• debian-atomic-base: Minimal system
• debian-atomic-workstation: Desktop environment
• debian-atomic-server: Server tools

📖 Documentation

• Technical Manual: Step-by-step build instructions
• OSTree Investigation: Technical findings
• Component Reports: Status reports for each component

🤝 Contributing

Current Development Focus

1. Core Tools: Help develop apt-ostree, deb-bootc-image-builder, deb-bootupd, bootc
2. Integration: Test core tools with our container images
3. Documentation: Improve technical documentation and user guides
4. Testing: Validate build system and deployment workflows

How to Contribute

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Development Guidelines

• Test on Debian 13+: Ensure compatibility with target distributions
• Follow Debian Standards: Use Debian packaging and development practices
• Document Changes: Update relevant documentation and reports
• Validate Builds: Ensure all variants still build successfully

🙏 Acknowledgments

• Debian Project: For the rock-solid base system
• OSTree Project: For the immutable filesystem foundation
• Fedora Project: For inspiration and architectural guidance
• Forgejo: For hosting our development infrastructure

🔗 Related Projects

• apt-ostree: Atomic package management for Debian
• deb-bootc-image-builder: Debian-native bootc image builder
• deb-bootupd: Debian-native bootloader update daemon
• bootc: Debian-native bootable container deployment

📈 Roadmap

Q3 2025: Core Tools Development

• Complete apt-ostree basic functionality
• Complete deb-bootc-image-builder core features
• Complete deb-bootupd basic functionality
• Complete bootc Debian compatibility

Q4 2025: Integration and Testing

• Integrate core tools with container images
• Validate deployment workflows
• Performance testing and optimization
• Security hardening and validation

Q1 2026: Production Readiness

• Production deployment testing
• Community documentation and guides
• Performance benchmarking
• Security audit and compliance

🎯 Bottom Line

Debian Atomic today gives you a working, proven build system with the same architecture as Fedora Atomic. The core immutable OS foundation is solid and tested. What's missing is the atomic functionality - but that's being actively developed in parallel repositories.

You're getting a solid foundation that's ready for the next phase of development, with core tools actively being developed by the community. This is a realistic, honest assessment of where we are and where we're going.