willlaptop/ansible/CLAUDE.md

CLAUDE.md

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

Overview

This is an Ansible-based machine provisioning system for Arch Linux systems. It automates the setup of a new machine including hostname, networking (WiFi/Ethernet), user accounts, SSH configuration, and package installation from multiple sources (pacman, AUR, Flatpak, AppImage).

Architecture

The repository follows Ansible's role-based structure with two primary roles:

Common Role (roles/common/)

Handles system-level configuration:

• Hostname configuration
• Network configuration using NetworkManager (nmcli)
• User account management with password-hashed credentials
• SSH daemon configuration with handlers for service restart

Key Implementation Details:

• Network connections use creates: parameter to avoid recreating existing NetworkManager connection files
• User passwords should be hashed (SHA-512) or managed via Ansible Vault
• SSH configuration changes trigger the Restart sshd handler (defined in roles/common/handlers/main.yml)

Packages Role (roles/packages/)

Manages software installation from multiple sources:

• Ensures yay AUR helper is installed (clones from AUR, builds with makepkg)
• Installs pacman packages from roles/packages/files/pkglist.txt
• Installs AUR packages from roles/packages/files/aur_pkglist.txt using yay
• Installs Flatpak packages from roles/packages/files/flatpak_pkglist.txt
• Downloads AppImages from URLs in roles/packages/files/appimage_pkglist.txt to ~/Applications

Key Implementation Details:

• Yay installation uses a block with conditional execution (checks if yay exists first)
• Package lists are read line-by-line using with_lines module
• AppImages are set to executable mode (0755) upon download

Common Commands

Running the Full Playbook

# Full run with privilege escalation prompt
ansible-playbook -i inventory playbook.yml --ask-become-pass

# Dry-run to preview changes
ansible-playbook -i inventory playbook.yml --check

# With encrypted vault variables
ansible-playbook -i inventory playbook.yml --ask-vault-pass --ask-become-pass

Running Specific Tasks with Tags

# Network configuration only (WiFi + Ethernet)
ansible-playbook -i inventory playbook.yml --tags "network" --ask-become-pass

# WiFi configuration only
ansible-playbook -i inventory playbook.yml --tags "wifi" --ask-become-pass

# Ethernet configuration only
ansible-playbook -i inventory playbook.yml --tags "ethernet" --ask-become-pass

# User management only
ansible-playbook -i inventory playbook.yml --tags "users" --ask-become-pass

# SSH daemon configuration only
ansible-playbook -i inventory playbook.yml --tags "sshd" --ask-become-pass

# Install pacman packages only
ansible-playbook -i inventory playbook.yml --tags "pacman" --ask-become-pass

# Install AUR packages only
ansible-playbook -i inventory playbook.yml --tags "aur" --ask-become-pass

# Install Flatpak packages only
ansible-playbook -i inventory playbook.yml --tags "flatpak" --ask-become-pass

# Download AppImages only
ansible-playbook -i inventory playbook.yml --tags "appimage" --ask-become-pass

Syntax Validation

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

# Lint all playbooks and roles
ansible-lint playbook.yml

Configuration Files

• ansible.cfg: Sets default inventory location
• inventory: Defines target hosts (currently configured for [new_machine] group)
• playbook.yml: Main orchestration playbook applying both roles
• roles/common/defaults/main.yml: Default variables for hostname, network, users, SSH (contains sensitive data)
• roles/packages/defaults/main.yml: File paths for package lists

Security Considerations

This repository contains sensitive information in plaintext (roles/common/defaults/main.yml):

• WiFi passwords
• User password hashes
• Static IP configurations

When modifying sensitive variables:

# Encrypt sensitive files
ansible-vault encrypt roles/common/defaults/main.yml

# Edit encrypted files
ansible-vault edit roles/common/defaults/main.yml

# View encrypted files
ansible-vault view roles/common/defaults/main.yml

Target System Requirements

• OS: Arch Linux (uses pacman, AUR, systemd)
• Network: NetworkManager for network configuration
• Python: Python 3 interpreter at /usr/bin/python3
• SSH: SSH access with sudo privileges