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.
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 --checkCurrent 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, 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
- 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
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.
Comprehensive guides are available in the docs/ directory:
- Installation Guide - Step-by-step setup instructions
- 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
- 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.