Skip to content

README.md

Latest commit

 

History

History
412 lines (291 loc) · 14.1 KB

README.md

File metadata and controls

412 lines (291 loc) · 14.1 KB
Raw

Documentation Index

Complete guide to the Fedora Desktop Configuration Manager.

New Here? Start Here

First time setup:

  1. Read Installation Guide - Get up and running
  2. Browse Playbooks Reference - See what optional features you can add
  3. Check Configuration Guide - Learn how to customize

Quick answers:

Documentation by Purpose

I want to install the system

Installation 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

I want to provision a server or cloud box unattended (IaC)

Headless Server Install — Unattended IaC Runbook — start here

A precise, copy-paste, step-by-step runbook (download → secret files → vars file → run), optimised to be followed by a human or an LLM agent. Includes a full cloud-init example and a one-shot install script.

Headless / Unattended Provisioning — the reference

The what behind the how: when headless mode triggers, the full RUN_BASH_* environment contract (non-secret config + 0600 secret file pointers), the security model, and the fail-fast, fail-loud guarantee.

The authoritative contract is also built into the script: ./run.bash --help-run-headless.

I want to add optional features

Playbooks Reference

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

I want to understand containerization options

Containerization Guide

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

I want to run Claude Code safely without permission prompts

CCY — Claude Code YOLO

Containerised Claude Code running with --dangerously-skip-permissions:

  • What the container does and does not expose (the security model)
  • Named OAuth token pool, separate from desktop Claude Code
  • Per-project container images, networks, and SSH key handling
  • The supervisor: automatic compaction so long sessions do not stall
  • Full flag reference and troubleshooting

Time to read: 15 minutes | Daily driver for agent work

I want to customize my setup

Configuration Guide

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

I want to understand how it works

Architecture Overview

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

I want to contribute or modify

Development Guide

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

Common Tasks Quick Reference

Installation & Setup

# 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_distribution

Adding Optional Features

cd ~/Projects/fedora-desktop

# Install rootful Docker (optional — needed for DDEV; Podman is the default engine)
ansible-playbook playbooks/imports/optional/common/play-docker.yml

# Install Distrobox
ansible-playbook playbooks/imports/optional/common/play-distrobox.yml

# Install Python environment (core — also runs automatically via main playbook)
ansible-playbook playbooks/imports/play-python.yml

# Add VS Code (core — also runs automatically via main playbook)
ansible-playbook playbooks/imports/play-vscode.yml

# Install DDEV (local PHP/CMS development)
ansible-playbook playbooks/imports/optional/common/play-ddev.yml

Configuration Management

# Edit settings (plain YAML file — open in any normal editor)
$EDITOR environment/localhost/host_vars/localhost.yml

# Encrypt a new secret value to paste into localhost.yml
ansible-vault encrypt_string 'sensitive-value' --name 'variable_name'

# Check DNF optimization
grep max_parallel /etc/dnf/dnf.conf

# Test playbook without applying changes
ansible-playbook playbook.yml --check

Containerization

# 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

CCY (Claude Code in a container)

# Start a session in the current project
ccy

# Token management
ccy --create-token
ccy --list-tokens

# Rebuild after changing .claude/ccy/Dockerfile
ccy --rebuild

# Manage running CCY containers
ccy --top

Project File Structure

~/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 (plain YAML with !vault values)
│
├── 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

Documentation Topics A-Z

Architecture & Design

Configuration & Customization

Containerization

CCY (Claude Code YOLO)

DDEV

Development & Contributing

Features

GitHub

Headless / Server Provisioning

Networking

Installation & Setup

Playbooks & Features

Terminal

Troubleshooting Quick Links

Getting Help

Version Information

Current branch: Fedora 44 (F44)

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 version

If versions don't match, checkout the appropriate branch:

cd ~/Projects/fedora-desktop
git fetch origin
git checkout F44  # or your version