Repository structure

This repository combines a Quarto documentation site with Ansible automation. The documentation explains the workflow; the playbooks and roles perform the repeatable system setup.

It is a self-contained shared lab baseline. A separate personal overlay may depend on and extend it, but this repository never depends on an overlay.

Main directories and files

docs/

Quarto source files for this website. Use these pages as the high-level workstation manual: new-machine setup, day-to-day operations, configuration notes, and concise reference material.

playbooks/

Executable Ansible entry points. playbooks/lab-stack.yml configures Fedora Workstation, playbooks/cloud-stack.yml configures an existing server-oriented (non-GUI) Fedora Cloud/server machine, and playbooks/audit-unmanaged-packages.yml audits package drift. Cloud infrastructure provisioning remains outside this repository.

roles/

Reusable Ansible configuration units. Roles keep related installation and configuration tasks together so they can be run from the main playbook and documented in the Software section.

inventory

Tracked local Ansible inventory file. It tells Ansible to configure localhost with a local connection. This file is intentionally generic for single-workstation use; keep local overrides in host_vars/localhost.yml.

host_vars/

Optional location for host-specific variables when a workstation needs local overrides. Keep secrets out of committed variable files.

group_vars/

Shared variables for playbooks, including package audit settings and allowlists.

Makefile

Convenience commands for common workflows. Prefer these commands in day-to-day use when a target exists, and use raw ansible-playbook commands when you need full transparency or extra options.

.github/

If present, this directory contains GitHub-specific project automation such as workflows or repository metadata. It is not required for local workstation execution.

How the pieces fit together

  1. Follow the New machine pages in docs/ to install Fedora, install prerequisites, verify the committed inventory, and run the lab stack.
  2. Run make install, which delegates to the lab-stack compatibility target and calls the main Ansible playbook.
  3. The playbook applies focused roles from roles/.
  4. Use Software pages for role-specific manual steps and checks.
  5. Use Day-to-day operations pages for recurring software updates and backup and sync routines.