116 lines
3.8 KiB
Markdown
116 lines
3.8 KiB
Markdown
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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:
|
|
1. Test in check mode first (`--check --diff`)
|
|
2. Use tags to test individual components
|
|
3. Validate on a test VM or secondary system before production workstation
|
|
4. Keep playbooks idempotent - safe to run multiple times
|