Desktop-System is the Source of Truth for system-level configurations and hardware orchestration on the homeserver (CachyOS). It acts as the "Brain" of the infrastructure, hosting the master Ansible playbooks that manage the entire multi-host topology (Desktop & NAS).
This repository manages the "Lower Stack" of the environment, ensuring that the hardware is performant, stable, and documented through a strict SRE lens.
| Component | Implementation | Purpose |
|---|---|---|
| Ansible Master | Full orchestration via `ansible/site.yml`. | Idempotent management of both Desktop and NAS nodes. |
| Systemd Units | Native Linux service management in `etc/systemd/system/`. | Clean lifecycle for backups, updates, and hardware resets. |
| Btrfs Snapshots | Automated snapshot chains via `upload_snapshots.sh`. | Instant recovery and backup-to-NAS logic. |
| Hardware Tweaks | Udev rules (G903 reset) and CPU governors. | Optimizing the hardware for low-latency SRE tasks. |
| Unified Docs | Syncs the central `GEMINI.md` to keep all nodes updated. | Cross-repo state awareness. |
Infrastructure-as-Code is the foundation of this setup. The `ansible/` directory contains a modular, role-based architecture designed for rapid deployment and zero-drift.
- Master Playbook: `site.yml` handles the full stack from foundation to admin tools.
- Modular Roles:
- `foundation`: Base packages and system hardening.
- `admin_stack`: Deployment of Caddy, Prometheus, Grafana, and Semaphore.
- `storage`: MergerFS and Btrfs configuration.
- `desktop`: Desktop-specific packages and optimizations.
- `nas`: NAS-specific services and HDD management.
- Semaphore Integration: The playbooks are exposed via a web UI (hosted on NAS) for remote execution.
The system is designed to be self-healing and easy to maintain through centralized scripts in `usr/local/bin/`.
- Trigger Update: ```bash sudo system-update.sh ```
- Verify State: Check the Systemd timer state for `system-update.timer`.
```bash cd ansible ansible-playbook -i inventory.ini site.yml ```
| Script Name | Purpose |
|---|---|
| `system-update.sh` | Orchestrates a full system update with Btrfs snapshot safety. |
| `upload_snapshots.sh` | Syncs local Btrfs snapshots to the NAS storage tier. |
| `dotfiles-sync.sh` | Enforces the system-level state (symlinks in `/etc/`, etc.). |
| `g903-reset.sh` | Hardware-specific reset logic triggered via Udev. |
Refer to GEMINI.md for architectural rules and SRE guidelines.