Transform your fresh Fedora installation into a fully-configured development powerhouse in minutes, not hours.
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
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
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:
- Verify your Fedora version matches this branch
- Install Ansible and dependencies
- Configure GitHub CLI and SSH keys
- Clone this repository to
~/Projects/fedora-desktop - Run the main configuration playbook
Time required: 10-30 minutes depending on your internet connection.
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.
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.
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.ymlThe 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 --checkOn a network that blocks SSH port 22? Keep
git push/pullworking by routing GitHub SSH overssh.github.com:443: rungithub-ssh-443 auto && eval "$(github-ssh-443 env)". See GitHub SSH over Port 443.
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.
The main playbook configures these essentials without any interaction:
System Foundations
- Optimized DNF configuration (10 parallel downloads)
- 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), including multi-account support
- Node.js (latest LTS) via NVM
- Python with pyenv, PDM, and Hugging Face tools
- Claude Code CLI
- CCY — Claude Code YOLO: Claude Code in a rootless container with permission prompts disabled
- VS Code (from the Microsoft repository) and JetBrains Toolbox
Container Platform
- Podman (rootless) — the default engine
- Docker (rootful) — compatibility engine for tools such as DDEV
- LXC with networking configured
- SSH keys for container access
- Firewall rules for container networking
Desktop Applications
- Firefox with managed enterprise policies
- Slack (via Flatpak)
- WireGuard tools and OpenVPN NetworkManager integration
Shell Experience
- Custom bash prompt with error state indicators
- Enhanced history (20K lines)
- Kitty terminal with managed configuration and keybindings
- Docker helper functions
- Passwordless sudo for your user
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
ccyIt 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.
Choose what you need from these curated playbooks:
Containerization (learn more)
Podman (rootless, the default engine) and Docker (rootful, for tools that need it such as DDEV) are both installed by the main playbook — see Container Engines for which to reach for. Optional on top:
- Distrobox for seamless development environments
- Docker-in-LXC for isolated project testing
- DDEV for local PHP/CMS development (Drupal, WordPress, Laravel, Magento)
- UniFi Network Controller self-hosted in a Podman container
- Browser automation testing (via CCY's built-in
agent-browser-headed,agent-browser-headlessandagent-browser-lite-headless)
Programming Languages
- Go compiler and tools
- Rust toolchain
IDEs & Editors
- 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
- Speech-to-Text — voice typing across the whole desktop (GPU-accelerated, falls back to CPU)
- Claude DevTools (
ccdt) — web UI for Claude Code session logs - Fast File Manager —
lf-based terminal file manager - LastPass CLI
- Extra VPN clients: Cloudflare WARP, NordVPN
See Playbooks Reference for the complete list with usage examples.
Comprehensive guides are available in the docs/ directory — start at the documentation index if you are not sure where to look.
Installing and upgrading
- 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 - Post-Upgrade Repair - Checklist after a major Fedora version upgrade
Tools and features
- CCY — Claude Code YOLO - Containerised Claude Code: security model, tokens, per-project images, supervisor
- CCY Debug Mounts - Read-only host access from inside a CCY container
- Speech-to-Text - Press-and-hold voice typing with auto-paste
- Claude DevTools (
ccdt) - Visualise Claude Code session logs in a web UI - Fast File Manager -
lf-based terminal file manager - Kitty Terminal - Managed configuration, keybindings, URL copy workflow
Containers and local development
- Containerization Guide - Podman, Docker, LXC and Distrobox explained
- DDEV - Local PHP/CMS development environments
- UniFi Network Controller - Self-hosted controller for whole-house WiFi roaming
Accounts and networking
- 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
- NordVPN Installation - OpenVPN-based setup via NetworkManager
Reference and contributing
- Playbooks Reference - Complete list of what you can install
- Configuration Guide - Customize your setup
- 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
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.
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)
- Bug reports: GitHub Issues
- Questions: GitHub Discussions
- Documentation: docs/README.md
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.