fscotto/infra
1
0
Fork 0
mirror of https://github.com/fscotto/infra.git synced 2026-05-31 07:49:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Refresh repository documentation for current state

Browse Source
This commit is contained in:
Fabio Scotto di Santolo
2026-03-25 22:18:24 +01:00
parent 980e984020
commit 88a9126afb
2 changed files with 92 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files

151
AGENTS.md
View File

@@ -1,67 +1,55 @@
# AGENTS.md # AGENTS.md
Guidance for agentic coding tools working in this repository. Guidance for agentic coding tools working in this repository.
Project type: Ansible-based infrastructure plus managed dotfiles. Project type: Ansible-based infrastructure and user dotfiles.
## Repository snapshot ## Repository snapshot
- Entry playbook: `ansible/site.yml` - Entry playbook: `ansible/site.yml`
- Ansible config: `ansible.cfg`
- Inventory: `ansible/inventory/hosts.yml` - Inventory: `ansible/inventory/hosts.yml`
- Group vars: `ansible/inventory/group_vars/*.yml` - Group vars: `ansible/inventory/group_vars/*.yml`
- Host vars: `ansible/inventory/host_vars/*.yml` - Host vars: `ansible/inventory/host_vars/*.yml`
- Active roles: `dotfiles_common`, `packages_void`, `services_runit`, `profile_desktop_i3`, `packages_ubuntu`, `services_systemd`, `profile_workstation_gnome`, `profile_server` - Templates: `ansible/templates/**/*.j2`
- Roles present but not currently wired into `ansible/site.yml`: `base`, `dotfiles`
- Dotfiles source of truth: `dotfiles/` - Dotfiles source of truth: `dotfiles/`
- Utility scripts: `scripts/` - Utility scripts: `scripts/`
- Sensitive local material/examples: `secrets/` - Sensitive material/examples: `secrets/`
## Local instruction files ## Active orchestration
Checked in this repository when this file was written:
- `.cursorrules`: not present
- `.cursor/rules/`: not present
- `.github/copilot-instructions.md`: not present
If any of these files appear later, treat them as higher-priority local instructions.
## Working assumptions
- Favor idempotent, host-safe changes over cleverness.
- Preserve the intended layering: `all -> OS -> profile -> host`.
- Validate on one host before broad rollout.
- Prefer minimal, targeted edits over cleanup refactors.
- Treat `secrets/` as sensitive and avoid exposing secret values.
- The repo contains both first-party dotfiles and vendored third-party plugin code.
## Current orchestration model
`ansible/site.yml` currently applies: `ansible/site.yml` currently applies:
- `all -> dotfiles_common` - `all -> dotfiles_common`
- `void -> packages_void, services_runit, profile_desktop_i3` - `void -> packages_void, services_runit, profile_desktop_i3`
- `ubuntu_workstation -> packages_ubuntu, services_systemd, profile_workstation_gnome` - `ubuntu_workstation -> packages_ubuntu, services_systemd, profile_workstation_gnome`
- `ubuntu_server -> packages_ubuntu, services_systemd, profile_server` - `ubuntu_server -> packages_ubuntu, services_systemd, profile_server`
## Build, lint, and test commands Active roles:
There is no compile/build step. Validation is based on Ansible syntax checks, inventory inspection, dry-runs, and linting. - `dotfiles_common`, `packages_void`, `services_runit`, `profile_desktop_i3`, `packages_ubuntu`, `services_systemd`, `profile_workstation_gnome`, `profile_server`
Install base tooling if needed: Roles present but not wired into `ansible/site.yml`:
- `base`
- `dotfiles`
## Local instruction files
Checked in this repository when this file was written:
- `.cursorrules`: not present
- `.cursor/rules/`: not present
- `.github/copilot-instructions.md`: not present
If any of these appear later, treat them as higher-priority local instructions.
## Working assumptions
- Favor idempotent, host-safe changes over cleverness.
- Preserve the layering: `all -> OS -> profile -> host`.
- Validate on one host before broad rollout.
- Prefer minimal, targeted edits over cleanup refactors.
- Treat `secrets/` as sensitive and avoid exposing values.
- `dotfiles/common/.tmux/plugins/` contains vendored upstream code.
## Build, lint, and test commands
There is no compile/build step. Validation is based on syntax checks, inventory inspection, dry-runs, and linting.
Install tooling if needed:
```bash ```bash
python3 -m pip install ansible python3 -m pip install ansible
ansible-galaxy collection install community.general ansible-galaxy collection install community.general
``` ```
Core commands:
```bash
ansible-playbook ansible/site.yml
ansible-playbook ansible/site.yml --check --diff
ansible-playbook ansible/site.yml --syntax-check
ansible-playbook ansible/site.yml --limit ikaros
ansible-playbook ansible/site.yml --limit nymph
ansible-playbook ansible/site.yml --limit deadalus
ansible-playbook ansible/site.yml --limit ubuntu_workstation
ansible-playbook ansible/site.yml --limit prometheus
ansible-playbook ansible/site.yml --limit ubuntu_server
ansible-inventory --graph
ansible-inventory --host ikaros
ansible-inventory --host deadalus
ansible-inventory --host prometheus
```
Linting and static checks if available locally: Linting and static checks if available locally:
```bash ```bash
ansible-lint ansible/site.yml ansible-lint ansible/site.yml
@@ -79,33 +67,17 @@ Fastest confidence check:
ansible-playbook ansible/site.yml --syntax-check ansible-playbook ansible/site.yml --syntax-check
``` ```
Best default host-scoped dry-run: Best default dry-runs:
```bash ```bash
ansible-playbook ansible/site.yml --limit ikaros --check --diff ansible-playbook ansible/site.yml --limit ikaros --check --diff
``` ansible-playbook ansible/site.yml --limit deadalus --check --diff
ansible-playbook ansible/site.yml --limit prometheus --check --diff
Validate one host's resolved inventory only:
```bash
ansible-inventory --host ikaros
```
Validate a narrow Ansible change starting from one task:
```bash
ansible-playbook ansible/site.yml --limit ikaros --start-at-task "Copy common dotfiles" --check --diff
ansible-playbook ansible/site.yml --limit ikaros --start-at-task "Install Void nonfree repository if needed" --check --diff
ansible-playbook ansible/site.yml --limit ikaros --start-at-task "Copy desktop dotfiles" --check --diff
```
Validate the standalone mail bootstrap script only:
```bash
sh -n scripts/bootstrap_mail.sh
shellcheck scripts/bootstrap_mail.sh
``` ```
Testing notes: Testing notes:
- Prefer `--limit` aggressively to avoid accidental multi-host rollout. - Prefer `--limit` aggressively to avoid accidental multi-host rollout.
- Prefer `--check --diff` before package, service, PAM, bootloader, or session changes. - Prefer `--check --diff` before package, service, PAM, bootloader, firewall, or session changes.
- Keep task names stable and unique enough to support `--start-at-task`. - Keep task names stable and unique enough for `--start-at-task`.
- If you change only vars, inventory inspection may be the quickest useful check. - If you change only vars, inventory inspection may be the quickest useful check.
## Code style guidelines ## Code style guidelines
@@ -114,65 +86,49 @@ Testing notes:
- Prefer declarative modules over imperative commands. - Prefer declarative modules over imperative commands.
- Avoid unrelated refactors while solving a targeted task. - Avoid unrelated refactors while solving a targeted task.
- Preserve idempotency and make state transitions explicit. - Preserve idempotency and make state transitions explicit.
- Keep changes readable for humans reviewing YAML and shell.
### Ansible modules and task structure ### Ansible modules and task structure
- Use FQCN module names such as `ansible.builtin.copy` and `community.general.xbps`. - Use FQCN module names such as `ansible.builtin.copy` and `community.general.ufw`.
- Prefer purpose-built modules over `ansible.builtin.command` or `ansible.builtin.shell`. - Prefer purpose-built modules over `ansible.builtin.command` or `ansible.builtin.shell`.
- Use `command` only when no good module exists. - Use `command` only when no good module exists; use `shell` only when shell features are required.
- Use `shell` only when shell features are genuinely required.
- When using `command` or `shell`, set `changed_when` and `failed_when` when defaults are misleading. - When using `command` or `shell`, set `changed_when` and `failed_when` when defaults are misleading.
- Keep task names imperative, outcome-based, and unique enough for `--start-at-task`. - Keep task names imperative, outcome-based, and unique enough for `--start-at-task`.
- Use `block` when a sequence of tasks shares one condition or operational purpose. - Tag every task consistently with its execution flow, typically `packages`, `services`, `dotfiles`, `gnome`, `nvidia`, or `dotfiles:*`.
- Prefer `loop` with clear `loop_control.label` for user-facing collections. - Prefer `loop` with clear `loop_control.label` for user-facing collections.
### YAML formatting ### YAML formatting
- Start YAML files with `---`. - Start YAML files with `---`.
- Use 2-space indentation and never tabs. - Use 2-space indentation and never tabs.
- Keep keys, lists, and maps in stable, readable order. - Keep keys, lists, and maps in stable order.
- Quote file modes as strings: `"0644"`, `"0755"`, `"0600"`, `"0700"`. - Quote file modes as strings: `"0644"`, `"0755"`, `"0600"`, `"0700"`.
- Prefer multiline Jinja when a one-line expression becomes hard to read.
- Avoid formatting-only churn in untouched sections. - Avoid formatting-only churn in untouched sections.
### Variables, types, and templating ### Variables, types, and naming
- Use `snake_case` consistently for variables and facts. - Use `snake_case` consistently for variables and facts.
- Follow existing naming families such as `common_packages`, `profile_packages`, `host_packages`, and `host_dotfiles`. - Follow existing families such as `common_packages`, `profile_packages`, `host_packages`, `common_dotfiles`, `workstation_dotfiles`, `server_dotfiles`, and `host_dotfiles`.
- Keep booleans as booleans, not quoted strings. - Keep booleans as booleans, not quoted strings.
- Keep structured data as YAML collections, not comma-separated strings. - Keep structured data as YAML collections, not comma-separated strings.
- Guard optional collections and maps with `default([])` and `default({})`. - Guard optional collections/maps with `default([])` and `default({})`.
- Guard optional strings with `default('')`. - Guard optional strings with `default('')`.
- Build user paths from `{{ user_home }}` instead of hardcoding home directories. - Build user paths from `{{ user_home }}` instead of hardcoding home directories.
- Prefer explicit derived facts with `set_fact` only when reuse improves clarity.
### Naming conventions
- Role names stay lowercase with underscores.
- Inventory groups and matching var files should stay semantically aligned.
- Host-specific overrides belong in `host_vars`, not shared group files. - Host-specific overrides belong in `host_vars`, not shared group files.
- New variables should fit existing naming patterns instead of introducing one-off aliases.
### Error handling and safety ### Error handling and safety
- Guard OS-specific or profile-specific behavior with `when` clauses. - Guard OS-specific or profile-specific behavior with `when` clauses.
- Prefer explicit inputs over assumptions about host state. - Prefer explicit inputs over assumptions about host state.
- Do not suppress failures without a clear operational reason.
- Use `failed_when: false` only for intentional probes or best-effort detection. - Use `failed_when: false` only for intentional probes or best-effort detection.
- Use `no_log: true` for secrets, tokens, passwords, and sensitive command results. - Use `no_log: true` for secrets, passwords, and sensitive command results.
- Keep tasks non-interactive and automation-safe. - Keep tasks non-interactive and automation-safe.
- Avoid destructive operations in user homes unless the request clearly requires them. - Avoid destructive operations in user homes unless clearly required.
- Fail early with `ansible.builtin.fail` when prerequisites such as architecture or required metadata are missing. - Fail early with `ansible.builtin.fail` when prerequisites such as architecture, release metadata, or session bus data are missing.
- For firewall changes, allow required access before enabling the firewall.
### Shell and script conventions ### Shell, scripts, and external code
- Prefer POSIX `sh` for simple login/session/bootstrap scripts. - Prefer POSIX `sh` for simple scripts; use Bash only when Bash features are required.
- Use Bash only when Bash features are actually required; then use `#!/usr/bin/env bash`.
- Quote variable expansions unless intentional word splitting is required. - Quote variable expansions unless intentional word splitting is required.
- Keep helper functions small and focused.
- Exit with clear errors when required commands or files are missing.
- Preserve executable bits for deployed scripts where appropriate. - Preserve executable bits for deployed scripts where appropriate.
- If you add Python later, follow standard-library, third-party, local import grouping.
### Imports and external code - Treat vendored tmux plugins as upstream code unless the task explicitly targets them.
- There are no Python import conventions to optimize for here; most changes are YAML, Jinja, and shell.
- If you add Python later, follow standard-library, third-party, local import grouping and keep modules small.
- Treat `dotfiles/common/.tmux/plugins/` as vendored upstream code unless the task explicitly targets it.
- Prefer changing first-party wrapper/config files before patching vendored plugin internals.
## Editing guidance by area ## Editing guidance by area
- `ansible/site.yml`: keep it small and orchestration-focused. - `ansible/site.yml`: keep it small and orchestration-focused.
@@ -196,15 +152,6 @@ Preferred for role, template, or vars changes:
ansible-playbook ansible/site.yml --limit <host> --check --diff ansible-playbook ansible/site.yml --limit <host> --check --diff
``` ```
Useful supporting checks:
```bash
ansible-inventory --graph
ansible-inventory --host <host>
ansible-lint ansible/site.yml
yamllint ansible/
sh -n scripts/bootstrap_mail.sh
```
## Agent workflow expectations ## Agent workflow expectations
- Read the relevant inventory, vars, role tasks, templates, and deployed dotfiles before editing. - Read the relevant inventory, vars, role tasks, templates, and deployed dotfiles before editing.
- Do not change unrelated files to "clean things up". - Do not change unrelated files to "clean things up".

79
README.md
View File

@@ -15,23 +15,25 @@ Il repository consente di gestire più sistemi operativi e profili macchina mant
# Architettura del progetto # Architettura del progetto
```text ```text
infra/ infra/
├── ansible/ ├── ansible/
│ ├── ansible.cfg │ ├── ansible.cfg
│ ├── site.yml │ ├── site.yml
│ ├── inventory/ │ ├── inventory/
│ │ ├── hosts.yml │ │ ├── hosts.yml
│ │ ├── group_vars/ │ │ ├── group_vars/
│ │ └── host_vars/ │ │ └── host_vars/
│ └── roles/ │ ├── templates/
│ │ └── roles/
├── dotfiles/ │
│ ├── common/ ├── dotfiles/
│ ├── desktop/ │ ├── common/
│ ├── workstation/ │ ├── desktop/
│ ├── ikaros/ │ ├── server/
│ └── nymph/ │ ├── workstation/
│ ├── ikaros/
│ └── nymph/
│ │
├── scripts/ ├── scripts/
├── secrets/ ├── secrets/
@@ -54,8 +56,8 @@ Il repository modella attualmente tre tipologie di profilo.
Nota sullo stato attuale del playbook principale: Nota sullo stato attuale del playbook principale:
- `ansible/site.yml` applica oggi in automatico il profilo desktop su host Void Linux - `ansible/site.yml` applica oggi in automatico il profilo desktop su host Void Linux
- `ansible/site.yml` applica anche il profilo `ubuntu_workstation` con un setup minimo basato su apt, systemd e GNOME - `ansible/site.yml` applica anche il profilo `ubuntu_workstation` con setup apt, systemd, dotfiles workstation, firewall UFW e integrazione GNOME
- `ansible/site.yml` applica anche il profilo `ubuntu_server` con una baseline minima basata su apt, systemd e profilo server - `ansible/site.yml` applica anche il profilo `ubuntu_server` con baseline apt, systemd, dotfiles server e firewall UFW
## Desktop ## Desktop
@@ -100,13 +102,16 @@ Macchina:
Questo profilo è pensato per sviluppo e lavoro. Questo profilo è pensato per sviluppo e lavoro.
Il profilo workstation Ubuntu e ora agganciato al playbook principale con una prima implementazione minima. Il profilo workstation Ubuntu e agganciato al playbook principale e include gia una base operativa per uso desktop e sviluppo.
Lo stato attuale del profilo workstation include: Lo stato attuale del profilo workstation include:
- installazione pacchetti base Ubuntu via apt - installazione pacchetti base Ubuntu via apt
- abilitazione dei servizi systemd dichiarati in inventory/group vars - installazione e configurazione di Docker dal repository ufficiale
- predisposizione delle directory utente minime per il profilo workstation GNOME - gestione dei dotfiles workstation e rendering dei template dedicati
- installazione di Google Chrome e pacchetti Snap workstation
- gestione delle estensioni GNOME da website e dello stato desiderato delle estensioni abilitate
- attivazione del firewall UFW
--- ---
@@ -124,13 +129,15 @@ Macchina:
- `prometheus` - `prometheus`
Profilo minimale orientato a servizi server. Profilo orientato a servizi server e gestione di dotfiles dedicati.
Lo stato attuale del profilo server include: Lo stato attuale del profilo server include:
- installazione pacchetti base Ubuntu via apt - installazione pacchetti base Ubuntu via apt
- installazione e configurazione di Docker dal repository ufficiale
- abilitazione dei servizi systemd dichiarati in inventory/group vars - abilitazione dei servizi systemd dichiarati in inventory/group vars
- esecuzione del profilo server minimale - copia dei dotfiles server e rendering dei template server
- attivazione del firewall UFW con regola SSH esplicita
--- ---
@@ -198,20 +205,21 @@ ubuntu_server -> packages_ubuntu + services_systemd + profile_server
Questo significa che, allo stato attuale: Questo significa che, allo stato attuale:
- i desktop Void (`ikaros`, `nymph`) restano il target operativo piu completo - i desktop Void (`ikaros`, `nymph`) restano il target operativo piu completo
- la workstation Ubuntu (`deadalus`) e ora gestita con una prima orchestrazione minima - la workstation Ubuntu (`deadalus`) e gestita con pacchetti, servizi, dotfiles, estensioni GNOME e firewall
- il server Ubuntu (`prometheus`) e ora agganciato al playbook principale con una baseline minima - il server Ubuntu (`prometheus`) e gestito con pacchetti, servizi, dotfiles server e firewall
# Dotfiles # Dotfiles
La directory `dotfiles/` contiene le configurazioni utente versionate. La directory `dotfiles/` contiene le configurazioni utente versionate.
```text ```text
dotfiles/ dotfiles/
├── common ├── common
├── desktop ├── desktop
├── workstation ├── server
├── ikaros ├── workstation
└── nymph ├── ikaros
└── nymph
``` ```
Le configurazioni sono applicate tramite Ansible e organizzate per livelli: Le configurazioni sono applicate tramite Ansible e organizzate per livelli:
@@ -260,8 +268,8 @@ Allo stato attuale questo comando:
- distribuisce i dotfiles comuni a tutti gli host - distribuisce i dotfiles comuni a tutti gli host
- per gli host Void applica pacchetti, servizi runit e profilo desktop i3 - per gli host Void applica pacchetti, servizi runit e profilo desktop i3
- per gli host `ubuntu_workstation` applica pacchetti Ubuntu, servizi systemd e profilo workstation GNOME minimo - per gli host `ubuntu_workstation` applica pacchetti Ubuntu, servizi systemd, profilo workstation GNOME, UFW, dotfiles, Snap e template dedicati
- per gli host `ubuntu_server` applica pacchetti Ubuntu, servizi systemd e profilo server minimale - per gli host `ubuntu_server` applica pacchetti Ubuntu, servizi systemd, profilo server, UFW, dotfiles e template dedicati
- carica `secrets/vault.yml` solo se presente - carica `secrets/vault.yml` solo se presente
Per validare prima di applicare: Per validare prima di applicare:
@@ -316,7 +324,6 @@ Questo consente di ricreare qualsiasi macchina partendo esclusivamente dal repos
Possibili evoluzioni future: Possibili evoluzioni future:
- completamento dell'orchestrazione per workstation Ubuntu e server Ubuntu
- hardening sicurezza server - hardening sicurezza server
- configurazione backup - configurazione backup
- testing automatico playbook - testing automatico playbook