Fedora Desktop Configuration Manager

Transform your fresh Fedora installation into a fully-configured development powerhouse in minutes, not hours.

What is This?

An Ansible-based automation project that eliminates the tedious manual setup of a new Fedora workstation. Run one command, grab a coffee, and come back to a system ready for serious development work.

Perfect for:

• Developers who want consistent environments across machines
• System administrators managing multiple Fedora workstations
• Anyone who's tired of manually reinstalling tools after a fresh OS install
• Teams wanting standardized development setups

Why Use This?

Instead of spending hours:

• Installing packages one by one
• Configuring Git, SSH, and development tools
• Setting up Docker, LXC, and container environments
• Tweaking bash prompts and shell configurations
• Installing fonts, codecs, and system utilities

You run a single command and get:

• A reproducible, version-controlled system configuration
• Automatic dependency management
• Secure vault-encrypted secrets
• Optional components you can enable as needed
• Battle-tested configurations used in production

Quick Start

One-Command Installation

On a fresh Fedora installation, run this as your regular user:

(source <(curl -sS https://raw.githubusercontent.com/LongTermSupport/fedora-desktop/HEAD/run.bash?$(date +%s)))

That's it. The script will:

1. Verify your Fedora version matches this branch
2. Install Ansible and dependencies
3. Configure GitHub CLI and SSH keys
4. Clone this repository to ~/Projects/fedora-desktop
5. Run the main configuration playbook

Time required: 10-30 minutes depending on your internet connection.

Before You Run It

Make sure you have:

• A fresh Fedora installation (check version compatibility below)
• Enabled third-party repositories during Fedora installation
• Logged in as your regular user (not root)
• A stable internet connection

Need more details? See the full Installation Guide.

Unattended Server / Cloud Install (IaC)

Provisioning a Fedora Server or Cloud box with no prompts (cloud-init / CI / an LLM agent)? Follow the step-by-step Headless Server Install — Unattended IaC Runbook (download run.bash, create the secret files, write the vars file, run), with the full RUN_BASH_* contract in Headless / Unattended Provisioning.

Adding GitHub Accounts

This project supports multiple GitHub identities on one machine, each with its own SSH key, gh authentication, and per-account git-<alias> / gh-<alias> shell helpers. Read the full guide before adding an account: GitHub Multi-Account Management.

To add a new GitHub account after initial setup:

./scripts/gh-account-setup.bash --add=alias:username
ansible-playbook playbooks/imports/play-github-cli-multi.yml

The setup script handles everything: GitHub CLI authentication with the required OAuth scopes, SSH key generation, key upload, and verification. The playbook then deploys the SSH config and regenerates the per-account shell helpers.

Do not authenticate with a bare gh auth login — it logs in without the required scopes and the playbook's scope audit will fail. Always use the setup script. See the full guide.

To check all configured accounts are healthy:

./scripts/gh-account-setup.bash --check

On a network that blocks SSH port 22? Keep git push/pull working by routing GitHub SSH over ssh.github.com:443: run github-ssh-443 auto && eval "$(github-ssh-443 env)". See GitHub SSH over Port 443.

Version Compatibility

Current branch targets: Fedora 44

This project uses version-specific branches:

• F44 - Fedora 44 (current)
• F45 - Fedora 45 (future)
• Each branch is maintained separately

The bootstrap script automatically verifies your Fedora version matches the branch. If you're running a different version, checkout the appropriate branch or wait for it to be created after the next Fedora release.

What You Get

Automatically Installed

The main playbook configures these essentials without any interaction:

System Foundations

• Optimized DNF configuration (10 parallel downloads, fastest mirror)
• Essential packages (vim, wget, htop, bash-completion, ripgrep)
• Microsoft fonts for document compatibility
• RPM Fusion repositories (free and non-free)

Development Environment

• Git with bash-git-prompt (Solarized theme)
• GitHub CLI (gh) for repository management
• Node.js 20 via NVM
• Claude Code CLI
• CCY — Claude Code YOLO: Claude Code in a rootless container with permission prompts disabled
• JetBrains Toolbox

Container Platform

• LXC with networking configured
• SSH keys for container access
• Firewall rules for container networking

Shell Experience

• Custom bash prompt with error state indicators
• Enhanced history (20K lines)
• Docker helper functions
• Passwordless sudo for your user

Agentic Development with CCY

ccy runs Claude Code inside a disposable, rootless Podman container with --dangerously-skip-permissions — so the agent works without stopping to ask permission for every action, while the filesystem it can damage is limited to the project you launched it in.

cd /path/to/your-project
ccy

It brings a named OAuth token pool kept separate from desktop Claude Code, per-project container images, read-only SSH key mounting for git push, container-network attachment, and an optional supervisor that compacts long sessions before they stall.

Read the CCY guide before relying on the isolation — it documents the threat model and exactly what the container can and cannot reach.

Optional Add-Ons

Choose what you need from these curated playbooks:

Containerization (learn more)

• Docker (rootless) for application containers
• Distrobox for seamless development environments
• Docker-in-LXC for isolated project testing
• Playwright testing environment (automated browser setup)

Programming Languages

• Python with pyenv, PDM, Hugging Face tools
• Go compiler and tools
• Rust toolchain

IDEs & Editors

• VS Code with Microsoft repository
• PyCharm Community (via Toolbox)
• Enhanced Vim configuration (already included)

Hardware Support

• NVIDIA proprietary drivers
• DisplayLink dock support
• HD audio configuration (192kHz, LDAC, aptX HD)
• TLP battery optimization (laptops)

Productivity Tools

• Flatpak applications (Slack, etc.)
• Firefox with profile switcher
• LastPass CLI
• VPN clients (WireGuard, Cloudflare WARP)

See Playbooks Reference for the complete list with usage examples.

Documentation

Comprehensive guides are available in the docs/ directory:

• CCY — Claude Code YOLO - Containerised Claude Code: security model, tokens, per-project images, supervisor
• Installation Guide - Step-by-step setup instructions
• Headless Server Install - Unattended IaC runbook for Fedora Server/Cloud (download → secrets → vars file → run)
• Headless / Unattended Provisioning - The full RUN_BASH_* contract, trigger rules, and security model
• Playbooks Reference - Complete list of what you can install
• Configuration Guide - Customize your setup
• Containerization Guide - LXC vs Docker vs Distrobox explained
• GitHub Multi-Account Management - Multiple GitHub identities, SSH keys, and per-account helpers
• GitHub SSH over Port 443 - Keep Git-over-SSH working on networks that block port 22
• Architecture Overview - How the project is structured
• Development Guide - Contributing and development workflow

Quick links:

• Stuck? Check Troubleshooting
• Want to add features? See Configuration Guide
• Running optional playbooks? See Playbooks Reference

Project Philosophy

This project follows these core principles:

Fail Fast - Errors stop execution immediately with clear messages YAGNI - Only include what's actually needed, keep it simple DRY - Don't repeat yourself, extract common patterns Idempotent - Safe to run multiple times, same result every time Security First - Vault-encrypted secrets, no credentials in version control

Read more about these principles in CLAUDE.md if you're contributing.

Contributing

Contributions are welcome! See the Development Guide for:

• Setting up a development environment
• Project structure and Ansible patterns
• Creating new playbooks
• Testing and debugging procedures
• Pull request guidelines

Quick contribution checklist:

• Test on fresh Fedora installation
• Verify idempotency (run twice, no changes second time)
• Follow the Ansible style guide
• Update relevant documentation
• Don't commit secrets (use Ansible Vault)

Support & Community

• Bug reports: GitHub Issues
• Questions: GitHub Discussions
• Documentation: docs/README.md

License

MIT License - see LICENSE file for details.

---

Note: This is a public repository. Never commit personal information, API keys, or secrets. Use Ansible Vault for sensitive data. See the security guidelines for details.