CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Purpose

Comprehensive Ansible configuration for managing Fedora Workstation laptops. Provides automated configuration management for system setup, package management, security hardening, and laptop-specific optimizations.

Common Commands

Running Playbooks

# Run main playbook against localhost
ansible-playbook -i inventory/hosts playbook.yml --ask-become-pass

# Run specific tags
ansible-playbook -i inventory/hosts playbook.yml --tags "packages,security" --ask-become-pass

# Dry run (check mode)
ansible-playbook -i inventory/hosts playbook.yml --check --diff

# Run against specific host
ansible-playbook -i inventory/hosts playbook.yml --limit hostname

# Use vault-encrypted variables
ansible-playbook -i inventory/hosts playbook.yml --ask-vault-pass

Testing and Validation

# Syntax check
ansible-playbook playbook.yml --syntax-check

# List all tasks that would be executed
ansible-playbook -i inventory/hosts playbook.yml --list-tasks

# List all hosts
ansible-playbook -i inventory/hosts playbook.yml --list-hosts

# Validate inventory
ansible-inventory -i inventory/hosts --list

Vault Operations

# Create encrypted file
ansible-vault create group_vars/all/vault.yml

# Edit encrypted file
ansible-vault edit group_vars/all/vault.yml

# Encrypt existing file
ansible-vault encrypt secrets.yml

# Decrypt file (temporary)
ansible-vault view group_vars/all/vault.yml

# Rekey vault file
ansible-vault rekey group_vars/all/vault.yml

Architecture

Standard Ansible Directory Structure

This repository follows standard Ansible best practices for a workstation management setup:

inventory/ - Host definitions and group variables
roles/ - Reusable role modules (packages, security, dotfiles, etc.)
group_vars/ - Variables for host groups
host_vars/ - Variables for specific hosts
playbooks/ or root playbook.yml - Main orchestration
files/ - Static files to be copied to hosts
templates/ - Jinja2 templates for configuration files

Typical Role Organization

Roles should follow the structure:

roles/role_name/
├── tasks/main.yml      # Main task list
├── handlers/main.yml   # Handlers for service restarts, etc.
├── templates/          # Jinja2 templates
├── files/              # Static files
├── vars/main.yml       # Role-specific variables
├── defaults/main.yml   # Default variables (lowest precedence)
└── meta/main.yml       # Role dependencies

Workstation Management Patterns

For Fedora workstation management, typical role categories include:

Base system: DNF configuration, repositories, system services
Packages: Software installation and updates
Security: Firewall, SELinux, user permissions
Laptop optimization: Power management, suspend/hibernate, battery optimization
User configuration: Dotfiles, shell setup, desktop environment
Development tools: Programming languages, IDEs, containers

Security Considerations

Vault Usage

All sensitive data (passwords, API keys, certificates) must be encrypted with ansible-vault
Never commit unencrypted vault files (.gitignore already configured)
Store vault password securely outside the repository

Privilege Escalation

Use become: true only when necessary
Prefer targeted become on specific tasks rather than entire playbooks
Always use --ask-become-pass when running locally for security

Testing Approach

For workstation configurations:

Test in check mode first (--check --diff)
Use tags to test individual components
Validate on a test VM or secondary system before production workstation
Keep playbooks idempotent - safe to run multiple times

3.8 KiB Raw Blame History