|
|
|
|
@@ -0,0 +1,123 @@
|
|
|
|
|
# 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
|
|
|
|
|
```bash
|
|
|
|
|
# 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
|
|
|
|
|
```bash
|
|
|
|
|
# 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
|
|
|
|
|
```bash
|
|
|
|
|
# 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:
|
|
|
|
|
```bash
|
|
|
|
|
# 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
|