# Debian Atomic Configs

**Debian Atomic Configs** is the central configuration repository for Debian Atomic variants, package groups, and treefile generation. This repository serves as the single source of truth for all Debian Atomic system configurations, similar to Fedora's `workstation-ostree-config` repository.

## Purpose

This repository manages:
- **Debian Atomic variants** (GNOME, KDE Plasma, Cosmic, Sway, Budgie, Minimal)
- **Package group definitions** (like Debian Comps integration)
- **Treefile generation** for apt-ostree composition
- **Variant configuration** and package management

## Repository Structure

```
debian-atomic-configs/
├── variants/                    # Debian variant definitions (source of truth)
│   ├── debian-gnome-atomic.yaml    # Debian GNOME Atomic equivalent
│   ├── debian-plasma-atomic.yaml   # Debian KDE Plasma Atomic equivalent  
│   ├── debian-cosmic-atomic.yaml   # Debian Cosmic Atomic equivalent
│   ├── debian-sway-atomic.yaml     # Debian Sway Atomic equivalent
│   ├── debian-budgie-atomic.yaml   # Debian Budgie Atomic equivalent
│   └── minimal.yaml                # Minimal Debian system
├── treefiles/                  # Generated treefiles for apt-ostree (auto-generated)
│   ├── debian-minimal.yaml
│   ├── debian-gnome-atomic.yaml
│   ├── debian-plasma-atomic.yaml
│   ├── debian-cosmic-atomic.yaml
│   ├── debian-sway-atomic.yaml
│   └── debian-budgie-atomic.yaml
├── scripts/                    # Generation and sync scripts
│   └── test-integration.py    # Integration testing script
├── .github/workflows/          # GitHub CI/CD automation
│   └── generate-treefiles.yml # Auto-generates treefiles on variant changes
├── .forgejo/workflows/         # Forgejo CI/CD automation
│   └── generate-treefiles.yml # Auto-generates treefiles on variant changes
├── docs/                       # Documentation
│   └── ATOMIC_DESKTOPS.md     # Comprehensive desktop guide
└── README.md                   # This file
```

## Variants

### **debian-gnome-atomic** (GNOME Desktop)
- **Base**: Debian Trixie (13) stable
- **Desktop**: GNOME Shell with GNOME applications
- **Packages**: GNOME desktop, applications, development tools
- **Target**: Desktop users, developers, GNOME enthusiasts
- **OSTree Ref**: `debian/14/x86_64/gnome-atomic`

### **debian-plasma-atomic** (KDE Desktop)  
- **Base**: Debian Trixie (13) stable
- **Desktop**: KDE Plasma with KDE applications
- **Packages**: KDE desktop, applications, multimedia tools
- **Target**: KDE users, multimedia enthusiasts
- **OSTree Ref**: `debian/14/x86_64/plasma-atomic`

### **debian-cosmic-atomic** (Cosmic Desktop)
- **Base**: Debian Trixie (13) stable
- **Desktop**: Enhanced GNOME with additional applications
- **Packages**: GNOME-based with extended app suite
- **Target**: Feature-rich GNOME experience
- **OSTree Ref**: `debian/14/x86_64/cosmic-atomic`

### **debian-sway-atomic** (Sway Wayland)
- **Base**: Debian Trixie (13) stable
- **Desktop**: Sway tiling window manager with Wayland
- **Packages**: Sway, waybar, foot terminal, Wayland tools
- **Target**: Power users, tiling enthusiasts, Wayland users
- **OSTree Ref**: `debian/14/x86_64/sway-atomic`

### **debian-budgie-atomic** (Budgie Desktop)
- **Base**: Debian Trixie (13) stable
- **Desktop**: Modern, elegant desktop with GNOME technologies
- **Packages**: Budgie desktop, lightdm, plank dock
- **Target**: Users seeking alternative to GNOME/KDE
- **OSTree Ref**: `debian/14/x86_64/budgie-atomic`

### **debian-minimal** (Minimal System)
- **Base**: Debian Trixie (13) stable
- **Desktop**: None (headless)
- **Packages**: Core system, basic utilities, networking
- **Target**: Servers, containers, minimal systems
- **OSTree Ref**: `debian/14/x86_64/minimal`

## Package Groups

### **Base System**
- Core system packages (systemd, dbus, policykit)
- Essential utilities (bash, coreutils, util-linux)
- OSTree support (ostree, apt-ostree)

### **Desktop Common**
- Essential applications (file manager, terminal, browser)
- Development tools and compilers
- Multimedia codecs and libraries
- System administration tools

### **GNOME Desktop**
- GNOME Shell and session management
- GNOME applications (Files, Terminal, Control Center)
- GTK framework and dependencies
- GNOME-specific utilities and themes

### **KDE Plasma Desktop**
- KDE Plasma desktop environment
- KDE applications (Dolphin, Konsole, Kate)
- Qt framework and dependencies
- KDE-specific utilities and artwork

### **Sway Wayland**
- Sway tiling window manager
- Wayland-native applications and tools
- Minimal resource usage
- Keyboard-driven workflow

### **Budgie Desktop**
- Budgie desktop environment
- Lightweight GNOME technology base
- Modern interface design
- Alternative desktop experience

## Treefile Generation

Treefiles are YAML configurations that define:
- **Base system**: Debian Trixie and architecture
- **Package selection**: Which packages to include
- **Repository configuration**: Debian package sources
- **Customizations**: System configuration and files

### Example Treefile
```yaml
# debian-gnome-atomic.yaml
ostree:
  ref: debian/14/x86_64/gnome-atomic
  repo: /tmp/apt-ostree/debian/repo

base: debian:trixie

apt:
  sources:
    - "deb http://deb.debian.org/debian trixie main contrib non-free"
    - "deb http://deb.debian.org/debian-security trixie-security main contrib non-free"

packages:
  - gnome-shell
  - gnome-session
  - gnome-terminal
  - firefox-esr
  - build-essential
```

## Integration

### **With apt-ostree**
- **Treefile input**: apt-ostree reads treefiles from this repository
- **Variant selection**: Users choose variants defined here
- **Package management**: Package groups define what gets installed

### **With Debian Forge**
- **Base image creation**: OSBuild creates base images for variants
- **Package building**: deb-mock builds packages in clean environments
- **Image composition**: apt-ostree creates atomic images from treefiles

### **With Debian Koji**
- **Build orchestration**: Koji manages package builds for variants
- **Dependency resolution**: Package groups define build dependencies
- **Result management**: Built packages feed into treefile generation

## Development Status

**Phase 1: Foundation** ✅ **COMPLETE**
- [x] Repository structure setup
- [x] Basic variant definitions
- [x] Package group specifications
- [x] Treefile templates
- [x] Integration testing

**Phase 2: Integration** 🔄 **IN PROGRESS**
- [x] apt-ostree integration testing
- [x] Variant validation
- [ ] Debian Comps synchronization
- [ ] Automated treefile generation

**Phase 3: Production** 📋 **PLANNED**
- [ ] Production variant definitions
- [ ] CI/CD for configuration updates
- [ ] User documentation and guides
- [ ] Community variant contributions

## Usage

### Building an Atomic Desktop

```bash
# Navigate to the overseer project
cd /var/home/rob/Documents/Projects/overseer

# Activate the development environment
source dev_setup.sh

# Build a specific atomic desktop
cd debian-atomic-configs
apt-ostree compose tree --dry-run treefiles/debian-gnome-atomic.yaml
```

### Testing All Configurations

```bash
# Run the integration test to verify all configurations
python3 test-integration.py
```

### Working with Variants

```bash
# View variant definitions
cat variants/debian-gnome-atomic.yaml

# Compare package sets between variants
diff variants/debian-gnome-atomic.yaml variants/debian-plasma-atomic.yaml
```

## Contributing

This repository is part of the Debian Atomic ecosystem. Contributions are welcome!

### **Development Guidelines**
- Follow YAML best practices
- Document all package group decisions
- Test variants with apt-ostree
- Maintain compatibility with Debian standards
- Update both treefiles and variants when making changes

### **Contact**
- **Project**: Part of Debian Atomic ecosystem
- **Goal**: Centralized configuration management for Debian Atomic
- **Timeline**: Phase 2 development (Configuration & Variants)

## License

[License information to be added]

---

**Debian Atomic Configs** - Centralized configuration management for Debian Atomic variants! 🚀