Complete guide to the Fedora Desktop Configuration Manager.
First time setup:
- Read Installation Guide - Get up and running
- Browse Playbooks Reference - See what optional features you can add
- Check Configuration Guide - Learn how to customize
Quick answers:
- "How do I install this?" → One-command installation
- "What does it install?" → Core playbooks
- "How do I add Docker?" → Optional playbooks
- "What's the difference between LXC, Docker, and Distrobox?" → Containerization Guide
Everything you need to get started:
- Prerequisites and system requirements
- One-command installation walkthrough
- What happens during installation
- Manual installation steps
- Common installation issues and fixes
Time to read: 5 minutes | Time to install: 10-30 minutes
Complete catalog of available features:
- Core features (automatic)
- Development tools (Docker, Python, Go, VS Code)
- Container platforms (LXC, Docker, Distrobox)
- Hardware support (NVIDIA, DisplayLink, audio)
- Desktop enhancements (GNOME, Firefox, VPN)
- How to run optional playbooks
- Creating custom playbooks
Time to read: 10 minutes | Quick reference format
Comprehensive comparison and usage guide:
- LXC vs Docker vs Distrobox comparison table
- When to use each technology
- Installation and configuration
- Real-world usage examples
- Docker-in-LXC for isolated development
- Troubleshooting container issues
Time to read: 15 minutes | Includes decision tree
Learn how to make it yours:
- User configuration (name, email, vault)
- System configuration (DNF, bash, SSH, Git)
- Optional feature configuration
- Ansible patterns and best practices
- Adding custom playbooks and files
- Debugging configuration issues
Time to read: 10 minutes | Reference guide
Deep dive into project structure:
- Directory structure and organization
- Execution flow (bootstrap → main → optional)
- Configuration management patterns
- Variable hierarchy
- File management
- Security model
Time to read: 8 minutes | For contributors and curious minds
Everything for contributors:
- Development environment setup
- Branching strategy (version-specific branches)
- Ansible style guide and patterns
- Testing and debugging procedures
- Contribution workflow
- Pull request guidelines
- Security considerations
Time to read: 12 minutes | Essential for contributors
# One-command install (fresh Fedora)
(source <(curl -sS https://raw.githubusercontent.com/LongTermSupport/fedora-desktop/HEAD/run.bash?$(date +%s)))
# Re-run main playbook
cd ~/Projects/fedora-desktop
ansible-playbook playbooks/playbook-main.yml --ask-become-pass
# Check what's installed
ansible desktop -m setup | grep ansible_distributioncd ~/Projects/fedora-desktop
# Install Docker (rootless)
ansible-playbook playbooks/imports/optional/common/play-docker.yml
# Install Distrobox
ansible-playbook playbooks/imports/optional/common/play-distrobox.yml
# Install Python environment
ansible-playbook playbooks/imports/optional/common/play-python.yml
# Add VS Code
ansible-playbook playbooks/imports/optional/common/play-vscode.yml# View encrypted settings
ansible-vault view environment/localhost/host_vars/localhost.yml
# Edit encrypted settings
ansible-vault edit environment/localhost/host_vars/localhost.yml
# Check DNF optimization
grep max_parallel /etc/dnf/dnf.conf
# Test playbook without applying changes
ansible-playbook playbook.yml --check# LXC: Create container
sudo lxc-create -n mycontainer -t download -- -d ubuntu -r jammy -a amd64
sudo lxc-start -n mycontainer
# Docker: Run service
docker run -d -p 8080:80 nginx
# Distrobox: Create dev environment
distrobox create --name dev --image ubuntu:22.04
distrobox enter dev~/Projects/fedora-desktop/
├── docs/ # Documentation (you are here)
│ ├── README.md # This index
│ ├── installation.md # Setup guide
│ ├── playbooks.md # Feature catalog
│ ├── configuration.md # Customization guide
│ ├── containerization.md # Container tech comparison
│ ├── architecture.md # Technical deep dive
│ └── development.md # Contributor guide
│
├── playbooks/ # Ansible automation
│ ├── playbook-main.yml # Main orchestrator (automatic)
│ └── imports/
│ ├── play-*.yml # Core playbooks
│ └── optional/
│ ├── common/ # General features
│ ├── hardware-specific/ # Hardware drivers
│ └── experimental/ # Bleeding-edge features
│
├── environment/localhost/ # Configuration
│ ├── hosts.yml # Inventory (localhost)
│ └── host_vars/localhost.yml # User settings (encrypted)
│
├── files/ # Static files deployed to system
│ ├── etc/ # System configs
│ └── var/ # Scripts and data
│
├── vars/ # Project variables
│ └── fedora-version.yml # Target Fedora version
│
├── run.bash # Bootstrap installer
├── ansible.cfg # Ansible configuration
├── vault-pass.secret # Vault password (gitignored)
└── CLAUDE.md # AI coding assistant instructions
Architecture & Design
Configuration & Customization
Containerization
Development & Contributing
Installation & Setup
Playbooks & Features
- Installation fails: Installation troubleshooting
- Version mismatch: Version troubleshooting
- Container issues: Container troubleshooting
- Configuration errors: Configuration debugging
- Playbook debugging: Testing guide
- Bug reports: GitHub Issues
- Questions & discussions: GitHub Discussions
- Source code: GitHub Repository
- Main README: Back to main page
Current branch: Fedora 42 (F42)
This documentation matches the configuration in this branch. Other Fedora versions have separate branches with version-specific changes.
Check your installed version:
cat /etc/fedora-release # Your system version
cat ~/Projects/fedora-desktop/vars/fedora-version.yml # Target versionIf versions don't match, checkout the appropriate branch:
cd ~/Projects/fedora-desktop
git fetch origin
git checkout F43 # or your version