# Debian Atomic

## 🎯 Overview

**Debian Atomic** is a **1:1 parallel to Fedora Atomic** for the Debian ecosystem. This project implements the exact same architecture, principles, and techniques that make Fedora Atomic successful, but adapted for Debian.

## 🏗️ Architecture

### **Fedora Atomic 1:1 Parallel**

Debian Atomic mirrors Fedora Atomic's architecture exactly:

- **OSTree Integration**: Same atomic update mechanism
- **Filesystem Restructuring**: Unified `/usr` hierarchy implementation
- **Variant System**: Inherit from base image (like Fedora variants)
- **Package Management**: Debian-native with atomic operations
- **Boot Process**: Same GRUB + systemd + initramfs approach
- **Container Support**: Native OCI container format

### **Variant Equivalents**

| Debian Atomic | Fedora Atomic | Purpose |
|---------------|---------------|---------|
| **base** | **base-atomic** | Foundation system |
| **workstation** | **silverblue** | GNOME desktop |
| **kde** | **kinoite** | KDE Plasma desktop |
| **sway** | **sway-atomic** | Sway/Wayland desktop |
| **server** | **coreos** | Server infrastructure |

## 🚀 How It Works

### **1. Build Base Image**

```bash
just compose-base
```

### **2. Build Variants**

```bash
# Build all variants
just compose-variants

# Build specific variant
just compose-legacy variant=workstation
just compose-image variant=kde
```

### **3. Create Bootable Images**

```bash
# Create bootable ISO
just build-iso variant=workstation output=/tmp/output
```

## 📁 Directory Structure

```
debian-atomic/
├── treefiles/              # YAML treefile definitions (Fedora pattern)
│   ├── common.yaml         # Common packages and configs
│   ├── base.yaml           # Base variant definition
│   ├── workstation.yaml    # GNOME desktop (Silverblue equivalent)
│   ├── kde.yaml            # KDE desktop (Kinoite equivalent)
│   ├── sway.yaml           # Sway desktop (Sway Atomic equivalent)
│   └── server.yaml         # Server (CoreOS equivalent)
├── variants/                # Containerfile-based builds
│   ├── base/               # Base OSTree system
│   ├── workstation/        # GNOME variant
│   ├── kde/                # KDE variant
│   ├── sway/               # Sway variant
│   └── server/             # Server variant
├── scripts/                 # Build and sync scripts
│   ├── comps-sync.py       # Debian package group sync
│   └── bootc-image-builder.sh # ISO creation
├── justfile                 # Fedora-style build recipes
└── README.md                # This file
```

## 🔧 Fedora Atomic Integration

### **1. Treefile System**

Debian Atomic uses the exact same YAML treefile approach as Fedora:

```yaml
# workstation.yaml (Silverblue equivalent)
include: common.yaml
ref: debian-atomic/workstation
packages:
  - gnome
  - gnome-shell
  - gnome-session
  # ... GNOME packages
```

### **2. Build System**

The `justfile` provides Fedora-equivalent recipes:

- `compose-legacy`: Classic OSTree commits (Fedora default)
- `compose-image`: OCI container images (Fedora's new approach)
- `sync-comps`: Debian package group sync (Fedora comps-sync equivalent)

### **3. Variant Inheritance**

Variants inherit from base image, just like Fedora:

```
base → workstation (Silverblue equivalent)
base → kde (Kinoite equivalent)
base → sway (Sway Atomic equivalent)
base → server (CoreOS equivalent)
```

## 🎯 Benefits of Fedora Atomic 1:1 Parallel

### **1. Standards Compliance**
- Follows established immutable OS patterns
- Same sophistication level as Fedora Atomic
- Compatible with Fedora Atomic tooling

### **2. Developer Familiarity**
- Fedora Atomic developers can contribute easily
- Same workflow and concepts
- Familiar variant structure

### **3. Ecosystem Integration**
- Can leverage Fedora Atomic documentation
- Compatible with existing tools and scripts
- Same deployment and management patterns

### **4. Quality Assurance**
- Proven architecture from Fedora Atomic
- Same testing methodologies
- Established best practices

## 🚀 Quick Start

### **Prerequisites**

```bash
# Install just command runner
sudo apt install just

# Install container tools
sudo apt install podman buildah
```

### **Build System**

```bash
# Clone repository
git clone https://github.com/debian-atomic/debian-atomic
cd debian-atomic

# Show available commands
just

# Build base image
just compose-base

# Build all variants
just compose-variants

# Build specific variant
just compose-legacy variant=workstation

# Create bootable ISO
just build-iso variant=workstation output=/tmp/output
```

### **Testing**

```bash
# Test specific variant
just test-variant variant=kde

# Test all variants
just test-all-variants

# Show build status
just status
```

## 🔍 Comparison: Fedora Atomic vs Debian Atomic

| Aspect | Fedora Atomic | Debian Atomic |
|--------|---------------|---------------|
| **Base System** | Fedora + rpm-ostree | Debian + apt-ostree* |
| **Package Manager** | rpm-ostree | apt-ostree* |
| **Architecture** | OSTree + atomic layout | OSTree + atomic layout |
| **Variant System** | Inherit from base | Inherit from base |
| **Build Process** | Treefile + Pungi | Treefile + Container |
| **Update Mechanism** | OSTree commits | OSTree commits |
| **Container Support** | Native OCI | Native OCI |

*Note: `apt-ostree` is being developed to provide Debian package management with atomic operations, similar to `rpm-ostree`.

## 🎉 Conclusion

Debian Atomic provides a **1:1 parallel to Fedora Atomic** for the Debian ecosystem. By implementing the exact same architecture, principles, and techniques, we achieve:

1. **Same sophistication level** as Fedora Atomic
2. **Debian-native foundation** for familiar package ecosystem
3. **Fedora Atomic compatibility** for tooling and workflows
4. **Professional-grade immutable OS** for Debian users

This puts Debian users on equal footing with Fedora Atomic users, providing the same advanced features, reliability, and user experience in a Debian-native way.

## 📚 References

- [Fedora Atomic Desktops](https://fedoraproject.org/wiki/Atomic_Desktops)
- [Fedora Silverblue](https://silverblue.fedoraproject.org/)
- [Fedora Kinoite](https://kinoite.fedoraproject.org/)
- [Fedora CoreOS](https://coreos.fedoraproject.org/)
- [OSTree Documentation](https://ostreedev.github.io/ostree/)