# CLAUDE.md

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

## Project Overview

This is an Ansible setup repository for managing system configurations. The project uses Ansible for infrastructure automation and configuration management.

**License**: GNU Affero General Public License v3.0 (AGPL-3.0)

## Repository Structure

This repository is currently in early setup phase. Typical Ansible project structure includes:
- `playbooks/` - Ansible playbooks for orchestrating configurations
- `roles/` - Reusable Ansible roles
- `inventory/` - Host inventory files (hosts.ini, hosts.yml)
- `group_vars/` - Variables organized by groups
- `host_vars/` - Variables for specific hosts
- `ansible.cfg` - Ansible configuration file

## Common Ansible Commands

### Running Playbooks
```bash
# Run a playbook
ansible-playbook playbooks/site.yml

# Run with specific inventory
ansible-playbook -i inventory/hosts.ini playbooks/site.yml

# Check mode (dry run)
ansible-playbook --check playbooks/site.yml

# Run with specific tags
ansible-playbook playbooks/site.yml --tags "web,database"

# Run specific hosts
ansible-playbook playbooks/site.yml --limit "webservers"
```

### Testing and Validation
```bash
# Check playbook syntax
ansible-playbook --syntax-check playbooks/site.yml

# List tasks in a playbook
ansible-playbook --list-tasks playbooks/site.yml

# List hosts that will be affected
ansible-playbook --list-hosts playbooks/site.yml

# Validate inventory
ansible-inventory --list -i inventory/hosts.ini
ansible-inventory --graph -i inventory/hosts.ini
```

### Ad-hoc Commands
```bash
# Ping all hosts
ansible all -m ping

# Check disk space on all hosts
ansible all -a "df -h"

# Gather facts from hosts
ansible all -m setup
```

### Ansible Vault (for sensitive data)
```bash
# Create encrypted file
ansible-vault create group_vars/production/vault.yml

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

# Encrypt existing file
ansible-vault encrypt vars/secrets.yml

# Run playbook with vault password
ansible-playbook playbooks/site.yml --ask-vault-pass
```

## Development Workflow

### When Creating Playbooks
- Use YAML syntax with proper indentation (2 spaces)
- Start playbooks with descriptive names and hosts definitions
- Include `gather_facts: yes/no` explicitly
- Use `become: yes` when privilege escalation is needed
- Group related tasks using block statements
- Add meaningful task names that describe the action

### When Creating Roles
- Follow Ansible Galaxy role structure: tasks/, handlers/, templates/, files/, vars/, defaults/, meta/
- Keep roles focused on a single responsibility
- Use role dependencies in meta/main.yml when appropriate
- Test roles independently before integrating

### Variables and Inventory
- Use group_vars for shared variables across host groups
- Use host_vars for host-specific configurations
- Prefer YAML format over INI for inventory when complexity grows
- Never commit sensitive data unencrypted (use ansible-vault)

### Best Practices
- Always test with `--check` mode first
- Use handlers for service restarts and reloads
- Leverage tags for partial playbook execution
- Use templates (Jinja2) for dynamic configuration files
- Register task outputs when results are needed in subsequent tasks
- Use `changed_when` and `failed_when` to control task status reporting