debian-atomic-config/ATOMIC_DESKTOPS.md

Debian Atomic Desktop Configurations

This document lists all available atomic desktop configurations for the Debian Atomic ecosystem.

Directory Structure

The project contains two main directories for configurations:

• treefiles/: Contains the actual treefile configurations used by apt-ostree
• variants/: Contains detailed variant definitions with package groupings and metadata

Available Configurations

1. debian-minimal.yaml

• Purpose: Minimal Debian Trixie system with basic tools
• Desktop: None (CLI only)
• Use Case: Server deployments, minimal systems
• OSTree Ref: debian/14/x86_64/minimal
• Variant: variants/minimal.yaml

2. debian-gnome-atomic.yaml

• Purpose: GNOME desktop environment
• Desktop: GNOME Shell with GNOME applications
• Use Case: Traditional desktop experience, GNOME users
• OSTree Ref: debian/14/x86_64/gnome-atomic
• Variant: variants/debian-gnome-atomic.yaml
• Key Packages: gnome-shell, gnome-session, gdm3

3. debian-plasma-atomic.yaml

• Purpose: KDE Plasma desktop environment
• Desktop: KDE Plasma with KDE applications
• Use Case: KDE users, modern desktop experience
• OSTree Ref: debian/14/x86_64/plasma-atomic
• Variant: variants/debian-plasma-atomic.yaml
• Key Packages: plasma-desktop, plasma-workspace, sddm

4. debian-cosmic-atomic.yaml

• Purpose: Cosmic desktop (GNOME-based with customizations)
• Desktop: Enhanced GNOME with additional applications
• Use Case: Feature-rich GNOME experience
• OSTree Ref: debian/14/x86_64/cosmic-atomic
• Variant: variants/debian-cosmic-atomic.yaml
• Key Packages: gnome-shell, gnome-tweaks, gnome-extensions

5. debian-sway-atomic.yaml

• Purpose: Sway Wayland desktop environment
• Desktop: Tiling window manager with Wayland
• Use Case: Power users, tiling enthusiasts, Wayland users
• OSTree Ref: debian/14/x86_64/sway-atomic
• Variant: variants/debian-sway-atomic.yaml
• Key Packages: sway, waybar, foot terminal

6. debian-budgie-atomic.yaml

• Purpose: Budgie desktop environment
• Desktop: Modern, elegant desktop with GNOME technologies
• Use Case: Users seeking alternative to GNOME/KDE
• OSTree Ref: debian/14/x86_64/budgie-atomic
• Variant: variants/debian-budgie-atomic.yaml
• Key Packages: budgie-desktop, lightdm, plank

Variants vs Treefiles

Treefiles (treefiles/)

• Purpose: Direct configuration for apt-ostree compose
• Format: YAML with apt-ostree specific syntax
• Usage: Direct input to apt-ostree commands
• Content: Package lists, system configuration, OSTree settings

Variants (variants/)

• Purpose: Detailed package organization and metadata
• Format: YAML with logical package groupings
• Usage: Reference for developers and package management
• Content: Categorized packages, excluded packages, development tools

Usage

Building an Atomic Desktop

# 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

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

Working with Variants

# 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

Customization

Each configuration can be customized by:

1. Adding packages: Modify the packages section in treefiles
2. Changing services: Update the system.services section
3. Custom directories: Add to the system.directories section
4. Post-install scripts: Modify the postinstall section
5. Package organization: Update the corresponding variant file

Base System

All configurations include:

• Debian Trixie base system
• OSTree support via apt-ostree
• Systemd services and configuration
• Basic system utilities and tools

Desktop-Specific Features

GNOME Atomic

• Full GNOME desktop experience
• GNOME Software for package management
• GNOME Extensions support
• Traditional desktop workflow

Plasma Atomic

• Complete KDE Plasma environment
• KDE Connect integration
• Plasma widgets and customization
• Modern desktop features

Cosmic Atomic

• Enhanced GNOME with additional apps
• GNOME Tweaks for customization
• Extended GNOME application suite
• Rich desktop experience

Sway Atomic

• Tiling window management
• Wayland-native applications
• Keyboard-driven workflow
• Minimal resource usage

Budgie Atomic

• Elegant, modern interface
• GNOME technology base
• Lightweight and fast
• Alternative desktop experience

Development

Adding New Configurations

1. Create a new YAML file in the treefiles/ directory
2. Create a corresponding variant file in the variants/ directory
3. Follow the existing structure and format
4. Update the OSTree reference
5. Test with apt-ostree
6. Add to this documentation

Testing

• All configurations are tested with the integration test suite
• Use --dry-run flag for testing without building
• Verify package dependencies exist in Debian Trixie
• Test system service configurations
• Validate both treefile and variant files

Support

For issues with specific configurations:

• Check the component-specific documentation
• Review the integration test output
• Verify package availability in Debian Trixie
• Test with minimal configuration first
• Compare with working variant files