Update ansible configuration to match current system state
- Updated ethernet interface name to enp0s20u1u1u2 - Changed default shell to fish - Removed uninstalled packages (zsh, htop, rclone, helm, llama-swap) - Network config still differs (systemd-networkd/iwd vs nmcli)
This commit is contained in:
OpenCode Test
123
ansible/CLAUDE.md
Normal file
123
ansible/CLAUDE.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user