mirror of
https://github.com/fscotto/infra.git
synced 2026-09-27 19:03:47 +00:00
Add English README
This commit is contained in:
Fabio Scotto di Santolo
523
README.it.md
Normal file
523
README.it.md
Normal file
@@ -0,0 +1,523 @@
|
|||||||
|
# Infra — Personal Infrastructure as Code
|
||||||
|
|
||||||
|
> **English version:** [README.md](README.md)
|
||||||
|
|
||||||
|
Questo repository contiene la configurazione **Infrastructure as Code (IaC)** utilizzata per gestire e mantenere allineate diverse macchine personali tramite **Ansible**.
|
||||||
|
|
||||||
|
L'obiettivo è avere **una singola fonte di verità** per:
|
||||||
|
|
||||||
|
- configurazione delle macchine
|
||||||
|
- pacchetti installati
|
||||||
|
- servizi di sistema
|
||||||
|
- configurazioni utente (dotfiles)
|
||||||
|
|
||||||
|
Il repository consente di gestire più sistemi operativi e profili macchina mantenendo una struttura modulare, riproducibile e idempotente.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Architettura del progetto
|
||||||
|
|
||||||
|
```text
|
||||||
|
infra/
|
||||||
|
├── ansible/
|
||||||
|
│ ├── ansible.cfg
|
||||||
|
│ ├── site.yml
|
||||||
|
│ ├── inventory/
|
||||||
|
│ │ ├── hosts.yml
|
||||||
|
│ │ ├── group_vars/
|
||||||
|
│ │ └── host_vars/
|
||||||
|
│ ├── templates/
|
||||||
|
│ └── roles/
|
||||||
|
│
|
||||||
|
├── dotfiles/
|
||||||
|
│ ├── common/
|
||||||
|
│ ├── desktop/
|
||||||
|
│ ├── fedora/
|
||||||
|
│ ├── ubuntu/
|
||||||
|
│ ├── server/
|
||||||
|
│ ├── workstation/
|
||||||
|
│ ├── workstation_dev_wsl/
|
||||||
|
│ └── nymph/
|
||||||
|
│
|
||||||
|
├── scripts/
|
||||||
|
├── secrets/
|
||||||
|
├── README.md
|
||||||
|
└── README.it.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Il repository è diviso in due componenti principali:
|
||||||
|
|
||||||
|
| Componente | Scopo |
|
||||||
|
| ---------- | -------------------------------------- |
|
||||||
|
| ansible | provisioning e configurazione macchine |
|
||||||
|
| dotfiles | configurazioni utente versionate |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Macchine gestite
|
||||||
|
|
||||||
|
Il repository modella attualmente host Fedora/GNOME, una workstation Fedora WSL e un server Ubuntu.
|
||||||
|
La composizione resta separata in assi indipendenti:
|
||||||
|
|
||||||
|
```text
|
||||||
|
common user environment
|
||||||
|
+ host-specific platform
|
||||||
|
+ role-specific software
|
||||||
|
+ independently selectable desktop
|
||||||
|
+ host hardware overrides
|
||||||
|
```
|
||||||
|
|
||||||
|
Matrice target:
|
||||||
|
|
||||||
|
| Host | Platform | Role | Desktop |
|
||||||
|
| ------------ | -------- | -------------------- | ------- |
|
||||||
|
| ikaros | Fedora | Personal workstation | GNOME |
|
||||||
|
| nymph | Fedora | Desktop laptop | GNOME |
|
||||||
|
| deadalus | Fedora WSL | Workstation dev | — |
|
||||||
|
| prometheus | Ubuntu | Server | — |
|
||||||
|
|
||||||
|
Regola operativa:
|
||||||
|
|
||||||
|
```text
|
||||||
|
ikaros must be boring
|
||||||
|
nymph is allowed to break
|
||||||
|
```
|
||||||
|
|
||||||
|
`ikaros` usa Fedora Workstation/GNOME come desktop personale stabile; `nymph` usa lo stesso
|
||||||
|
target Fedora Workstation/GNOME come laptop. I gruppi legacy `void` e `desktop` restano alias di
|
||||||
|
compatibilita per eventuali host Void futuri mentre i nuovi assi sono
|
||||||
|
`platform_*`, `role_*` e `desktop_*`.
|
||||||
|
|
||||||
|
Nota sullo stato attuale del playbook principale:
|
||||||
|
|
||||||
|
- `ansible/site.yml` applica oggi in automatico Fedora/GNOME su `ikaros` e `nymph`
|
||||||
|
- `ansible/site.yml` applica il profilo Fedora WSL alla workstation `deadalus`
|
||||||
|
- `ansible/site.yml` applica anche il profilo `ubuntu_server` con baseline apt, systemd, dotfiles server e firewall UFW
|
||||||
|
|
||||||
|
## Desktop
|
||||||
|
|
||||||
|
Target operativi:
|
||||||
|
|
||||||
|
- `ikaros`: Fedora Workstation + GNOME, desktop personale stabile/floating.
|
||||||
|
- `nymph`: Fedora Workstation + GNOME, laptop desktop con dotfiles desktop condivisi e GNOME lasciato al default Fedora.
|
||||||
|
|
||||||
|
Il profilo Void desktop resta disponibile come modello riutilizzabile per host
|
||||||
|
futuri e usa esclusivamente `desktop_environment: minimal`: Sway e il default,
|
||||||
|
mentre Niri si seleziona con il gruppo `desktop_niri`. GNOME e disponibile solo
|
||||||
|
sui target Fedora tramite `desktop_gnome`.
|
||||||
|
|
||||||
|
Lo stato attuale del profilo desktop include, tra le altre cose:
|
||||||
|
|
||||||
|
- dotfiles comuni e desktop
|
||||||
|
- sessioni Sway e Niri per eventuali host Void in modalita `minimal`
|
||||||
|
- `emptty` con default host-specific in modalita `minimal` e session file Wayland per `sway`
|
||||||
|
- pacchetti Void Linux e servizi runit; le liste pacchetti Void desktop sono separate per criterio:
|
||||||
|
- `void_packages_base` per il runtime sistema (init, kernel, audio core, networking, firewall, hw daemons)
|
||||||
|
- `desktop_common_packages` per l'infrastruttura condivisa
|
||||||
|
- `desktop_minimal_packages` per applicazioni GTK e `emptty`
|
||||||
|
- `desktop_sway_packages` per i binari specifici della sessione Sway
|
||||||
|
- `turnstile` per i servizi utente Void, incluso `ssh-agent`
|
||||||
|
- `ssh-agent` con socket stabile condiviso tra shell e SSH in `~/.local/state/ssh-agent/socket`
|
||||||
|
- Emacs usa una sola configurazione orientata a Org e authoring, condivisa da desktop Fedora/GNOME e workstation; Vim resta l'editor di sviluppo
|
||||||
|
- `tmux` con plugin gestiti da TPM al bootstrap del profilo desktop
|
||||||
|
- Flatpak con remoto Flathub
|
||||||
|
- GNOME Keyring e `udiskie` nella modalita minimale
|
||||||
|
- multi-monitor Void: sotto Sway è gestito da `kanshi`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workstation
|
||||||
|
|
||||||
|
La workstation `deadalus` usa Fedora in WSL sulla macchina Windows omonima, senza runtime Flatpak o Snap.
|
||||||
|
Il profilo è pensato per sviluppo e lavoro.
|
||||||
|
|
||||||
|
Nel modello Ansible usato qui, un singolo inventory host puo appartenere intenzionalmente a piu gruppi e quindi ricevere piu play nello stesso run: l'associazione non e `1 host = 1 play`, ma `host + gruppi = layering finale`.
|
||||||
|
|
||||||
|
Il profilo workstation e agganciato al playbook principale tramite:
|
||||||
|
|
||||||
|
- layer dev Fedora
|
||||||
|
- layer WSL dedicato per sviluppo con `systemd`
|
||||||
|
|
||||||
|
Lo stato attuale del profilo workstation include:
|
||||||
|
|
||||||
|
- installazione pacchetti base Fedora via dnf
|
||||||
|
- installazione e configurazione di Docker dal repository ufficiale
|
||||||
|
- gestione dei dotfiles workstation e rendering dei template dev condivisi
|
||||||
|
- preparazione di Fedora WSL con `systemd` per il toolchain di sviluppo
|
||||||
|
- attivazione del firewall `firewalld` sui target Fedora che dichiarano regole host-specifiche
|
||||||
|
|
||||||
|
Workflow WSL previsto:
|
||||||
|
|
||||||
|
1. avviare Fedora WSL almeno una volta e completare la creazione dell'utente Linux
|
||||||
|
2. installare Ansible dentro la distribuzione WSL
|
||||||
|
3. lanciare il playbook dalla distribuzione su `deadalus` per configurare l'ambiente dev locale
|
||||||
|
4. usare VS Code con le estensioni Remote (`WSL`, `SSH`, `Dev Containers`) dal lato Windows
|
||||||
|
|
||||||
|
Le applicazioni Windows sono installate e gestite manualmente; il profilo WSL non installa componenti di remoting Python per esse.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Server
|
||||||
|
|
||||||
|
Sistema operativo:
|
||||||
|
|
||||||
|
- Ubuntu LTS
|
||||||
|
|
||||||
|
Configurazione:
|
||||||
|
|
||||||
|
- nessun ambiente grafico
|
||||||
|
|
||||||
|
Macchina:
|
||||||
|
|
||||||
|
- `prometheus`
|
||||||
|
|
||||||
|
Profilo orientato a servizi server e gestione di dotfiles dedicati.
|
||||||
|
|
||||||
|
Lo stato attuale del profilo server include:
|
||||||
|
|
||||||
|
- installazione pacchetti base Ubuntu via apt
|
||||||
|
- installazione e configurazione di Docker dal repository ufficiale
|
||||||
|
- abilitazione dei servizi systemd dichiarati in inventory/group vars
|
||||||
|
- copia dei dotfiles server e rendering dei template server, incluso il `docker-compose.yml` dello stack servizi
|
||||||
|
- attivazione del firewall UFW con regola SSH esplicita
|
||||||
|
- apertura delle porte Syncthing `22000/tcp`, `22000/udp` e `21027/udp`, lasciando la GUI non esposta direttamente su UFW
|
||||||
|
|
||||||
|
Utente del profilo server:
|
||||||
|
|
||||||
|
- il profilo usa `server_username`, `server_user_group` e `server_user_home` definiti in `ansible/inventory/group_vars/server.yml`
|
||||||
|
- per default `server_username` eredita `username`, ma puo essere sovrascritto per tutti gli host server via inventory oppure a runtime con extra vars
|
||||||
|
- esempio override da CLI:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ansible-playbook ansible/site.yml --limit prometheus -e server_username=myuser
|
||||||
|
```
|
||||||
|
|
||||||
|
- se necessario puoi passare anche:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ansible-playbook ansible/site.yml --limit prometheus -e server_username=myuser -e server_user_group=mygroup -e server_user_home=/srv/myuser
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Composizione della configurazione
|
||||||
|
|
||||||
|
Emacs è abilitato sui profili Fedora/GNOME e workstation; la configurazione canonica è distribuita da `dotfiles_common`, con Org in `~/Org/`, template versionati e export PDF/HTML/Markdown/DOCX/ODT. Per abilitarlo temporaneamente su un altro profilo:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ansible-playbook ansible/site.yml --limit <host> --tags emacs -e emacs_enabled=true
|
||||||
|
```
|
||||||
|
|
||||||
|
La configurazione finale di una macchina è ottenuta combinando più livelli.
|
||||||
|
|
||||||
|
```text
|
||||||
|
common configuration
|
||||||
|
+ platform configuration
|
||||||
|
+ role configuration
|
||||||
|
+ desktop configuration
|
||||||
|
+ host overrides
|
||||||
|
```
|
||||||
|
|
||||||
|
Esempi correnti:
|
||||||
|
|
||||||
|
```text
|
||||||
|
ikaros -> common + platform_fedora + role_personal_workstation + graphical_desktop + desktop_gnome + ikaros
|
||||||
|
nymph -> common + platform_fedora + graphical_desktop + desktop_gnome + nymph
|
||||||
|
deadalus -> common + platform_fedora + workstation_dev_fedora + workstation_dev_wsl + deadalus
|
||||||
|
```
|
||||||
|
|
||||||
|
Questo approccio consente di:
|
||||||
|
|
||||||
|
- mantenere configurazioni condivise
|
||||||
|
- applicare override specifici per host
|
||||||
|
- evitare duplicazioni
|
||||||
|
- riutilizzare il profilo Void corrente su un host futuro assegnandolo a
|
||||||
|
`platform_void + graphical_desktop + desktop_sway`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Ruoli Ansible
|
||||||
|
|
||||||
|
I principali ruoli attualmente presenti sono:
|
||||||
|
|
||||||
|
| Role | Descrizione |
|
||||||
|
| ------------------------- | ----------------------------------- |
|
||||||
|
| base | configurazione base comune |
|
||||||
|
| packages_void | installazione pacchetti su Void |
|
||||||
|
| packages_freebsd | installazione pacchetti su FreeBSD via pkg |
|
||||||
|
| packages_ubuntu | installazione pacchetti su Ubuntu |
|
||||||
|
| packages_fedora | installazione pacchetti su Fedora |
|
||||||
|
| services_runit | gestione servizi runit |
|
||||||
|
| services_systemd | gestione servizi systemd |
|
||||||
|
| services_freebsd | gestione servizi FreeBSD dichiarati per host |
|
||||||
|
| profile_desktop_common | bootstrap desktop Void condiviso |
|
||||||
|
| profile_desktop_gnome | dotfiles desktop condivisi per Fedora/GNOME |
|
||||||
|
| profile_desktop_sway | sessione desktop sway / SwayFX (Wayland) |
|
||||||
|
| profile_desktop_niri | sessione desktop Niri su Void (Wayland) |
|
||||||
|
| profile_desktop_host | override desktop specifici per host |
|
||||||
|
| profile_personal_workstation | layer stabile per workstation personale |
|
||||||
|
| profile_workstation_dev_common | configurazione dev workstation condivisa |
|
||||||
|
| profile_workstation_dev_wsl | configurazione WSL condivisa per sviluppo |
|
||||||
|
| profile_server | configurazione server |
|
||||||
|
| dotfiles_common | distribuzione dotfiles comuni |
|
||||||
|
| dotfiles | distribuzione configurazioni utente |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Stato attuale del playbook principale
|
||||||
|
|
||||||
|
Il playbook `ansible/site.yml` e attualmente composto da blocchi per asse:
|
||||||
|
|
||||||
|
```text
|
||||||
|
all -> dotfiles_common
|
||||||
|
platform_void -> packages_void + services_runit
|
||||||
|
platform_void & graphical_desktop -> profile_desktop_common + profile_desktop_sway + profile_desktop_niri + profile_desktop_host
|
||||||
|
platform_freebsd -> packages_freebsd + services_freebsd
|
||||||
|
platform_fedora -> packages_fedora + services_systemd
|
||||||
|
platform_fedora & role_personal_workstation -> profile_personal_workstation
|
||||||
|
platform_fedora & desktop_gnome -> profile_desktop_gnome
|
||||||
|
workstation_dev_fedora -> profile_workstation_dev_common
|
||||||
|
workstation_dev_wsl -> profile_workstation_dev_wsl (dopo platform_fedora + workstation_dev_fedora)
|
||||||
|
ubuntu_server -> packages_ubuntu + services_systemd + profile_server
|
||||||
|
```
|
||||||
|
|
||||||
|
Questo significa che, allo stato attuale:
|
||||||
|
|
||||||
|
- `ikaros` riceve Fedora Workstation/GNOME come target desktop personale stabile
|
||||||
|
- `nymph` riceve Fedora Workstation/GNOME come target laptop
|
||||||
|
- il profilo Void resta selezionabile tramite `platform_void + graphical_desktop` per host futuri
|
||||||
|
- `deadalus` riceve il profilo Fedora WSL tramite play dev dedicati
|
||||||
|
- il server Ubuntu (`prometheus`) e gestito con pacchetti, servizi, dotfiles server e firewall
|
||||||
|
- lo stack container server include `navidrome`, `postgres`, `gitea`, `nginx-proxy-manager` e `syncthing`, con GUI Syncthing raggiungibile tramite la rete Docker `web`
|
||||||
|
|
||||||
|
# Dotfiles
|
||||||
|
|
||||||
|
La directory `dotfiles/` contiene le configurazioni utente versionate.
|
||||||
|
|
||||||
|
```text
|
||||||
|
dotfiles/
|
||||||
|
├── common
|
||||||
|
├── desktop
|
||||||
|
├── server
|
||||||
|
├── fedora
|
||||||
|
├── ubuntu
|
||||||
|
├── workstation
|
||||||
|
├── workstation_dev_wsl
|
||||||
|
└── nymph
|
||||||
|
```
|
||||||
|
|
||||||
|
Le configurazioni sono applicate tramite Ansible e organizzate per livelli:
|
||||||
|
|
||||||
|
| Livello | Scopo |
|
||||||
|
| ------- | -------------------------------- |
|
||||||
|
| common | configurazioni condivise |
|
||||||
|
| profile | configurazioni per tipo macchina |
|
||||||
|
| host | override specifici |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Requisiti
|
||||||
|
|
||||||
|
Per utilizzare il repository sono necessari:
|
||||||
|
|
||||||
|
- Python 3
|
||||||
|
- Ansible
|
||||||
|
- `ansible-lint`
|
||||||
|
- `yamllint`
|
||||||
|
- `shellcheck`
|
||||||
|
- collection definite in `ansible/collections/requirements.yml`
|
||||||
|
- accesso locale o SSH alle macchine target, in base a come e definito l'inventory
|
||||||
|
|
||||||
|
Installazione base:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 -m pip install ansible ansible-lint yamllint shellcheck-py
|
||||||
|
ansible-galaxy collection install -r ansible/collections/requirements.yml
|
||||||
|
```
|
||||||
|
|
||||||
|
Gestione segreti:
|
||||||
|
|
||||||
|
- il repository supporta il caricamento opzionale di `secrets/vault.yml`
|
||||||
|
- il repository supporta anche `secrets/vault.local.yml` per override locali non versionati
|
||||||
|
- `secrets/vault.yml.example` funge da template/esempio
|
||||||
|
- se `secrets/vault.yml` non e presente, il playbook continua comunque senza caricare variabili locali opzionali
|
||||||
|
- se `secrets/.vault_pass.gpg` esiste viene usato automaticamente per sbloccare i vault tramite `gpg`; in alternativa resta supportato `secrets/.vault_pass` come fallback legacy locale; se nessuno dei due file esiste Ansible richiede la password in modo interattivo
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Utilizzo
|
||||||
|
|
||||||
|
Eseguire il playbook principale:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ansible-playbook ansible/site.yml
|
||||||
|
```
|
||||||
|
|
||||||
|
Allo stato attuale questo comando:
|
||||||
|
|
||||||
|
- distribuisce i dotfiles comuni a tutti gli host
|
||||||
|
- per `platform_void` applica pacchetti Void e servizi runit
|
||||||
|
- per `platform_void + graphical_desktop` applica bootstrap desktop condiviso, sessioni Sway/Niri e override specifici per host
|
||||||
|
- per `platform_freebsd` non applica nulla finche il gruppo resta senza host
|
||||||
|
- per `platform_fedora` applica pacchetti Fedora e servizi systemd a `ikaros`, `nymph` e `deadalus`
|
||||||
|
- per `platform_fedora & role_personal_workstation` applica il layer personale a `ikaros`
|
||||||
|
- per `platform_fedora & desktop_gnome` applica il profilo GNOME a `ikaros` e `nymph`
|
||||||
|
- per `workstation_dev_wsl` applica i tweak WSL dopo il layer Fedora a `deadalus`, escludendo Flatpak e Snap
|
||||||
|
- per gli host `ubuntu_server` applica pacchetti Ubuntu, servizi systemd, profilo server, UFW, dotfiles e template dedicati
|
||||||
|
- non riavvia automaticamente il display manager
|
||||||
|
- carica `secrets/vault.yml` solo se presente
|
||||||
|
- carica `secrets/vault.local.yml` solo se presente, dopo `vault.yml`, cosi gli override locali hanno precedenza
|
||||||
|
|
||||||
|
Per validare prima di applicare:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ansible-playbook ansible/site.yml --syntax-check
|
||||||
|
ansible-playbook ansible/site.yml --limit ikaros,nymph --check --diff
|
||||||
|
ansible-playbook ansible/site.yml --limit ikaros --check --diff
|
||||||
|
ansible-playbook ansible/site.yml --limit nymph --check --diff
|
||||||
|
ansible-playbook ansible/site.yml --limit deadalus --check --diff
|
||||||
|
ansible-playbook ansible/site.yml --limit prometheus --check --diff
|
||||||
|
ansible-lint ansible/site.yml
|
||||||
|
ansible-lint ansible/roles
|
||||||
|
yamllint ansible/
|
||||||
|
```
|
||||||
|
|
||||||
|
Per testare un override dell'utente server senza modificare l'inventory:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ansible-playbook ansible/site.yml --limit prometheus --check --diff -e server_username=myuser
|
||||||
|
```
|
||||||
|
|
||||||
|
Per validazioni piu mirate:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ansible-playbook ansible/site.yml --limit <host> --tags <tag1>,<tag2> --check --diff
|
||||||
|
ansible-playbook ansible/site.yml --limit <host> --start-at-task "<task name>" --check --diff
|
||||||
|
ansible-lint ansible/roles/<role>
|
||||||
|
yamllint ansible/path/to/file.yml
|
||||||
|
docker compose -f /opt/docker/server/docker-compose.yml config
|
||||||
|
```
|
||||||
|
|
||||||
|
## Tag supportati dal playbook
|
||||||
|
|
||||||
|
Per vedere l'elenco reale aggiornato dei tag disponibili:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ansible-playbook ansible/site.yml --list-tags
|
||||||
|
```
|
||||||
|
|
||||||
|
Allo stato attuale `ansible/site.yml` espone questi tag:
|
||||||
|
|
||||||
|
| Tag | Scopo | Ambito principale |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `always` | pre-task sempre eseguiti, inclusi caricamento vault e validazioni preliminari | common |
|
||||||
|
| `ai_agents` | installazione agenti AI condivisi | Fedora, WSL |
|
||||||
|
| `dotfiles` | distribuzione/configurazione dotfiles | tutti i profili |
|
||||||
|
| `dotfiles:common` | dotfiles comuni condivisi | common, workstation, server |
|
||||||
|
| `dotfiles:desktop` | dotfiles desktop | desktop Void, Fedora/GNOME |
|
||||||
|
| `dotfiles:host` | override host-specifici desktop | desktop Void |
|
||||||
|
| `dotfiles:server` | dotfiles dedicati al profilo server | server |
|
||||||
|
| `dotfiles:workstation` | dotfiles dedicati alle workstation | personal workstation, WSL |
|
||||||
|
| `emptty` | gestione display manager `emptty` | desktop Void |
|
||||||
|
| `display-manager` | gestione del display manager `emptty` | desktop Void |
|
||||||
|
| `emacs` | configurazione Emacs condivisa e dipendenze di authoring | desktop Fedora/GNOME e workstation |
|
||||||
|
| `fonts` | installazione font | Fedora |
|
||||||
|
| `fzf` | configurazione FZF | dotfiles comuni |
|
||||||
|
| `git` | configurazione Git e GPG desktop | Fedora/GNOME, desktop Void |
|
||||||
|
| `gnome` | configurazione host GNOME | Fedora/GNOME desktop |
|
||||||
|
| `sway` | sessione/configurazione sway / SwayFX (Wayland) | desktop Void |
|
||||||
|
| `niri` | sessione/configurazione Niri (Wayland) | desktop Void |
|
||||||
|
| `npm` | installazione pacchetti npm globali | Fedora/GNOME, desktop Void, WSL |
|
||||||
|
| `nvidia` | componenti NVIDIA desktop | desktop Void |
|
||||||
|
| `packages` | installazione e aggiornamento pacchetti | tutti i profili |
|
||||||
|
| `portal` | configurazione xdg-desktop-portal | desktop Void |
|
||||||
|
| `services` | gestione servizi runit/systemd | tutti i profili |
|
||||||
|
| `theme` | configurazione del tema GTK/Qt | desktop Void |
|
||||||
|
| `tmux` | configurazione e plugin tmux | desktop Fedora/Void, WSL |
|
||||||
|
| `vim` | configurazione Vim | dotfiles comuni |
|
||||||
|
| `wsl` | bootstrap e configurazione WSL | WSL |
|
||||||
|
|
||||||
|
Esempi pratici:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ansible-playbook ansible/site.yml --limit nymph --tags dotfiles:desktop,gnome --check --diff
|
||||||
|
ansible-playbook ansible/site.yml --limit ikaros --tags gnome --check --diff
|
||||||
|
ansible-playbook ansible/site.yml --limit prometheus --tags services,dotfiles:server --check --diff
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Bootstrap di una nuova macchina
|
||||||
|
|
||||||
|
Una nuova macchina può essere inizializzata con i seguenti passaggi:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone <repo>
|
||||||
|
cd <repo-dir>
|
||||||
|
ansible-galaxy collection install -r ansible/collections/requirements.yml
|
||||||
|
ansible-playbook ansible/site.yml
|
||||||
|
```
|
||||||
|
|
||||||
|
Dopo l'esecuzione del playbook la macchina verra configurata secondo il profilo definito e i ruoli attualmente orchestrati.
|
||||||
|
|
||||||
|
Per aggiungere un nuovo host Void che riusa il profilo desktop preservato:
|
||||||
|
|
||||||
|
1. aggiungere l'host a `platform_void`;
|
||||||
|
2. aggiungerlo a `graphical_desktop`;
|
||||||
|
3. usare Sway, oppure aggiungerlo a `desktop_niri` per selezionare Niri;
|
||||||
|
4. lasciare eventuali dettagli hardware in `host_vars/<host>.yml`.
|
||||||
|
|
||||||
|
I gruppi legacy `void` e `desktop` sono parent di compatibilita, quindi un host
|
||||||
|
in `platform_void` e `graphical_desktop` continua a ricevere anche le variabili
|
||||||
|
Void e desktop esistenti.
|
||||||
|
|
||||||
|
Per prove in VM sono disponibili gruppi di esempio in
|
||||||
|
`ansible/inventory/examples/platform-test-hosts.yml`, da passare esplicitamente
|
||||||
|
con `-i` insieme all'inventory principale.
|
||||||
|
|
||||||
|
Per il flusso mail desktop esiste inoltre uno script dedicato:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
scripts/bootstrap_mail.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
Lo script si occupa del bootstrap dei secret nel keyring, del primo sync con `mbsync` e dell'inizializzazione di `mu` usando la configurazione mail generata dai template.
|
||||||
|
|
||||||
|
Se modifichi questo script, valida almeno con:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sh -n scripts/bootstrap_mail.sh
|
||||||
|
shellcheck scripts/bootstrap_mail.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Filosofia del progetto
|
||||||
|
|
||||||
|
Il repository segue alcuni principi chiave:
|
||||||
|
|
||||||
|
- Infrastructure as Code
|
||||||
|
- configurazione dichiarativa
|
||||||
|
- idempotenza
|
||||||
|
- ambienti riproducibili
|
||||||
|
- separazione tra configurazione sistema e configurazione utente
|
||||||
|
|
||||||
|
Questo consente di ricreare qualsiasi macchina partendo esclusivamente dal repository.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Roadmap
|
||||||
|
|
||||||
|
Possibili evoluzioni future:
|
||||||
|
|
||||||
|
- hardening sicurezza server
|
||||||
|
- configurazione backup
|
||||||
|
- testing automatico playbook
|
||||||
|
- integrazione CI
|
||||||
|
- supporto ad altre distribuzioni Linux
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Licenza
|
||||||
|
|
||||||
|
Questo progetto è distribuito sotto licenza **LGPL-3.0**.
|
||||||
488
README.md
488
README.md
@@ -1,24 +1,14 @@
|
|||||||
# Infra — Personal Infrastructure as Code
|
# Infra — Personal Infrastructure as Code
|
||||||
|
|
||||||
Questo repository contiene la configurazione **Infrastructure as Code (IaC)** utilizzata per gestire e mantenere allineate diverse macchine personali tramite **Ansible**.
|
> **Italian version:** [README.it.md](README.it.md)
|
||||||
|
|
||||||
L'obiettivo è avere **una singola fonte di verità** per:
|
This is my Ansible repo for keeping my personal machines and dotfiles in sync. It is the source of truth for packages, services, and user configuration. The setup is meant to stay modular, reproducible, and idempotent without getting too clever.
|
||||||
|
|
||||||
- configurazione delle macchine
|
## Layout
|
||||||
- pacchetti installati
|
|
||||||
- servizi di sistema
|
|
||||||
- configurazioni utente (dotfiles)
|
|
||||||
|
|
||||||
Il repository consente di gestire più sistemi operativi e profili macchina mantenendo una struttura modulare, riproducibile e idempotente.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Architettura del progetto
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
infra/
|
infra/
|
||||||
├── ansible/
|
├── ansible/
|
||||||
│ ├── ansible.cfg
|
|
||||||
│ ├── site.yml
|
│ ├── site.yml
|
||||||
│ ├── inventory/
|
│ ├── inventory/
|
||||||
│ │ ├── hosts.yml
|
│ │ ├── hosts.yml
|
||||||
@@ -26,7 +16,6 @@ infra/
|
|||||||
│ │ └── host_vars/
|
│ │ └── host_vars/
|
||||||
│ ├── templates/
|
│ ├── templates/
|
||||||
│ └── roles/
|
│ └── roles/
|
||||||
│
|
|
||||||
├── dotfiles/
|
├── dotfiles/
|
||||||
│ ├── common/
|
│ ├── common/
|
||||||
│ ├── desktop/
|
│ ├── desktop/
|
||||||
@@ -36,176 +25,94 @@ infra/
|
|||||||
│ ├── workstation/
|
│ ├── workstation/
|
||||||
│ ├── workstation_dev_wsl/
|
│ ├── workstation_dev_wsl/
|
||||||
│ └── nymph/
|
│ └── nymph/
|
||||||
│
|
|
||||||
├── scripts/
|
├── scripts/
|
||||||
├── secrets/
|
├── secrets/
|
||||||
└── README.md
|
├── README.md
|
||||||
|
└── README.it.md
|
||||||
```
|
```
|
||||||
|
|
||||||
Il repository è diviso in due componenti principali:
|
- `ansible/` holds provisioning and host configuration.
|
||||||
|
- `dotfiles/` holds versioned user configuration.
|
||||||
|
|
||||||
| Componente | Scopo |
|
## Managed machines
|
||||||
| ---------- | -------------------------------------- |
|
|
||||||
| ansible | provisioning e configurazione macchine |
|
|
||||||
| dotfiles | configurazioni utente versionate |
|
|
||||||
|
|
||||||
---
|
The repo currently covers Fedora/GNOME desktops, one Fedora WSL workstation, and an Ubuntu server. Configuration is layered instead of being tied to host names:
|
||||||
|
|
||||||
# Macchine gestite
|
|
||||||
|
|
||||||
Il repository modella attualmente host Fedora/GNOME, una workstation Fedora WSL e un server Ubuntu.
|
|
||||||
La composizione resta separata in assi indipendenti:
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
common user environment
|
common user environment
|
||||||
+ host-specific platform
|
+ platform-specific setup
|
||||||
+ role-specific software
|
+ role-specific software
|
||||||
+ independently selectable desktop
|
+ independently selected desktop
|
||||||
+ host hardware overrides
|
+ host overrides
|
||||||
```
|
```
|
||||||
|
|
||||||
Matrice target:
|
| Host | Platform | Role | Desktop |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
| Host | Platform | Role | Desktop |
|
| `ikaros` | Fedora | Personal workstation | GNOME |
|
||||||
| ------------ | -------- | -------------------- | ------- |
|
| `nymph` | Fedora | Desktop laptop | GNOME |
|
||||||
| ikaros | Fedora | Personal workstation | GNOME |
|
| `deadalus` | Fedora WSL | Development workstation | — |
|
||||||
| nymph | Fedora | Desktop laptop | GNOME |
|
| `prometheus` | Ubuntu | Server | — |
|
||||||
| deadalus | Fedora WSL | Workstation dev | — |
|
|
||||||
| prometheus | Ubuntu | Server | — |
|
|
||||||
|
|
||||||
Regola operativa:
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
ikaros must be boring
|
ikaros must be boring
|
||||||
nymph is allowed to break
|
nymph is allowed to break
|
||||||
```
|
```
|
||||||
|
|
||||||
`ikaros` usa Fedora Workstation/GNOME come desktop personale stabile; `nymph` usa lo stesso
|
`ikaros` is the stable personal Fedora/GNOME desktop. `nymph` is the laptop and gets the same shared desktop dotfiles while GNOME itself stays close to the Fedora defaults. The legacy `void` and `desktop` groups are compatibility parents; the main axes are `platform_*`, `role_*`, and `desktop_*`.
|
||||||
target Fedora Workstation/GNOME come laptop. I gruppi legacy `void` e `desktop` restano alias di
|
|
||||||
compatibilita per eventuali host Void futuri mentre i nuovi assi sono
|
|
||||||
`platform_*`, `role_*` e `desktop_*`.
|
|
||||||
|
|
||||||
Nota sullo stato attuale del playbook principale:
|
## Desktop profiles
|
||||||
|
|
||||||
- `ansible/site.yml` applica oggi in automatico Fedora/GNOME su `ikaros` e `nymph`
|
- `ikaros`: stable Fedora Workstation + GNOME desktop.
|
||||||
- `ansible/site.yml` applica il profilo Fedora WSL alla workstation `deadalus`
|
- `nymph`: Fedora Workstation + GNOME laptop.
|
||||||
- `ansible/site.yml` applica anche il profilo `ubuntu_server` con baseline apt, systemd, dotfiles server e firewall UFW
|
- Void desktops stay available as reusable future profiles through `platform_void + graphical_desktop`.
|
||||||
|
|
||||||
## Desktop
|
Void uses `desktop_environment: minimal`. Sway is the normal session; add a host to `desktop_niri` to select Niri. GNOME is only handled on Fedora through `desktop_gnome`.
|
||||||
|
|
||||||
Target operativi:
|
The desktop setup includes shared desktop dotfiles, Sway/Niri support for future Void hosts, `emptty`, `turnstile` user services, a stable ssh-agent socket at `~/.local/state/ssh-agent/socket`, Emacs authoring config, tmux bootstrapped through TPM, Flatpak, GNOME Keyring, Udiskie, and `kanshi` for Sway multi-monitor setups.
|
||||||
|
|
||||||
- `ikaros`: Fedora Workstation + GNOME, desktop personale stabile/floating.
|
Void package buckets stay separate on purpose:
|
||||||
- `nymph`: Fedora Workstation + GNOME, laptop desktop con dotfiles desktop condivisi e GNOME lasciato al default Fedora.
|
|
||||||
|
|
||||||
Il profilo Void desktop resta disponibile come modello riutilizzabile per host
|
- `void_packages_base`: system runtime and services.
|
||||||
futuri e usa esclusivamente `desktop_environment: minimal`: Sway e il default,
|
- `desktop_common_packages`: shared GUI infrastructure.
|
||||||
mentre Niri si seleziona con il gruppo `desktop_niri`. GNOME e disponibile solo
|
- `desktop_minimal_packages`: GTK applications and `emptty`.
|
||||||
sui target Fedora tramite `desktop_gnome`.
|
- `desktop_sway_packages`: Sway-only binaries.
|
||||||
|
|
||||||
Lo stato attuale del profilo desktop include, tra le altre cose:
|
|
||||||
|
|
||||||
- dotfiles comuni e desktop
|
|
||||||
- sessioni Sway e Niri per eventuali host Void in modalita `minimal`
|
|
||||||
- `emptty` con default host-specific in modalita `minimal` e session file Wayland per `sway`
|
|
||||||
- pacchetti Void Linux e servizi runit; le liste pacchetti Void desktop sono separate per criterio:
|
|
||||||
- `void_packages_base` per il runtime sistema (init, kernel, audio core, networking, firewall, hw daemons)
|
|
||||||
- `desktop_common_packages` per l'infrastruttura condivisa
|
|
||||||
- `desktop_minimal_packages` per applicazioni GTK e `emptty`
|
|
||||||
- `desktop_sway_packages` per i binari specifici della sessione Sway
|
|
||||||
- `turnstile` per i servizi utente Void, incluso `ssh-agent`
|
|
||||||
- `ssh-agent` con socket stabile condiviso tra shell e SSH in `~/.local/state/ssh-agent/socket`
|
|
||||||
- Emacs usa una sola configurazione orientata a Org e authoring, condivisa da desktop Fedora/GNOME e workstation; Vim resta l'editor di sviluppo
|
|
||||||
- `tmux` con plugin gestiti da TPM al bootstrap del profilo desktop
|
|
||||||
- Flatpak con remoto Flathub
|
|
||||||
- GNOME Keyring e `udiskie` nella modalita minimale
|
|
||||||
- multi-monitor Void: sotto Sway è gestito da `kanshi`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Workstation
|
## Workstation
|
||||||
|
|
||||||
La workstation `deadalus` usa Fedora in WSL sulla macchina Windows omonima, senza runtime Flatpak o Snap.
|
`deadalus` is the only workstation target. It is Fedora running in WSL on the Windows machine with the same name. Flatpak and Snap are explicitly kept out of this profile.
|
||||||
Il profilo è pensato per sviluppo e lavoro.
|
|
||||||
|
|
||||||
Nel modello Ansible usato qui, un singolo inventory host puo appartenere intenzionalmente a piu gruppi e quindi ricevere piu play nello stesso run: l'associazione non e `1 host = 1 play`, ma `host + gruppi = layering finale`.
|
The workstation receives two layers:
|
||||||
|
|
||||||
Il profilo workstation e agganciato al playbook principale tramite:
|
- Fedora development setup through `workstation_dev_fedora`.
|
||||||
|
- WSL setup with `systemd` through `workstation_dev_wsl`.
|
||||||
|
|
||||||
- layer dev Fedora
|
That gives it Fedora packages through DNF, Docker from the official repository, shared workstation dotfiles and templates, tmux helpers, and WSL systemd configuration. Windows applications are installed manually; the WSL profile does not manage Python remoting components for them.
|
||||||
- layer WSL dedicato per sviluppo con `systemd`
|
|
||||||
|
|
||||||
Lo stato attuale del profilo workstation include:
|
### WSL workflow
|
||||||
|
|
||||||
- installazione pacchetti base Fedora via dnf
|
1. Start Fedora WSL once and finish creating the Linux user.
|
||||||
- installazione e configurazione di Docker dal repository ufficiale
|
2. Install Ansible inside Fedora WSL.
|
||||||
- gestione dei dotfiles workstation e rendering dei template dev condivisi
|
3. Run the playbook from that distribution with `--limit deadalus`.
|
||||||
- preparazione di Fedora WSL con `systemd` per il toolchain di sviluppo
|
4. Use Windows-side VS Code with Remote WSL, Remote SSH, and Dev Containers if wanted.
|
||||||
- attivazione del firewall `firewalld` sui target Fedora che dichiarano regole host-specifiche
|
|
||||||
|
|
||||||
Workflow WSL previsto:
|
|
||||||
|
|
||||||
1. avviare Fedora WSL almeno una volta e completare la creazione dell'utente Linux
|
|
||||||
2. installare Ansible dentro la distribuzione WSL
|
|
||||||
3. lanciare il playbook dalla distribuzione su `deadalus` per configurare l'ambiente dev locale
|
|
||||||
4. usare VS Code con le estensioni Remote (`WSL`, `SSH`, `Dev Containers`) dal lato Windows
|
|
||||||
|
|
||||||
Le applicazioni Windows sono installate e gestite manualmente; il profilo WSL non installa componenti di remoting Python per esse.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Server
|
## Server
|
||||||
|
|
||||||
Sistema operativo:
|
`prometheus` is the Ubuntu LTS server. It has no graphical environment and gets server-specific dotfiles and templates.
|
||||||
|
|
||||||
- Ubuntu LTS
|
The server profile installs Ubuntu packages, Docker from the official repository, declared systemd services, UFW rules, and the server Compose stack. Syncthing ports `22000/tcp`, `22000/udp`, and `21027/udp` are opened; the Syncthing GUI is not directly opened in UFW.
|
||||||
|
|
||||||
Configurazione:
|
Server identity comes from `server_username`, `server_user_group`, and `server_user_home` in `ansible/inventory/group_vars/server.yml`. `server_username` defaults to `username`, but it can be overridden, for example:
|
||||||
|
|
||||||
- nessun ambiente grafico
|
|
||||||
|
|
||||||
Macchina:
|
|
||||||
|
|
||||||
- `prometheus`
|
|
||||||
|
|
||||||
Profilo orientato a servizi server e gestione di dotfiles dedicati.
|
|
||||||
|
|
||||||
Lo stato attuale del profilo server include:
|
|
||||||
|
|
||||||
- installazione pacchetti base Ubuntu via apt
|
|
||||||
- installazione e configurazione di Docker dal repository ufficiale
|
|
||||||
- abilitazione dei servizi systemd dichiarati in inventory/group vars
|
|
||||||
- copia dei dotfiles server e rendering dei template server, incluso il `docker-compose.yml` dello stack servizi
|
|
||||||
- attivazione del firewall UFW con regola SSH esplicita
|
|
||||||
- apertura delle porte Syncthing `22000/tcp`, `22000/udp` e `21027/udp`, lasciando la GUI non esposta direttamente su UFW
|
|
||||||
|
|
||||||
Utente del profilo server:
|
|
||||||
|
|
||||||
- il profilo usa `server_username`, `server_user_group` e `server_user_home` definiti in `ansible/inventory/group_vars/server.yml`
|
|
||||||
- per default `server_username` eredita `username`, ma puo essere sovrascritto per tutti gli host server via inventory oppure a runtime con extra vars
|
|
||||||
- esempio override da CLI:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
ansible-playbook ansible/site.yml --limit prometheus -e server_username=myuser
|
ansible-playbook ansible/site.yml --limit prometheus -e server_username=myuser
|
||||||
|
ansible-playbook ansible/site.yml --limit prometheus \
|
||||||
|
-e server_username=myuser -e server_user_group=mygroup \
|
||||||
|
-e server_user_home=/srv/myuser
|
||||||
```
|
```
|
||||||
|
|
||||||
- se necessario puoi passare anche:
|
## How layering works
|
||||||
|
|
||||||
```bash
|
A host can intentionally belong to more than one inventory group. The final configuration is the combination of the host and its groups, not a one-host/one-play mapping.
|
||||||
ansible-playbook ansible/site.yml --limit prometheus -e server_username=myuser -e server_user_group=mygroup -e server_user_home=/srv/myuser
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Composizione della configurazione
|
|
||||||
|
|
||||||
Emacs è abilitato sui profili Fedora/GNOME e workstation; la configurazione canonica è distribuita da `dotfiles_common`, con Org in `~/Org/`, template versionati e export PDF/HTML/Markdown/DOCX/ODT. Per abilitarlo temporaneamente su un altro profilo:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ansible-playbook ansible/site.yml --limit <host> --tags emacs -e emacs_enabled=true
|
|
||||||
```
|
|
||||||
|
|
||||||
La configurazione finale di una macchina è ottenuta combinando più livelli.
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
common configuration
|
common configuration
|
||||||
@@ -215,55 +122,45 @@ common configuration
|
|||||||
+ host overrides
|
+ host overrides
|
||||||
```
|
```
|
||||||
|
|
||||||
Esempi correnti:
|
Current examples:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
ikaros -> common + platform_fedora + role_personal_workstation + graphical_desktop + desktop_gnome + ikaros
|
ikaros -> common + platform_fedora + role_personal_workstation + graphical_desktop + desktop_gnome + ikaros
|
||||||
nymph -> common + platform_fedora + graphical_desktop + desktop_gnome + nymph
|
nymph -> common + platform_fedora + graphical_desktop + desktop_gnome + nymph
|
||||||
deadalus -> common + platform_fedora + workstation_dev_fedora + workstation_dev_wsl + deadalus
|
deadalus -> common + platform_fedora + workstation_dev_fedora + workstation_dev_wsl + deadalus
|
||||||
```
|
```
|
||||||
|
|
||||||
Questo approccio consente di:
|
This keeps shared configuration reusable, lets host overrides stay small, and leaves the Void desktop profile ready for a future host using `platform_void + graphical_desktop + desktop_sway`.
|
||||||
|
|
||||||
- mantenere configurazioni condivise
|
Emacs is enabled on Fedora/GNOME and workstation profiles. `dotfiles_common` deploys the canonical authoring setup, including `~/Org/`, versioned templates, and PDF/HTML/Markdown/DOCX/ODT export support. To turn it on temporarily elsewhere:
|
||||||
- applicare override specifici per host
|
|
||||||
- evitare duplicazioni
|
|
||||||
- riutilizzare il profilo Void corrente su un host futuro assegnandolo a
|
|
||||||
`platform_void + graphical_desktop + desktop_sway`
|
|
||||||
|
|
||||||
---
|
```bash
|
||||||
|
ansible-playbook ansible/site.yml --limit <host> --tags emacs -e emacs_enabled=true
|
||||||
|
```
|
||||||
|
|
||||||
# Ruoli Ansible
|
## Main roles
|
||||||
|
|
||||||
I principali ruoli attualmente presenti sono:
|
| Role | What it does |
|
||||||
|
| --- | --- |
|
||||||
|
| `packages_void` | Installs packages on Void. |
|
||||||
|
| `packages_freebsd` | Installs packages on FreeBSD with pkg. |
|
||||||
|
| `packages_ubuntu` | Installs packages on Ubuntu. |
|
||||||
|
| `packages_fedora` | Installs packages on Fedora. |
|
||||||
|
| `services_runit` | Manages runit services. |
|
||||||
|
| `services_systemd` | Manages systemd services. |
|
||||||
|
| `services_freebsd` | Manages declared FreeBSD rc services. |
|
||||||
|
| `profile_desktop_common` | Shared Void desktop bootstrap. |
|
||||||
|
| `profile_desktop_gnome` | Shared Fedora/GNOME desktop dotfiles. |
|
||||||
|
| `profile_desktop_sway` | Sway / SwayFX Wayland session. |
|
||||||
|
| `profile_desktop_niri` | Niri Wayland session on Void. |
|
||||||
|
| `profile_desktop_host` | Host-specific desktop overrides. |
|
||||||
|
| `profile_personal_workstation` | Stable personal-workstation layer. |
|
||||||
|
| `profile_workstation_dev_common` | Shared workstation development setup. |
|
||||||
|
| `profile_workstation_dev_wsl` | WSL development setup. |
|
||||||
|
| `profile_server` | Server setup. |
|
||||||
|
| `dotfiles_common` | Shared user dotfiles. |
|
||||||
|
|
||||||
| Role | Descrizione |
|
## What `site.yml` runs
|
||||||
| ------------------------- | ----------------------------------- |
|
|
||||||
| base | configurazione base comune |
|
|
||||||
| packages_void | installazione pacchetti su Void |
|
|
||||||
| packages_freebsd | installazione pacchetti su FreeBSD via pkg |
|
|
||||||
| packages_ubuntu | installazione pacchetti su Ubuntu |
|
|
||||||
| packages_fedora | installazione pacchetti su Fedora |
|
|
||||||
| services_runit | gestione servizi runit |
|
|
||||||
| services_systemd | gestione servizi systemd |
|
|
||||||
| services_freebsd | gestione servizi FreeBSD dichiarati per host |
|
|
||||||
| profile_desktop_common | bootstrap desktop Void condiviso |
|
|
||||||
| profile_desktop_gnome | dotfiles desktop condivisi per Fedora/GNOME |
|
|
||||||
| profile_desktop_sway | sessione desktop sway / SwayFX (Wayland) |
|
|
||||||
| profile_desktop_niri | sessione desktop Niri su Void (Wayland) |
|
|
||||||
| profile_desktop_host | override desktop specifici per host |
|
|
||||||
| profile_personal_workstation | layer stabile per workstation personale |
|
|
||||||
| profile_workstation_dev_common | configurazione dev workstation condivisa |
|
|
||||||
| profile_workstation_dev_wsl | configurazione WSL condivisa per sviluppo |
|
|
||||||
| profile_server | configurazione server |
|
|
||||||
| dotfiles_common | distribuzione dotfiles comuni |
|
|
||||||
| dotfiles | distribuzione configurazioni utente |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Stato attuale del playbook principale
|
|
||||||
|
|
||||||
Il playbook `ansible/site.yml` e attualmente composto da blocchi per asse:
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
all -> dotfiles_common
|
all -> dotfiles_common
|
||||||
@@ -274,98 +171,45 @@ platform_fedora -> packages_fedora + services_systemd
|
|||||||
platform_fedora & role_personal_workstation -> profile_personal_workstation
|
platform_fedora & role_personal_workstation -> profile_personal_workstation
|
||||||
platform_fedora & desktop_gnome -> profile_desktop_gnome
|
platform_fedora & desktop_gnome -> profile_desktop_gnome
|
||||||
workstation_dev_fedora -> profile_workstation_dev_common
|
workstation_dev_fedora -> profile_workstation_dev_common
|
||||||
workstation_dev_wsl -> profile_workstation_dev_wsl (dopo platform_fedora + workstation_dev_fedora)
|
workstation_dev_wsl -> profile_workstation_dev_wsl (after platform_fedora + workstation_dev_fedora)
|
||||||
ubuntu_server -> packages_ubuntu + services_systemd + profile_server
|
ubuntu_server -> packages_ubuntu + services_systemd + profile_server
|
||||||
```
|
```
|
||||||
|
|
||||||
Questo significa che, allo stato attuale:
|
So, in practice:
|
||||||
|
|
||||||
- `ikaros` riceve Fedora Workstation/GNOME come target desktop personale stabile
|
- `platform_fedora` configures `ikaros`, `nymph`, and `deadalus`.
|
||||||
- `nymph` riceve Fedora Workstation/GNOME come target laptop
|
- `deadalus` gets the Fedora development layer followed by the WSL layer.
|
||||||
- il profilo Void resta selezionabile tramite `platform_void + graphical_desktop` per host futuri
|
- `ubuntu_server` configures `prometheus`.
|
||||||
- `deadalus` riceve il profilo Fedora WSL tramite play dev dedicati
|
- Empty `platform_void` and `platform_freebsd` groups do nothing until they get a host.
|
||||||
- il server Ubuntu (`prometheus`) e gestito con pacchetti, servizi, dotfiles server e firewall
|
- The playbook never restarts the display manager during a run.
|
||||||
- lo stack container server include `navidrome`, `postgres`, `gitea`, `nginx-proxy-manager` e `syncthing`, con GUI Syncthing raggiungibile tramite la rete Docker `web`
|
- `secrets/vault.yml` and then `secrets/vault.local.yml` are loaded only when present.
|
||||||
|
|
||||||
# Dotfiles
|
## Requirements
|
||||||
|
|
||||||
La directory `dotfiles/` contiene le configurazioni utente versionate.
|
You will need Python 3, Ansible, `ansible-lint`, `yamllint`, `shellcheck`, and the collections in `ansible/collections/requirements.yml`.
|
||||||
|
|
||||||
```text
|
|
||||||
dotfiles/
|
|
||||||
├── common
|
|
||||||
├── desktop
|
|
||||||
├── server
|
|
||||||
├── fedora
|
|
||||||
├── ubuntu
|
|
||||||
├── workstation
|
|
||||||
├── workstation_dev_wsl
|
|
||||||
└── nymph
|
|
||||||
```
|
|
||||||
|
|
||||||
Le configurazioni sono applicate tramite Ansible e organizzate per livelli:
|
|
||||||
|
|
||||||
| Livello | Scopo |
|
|
||||||
| ------- | -------------------------------- |
|
|
||||||
| common | configurazioni condivise |
|
|
||||||
| profile | configurazioni per tipo macchina |
|
|
||||||
| host | override specifici |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Requisiti
|
|
||||||
|
|
||||||
Per utilizzare il repository sono necessari:
|
|
||||||
|
|
||||||
- Python 3
|
|
||||||
- Ansible
|
|
||||||
- `ansible-lint`
|
|
||||||
- `yamllint`
|
|
||||||
- `shellcheck`
|
|
||||||
- collection definite in `ansible/collections/requirements.yml`
|
|
||||||
- accesso locale o SSH alle macchine target, in base a come e definito l'inventory
|
|
||||||
|
|
||||||
Installazione base:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python3 -m pip install ansible ansible-lint yamllint shellcheck-py
|
python3 -m pip install ansible ansible-lint yamllint shellcheck-py
|
||||||
ansible-galaxy collection install -r ansible/collections/requirements.yml
|
ansible-galaxy collection install -r ansible/collections/requirements.yml
|
||||||
```
|
```
|
||||||
|
|
||||||
Gestione segreti:
|
Secrets are optional:
|
||||||
|
|
||||||
- il repository supporta il caricamento opzionale di `secrets/vault.yml`
|
- `secrets/vault.yml` can hold shared local vault values.
|
||||||
- il repository supporta anche `secrets/vault.local.yml` per override locali non versionati
|
- `secrets/vault.local.yml` can hold untracked local overrides.
|
||||||
- `secrets/vault.yml.example` funge da template/esempio
|
- `secrets/vault.yml.example` is the example template.
|
||||||
- se `secrets/vault.yml` non e presente, il playbook continua comunque senza caricare variabili locali opzionali
|
- If no vault file exists, the playbook still runs without those optional values.
|
||||||
- se `secrets/.vault_pass.gpg` esiste viene usato automaticamente per sbloccare i vault tramite `gpg`; in alternativa resta supportato `secrets/.vault_pass` come fallback legacy locale; se nessuno dei due file esiste Ansible richiede la password in modo interattivo
|
- `secrets/.vault_pass.gpg` is used when available; `secrets/.vault_pass` is a legacy local fallback. Without either one, Ansible asks for the password interactively.
|
||||||
|
|
||||||
---
|
## Running it
|
||||||
|
|
||||||
# Utilizzo
|
Run the whole playbook:
|
||||||
|
|
||||||
Eseguire il playbook principale:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
ansible-playbook ansible/site.yml
|
ansible-playbook ansible/site.yml
|
||||||
```
|
```
|
||||||
|
|
||||||
Allo stato attuale questo comando:
|
Useful checks before applying changes:
|
||||||
|
|
||||||
- distribuisce i dotfiles comuni a tutti gli host
|
|
||||||
- per `platform_void` applica pacchetti Void e servizi runit
|
|
||||||
- per `platform_void + graphical_desktop` applica bootstrap desktop condiviso, sessioni Sway/Niri e override specifici per host
|
|
||||||
- per `platform_freebsd` non applica nulla finche il gruppo resta senza host
|
|
||||||
- per `platform_fedora` applica pacchetti Fedora e servizi systemd a `ikaros`, `nymph` e `deadalus`
|
|
||||||
- per `platform_fedora & role_personal_workstation` applica il layer personale a `ikaros`
|
|
||||||
- per `platform_fedora & desktop_gnome` applica il profilo GNOME a `ikaros` e `nymph`
|
|
||||||
- per `workstation_dev_wsl` applica i tweak WSL dopo il layer Fedora a `deadalus`, escludendo Flatpak e Snap
|
|
||||||
- per gli host `ubuntu_server` applica pacchetti Ubuntu, servizi systemd, profilo server, UFW, dotfiles e template dedicati
|
|
||||||
- non riavvia automaticamente il display manager
|
|
||||||
- carica `secrets/vault.yml` solo se presente
|
|
||||||
- carica `secrets/vault.local.yml` solo se presente, dopo `vault.yml`, cosi gli override locali hanno precedenza
|
|
||||||
|
|
||||||
Per validare prima di applicare:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
ansible-playbook ansible/site.yml --syntax-check
|
ansible-playbook ansible/site.yml --syntax-check
|
||||||
@@ -379,13 +223,7 @@ ansible-lint ansible/roles
|
|||||||
yamllint ansible/
|
yamllint ansible/
|
||||||
```
|
```
|
||||||
|
|
||||||
Per testare un override dell'utente server senza modificare l'inventory:
|
For focused checks:
|
||||||
|
|
||||||
```bash
|
|
||||||
ansible-playbook ansible/site.yml --limit prometheus --check --diff -e server_username=myuser
|
|
||||||
```
|
|
||||||
|
|
||||||
Per validazioni piu mirate:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
ansible-playbook ansible/site.yml --limit <host> --tags <tag1>,<tag2> --check --diff
|
ansible-playbook ansible/site.yml --limit <host> --tags <tag1>,<tag2> --check --diff
|
||||||
@@ -395,58 +233,33 @@ yamllint ansible/path/to/file.yml
|
|||||||
docker compose -f /opt/docker/server/docker-compose.yml config
|
docker compose -f /opt/docker/server/docker-compose.yml config
|
||||||
```
|
```
|
||||||
|
|
||||||
## Tag supportati dal playbook
|
## Tags
|
||||||
|
|
||||||
Per vedere l'elenco reale aggiornato dei tag disponibili:
|
Use Ansible as the source of truth for the current tag list:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
ansible-playbook ansible/site.yml --list-tags
|
ansible-playbook ansible/site.yml --list-tags
|
||||||
```
|
```
|
||||||
|
|
||||||
Allo stato attuale `ansible/site.yml` espone questi tag:
|
| Tag | Main scope |
|
||||||
|
| --- | --- |
|
||||||
|
| `always` | Common pre-tasks, including optional vault loading. |
|
||||||
|
| `ai_agents` | Shared AI agent installation on Fedora and WSL. |
|
||||||
|
| `dotfiles` | User configuration across all profiles. |
|
||||||
|
| `dotfiles:common` | Shared dotfiles. |
|
||||||
|
| `dotfiles:desktop` | Void and Fedora/GNOME desktop dotfiles. |
|
||||||
|
| `dotfiles:host` | Host-specific Void desktop overrides. |
|
||||||
|
| `dotfiles:server` | Server dotfiles. |
|
||||||
|
| `dotfiles:workstation` | Personal workstation and WSL dotfiles. |
|
||||||
|
| `emacs` | Shared Emacs setup and authoring dependencies. |
|
||||||
|
| `gnome` | Fedora/GNOME desktop configuration. |
|
||||||
|
| `npm` | Global npm packages. |
|
||||||
|
| `packages` | Package installation and updates. |
|
||||||
|
| `services` | runit and systemd services. |
|
||||||
|
| `tmux` | tmux configuration and plugins. |
|
||||||
|
| `wsl` | WSL bootstrap and configuration. |
|
||||||
|
|
||||||
| Tag | Scopo | Ambito principale |
|
## Bootstrapping a new machine
|
||||||
| --- | --- | --- |
|
|
||||||
| `always` | pre-task sempre eseguiti, inclusi caricamento vault e validazioni preliminari | common |
|
|
||||||
| `ai_agents` | installazione agenti AI condivisi | Fedora, WSL |
|
|
||||||
| `dotfiles` | distribuzione/configurazione dotfiles | tutti i profili |
|
|
||||||
| `dotfiles:common` | dotfiles comuni condivisi | common, workstation, server |
|
|
||||||
| `dotfiles:desktop` | dotfiles desktop | desktop Void, Fedora/GNOME |
|
|
||||||
| `dotfiles:host` | override host-specifici desktop | desktop Void |
|
|
||||||
| `dotfiles:server` | dotfiles dedicati al profilo server | server |
|
|
||||||
| `dotfiles:workstation` | dotfiles dedicati alle workstation | personal workstation, WSL |
|
|
||||||
| `emptty` | gestione display manager `emptty` | desktop Void |
|
|
||||||
| `display-manager` | gestione del display manager `emptty` | desktop Void |
|
|
||||||
| `emacs` | configurazione Emacs condivisa e dipendenze di authoring | desktop Fedora/GNOME e workstation |
|
|
||||||
| `fonts` | installazione font | Fedora |
|
|
||||||
| `fzf` | configurazione FZF | dotfiles comuni |
|
|
||||||
| `git` | configurazione Git e GPG desktop | Fedora/GNOME, desktop Void |
|
|
||||||
| `gnome` | configurazione host GNOME | Fedora/GNOME desktop |
|
|
||||||
| `sway` | sessione/configurazione sway / SwayFX (Wayland) | desktop Void |
|
|
||||||
| `niri` | sessione/configurazione Niri (Wayland) | desktop Void |
|
|
||||||
| `npm` | installazione pacchetti npm globali | Fedora/GNOME, desktop Void, WSL |
|
|
||||||
| `nvidia` | componenti NVIDIA desktop | desktop Void |
|
|
||||||
| `packages` | installazione e aggiornamento pacchetti | tutti i profili |
|
|
||||||
| `portal` | configurazione xdg-desktop-portal | desktop Void |
|
|
||||||
| `services` | gestione servizi runit/systemd | tutti i profili |
|
|
||||||
| `theme` | configurazione del tema GTK/Qt | desktop Void |
|
|
||||||
| `tmux` | configurazione e plugin tmux | desktop Fedora/Void, WSL |
|
|
||||||
| `vim` | configurazione Vim | dotfiles comuni |
|
|
||||||
| `wsl` | bootstrap e configurazione WSL | WSL |
|
|
||||||
|
|
||||||
Esempi pratici:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ansible-playbook ansible/site.yml --limit nymph --tags dotfiles:desktop,gnome --check --diff
|
|
||||||
ansible-playbook ansible/site.yml --limit ikaros --tags gnome --check --diff
|
|
||||||
ansible-playbook ansible/site.yml --limit prometheus --tags services,dotfiles:server --check --diff
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Bootstrap di una nuova macchina
|
|
||||||
|
|
||||||
Una nuova macchina può essere inizializzata con i seguenti passaggi:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone <repo>
|
git clone <repo>
|
||||||
@@ -455,66 +268,11 @@ ansible-galaxy collection install -r ansible/collections/requirements.yml
|
|||||||
ansible-playbook ansible/site.yml
|
ansible-playbook ansible/site.yml
|
||||||
```
|
```
|
||||||
|
|
||||||
Dopo l'esecuzione del playbook la macchina verra configurata secondo il profilo definito e i ruoli attualmente orchestrati.
|
For a future Void desktop host:
|
||||||
|
|
||||||
Per aggiungere un nuovo host Void che riusa il profilo desktop preservato:
|
1. Add it to `platform_void`.
|
||||||
|
2. Add it to `graphical_desktop`.
|
||||||
|
3. Use Sway, or add it to `desktop_niri` for Niri.
|
||||||
|
4. Put hardware-specific details in `host_vars/<host>.yml`.
|
||||||
|
|
||||||
1. aggiungere l'host a `platform_void`;
|
The legacy `void` and `desktop` groups remain compatibility parents, so hosts in `platform_void` and `graphical_desktop` still receive the existing Void and desktop variables.
|
||||||
2. aggiungerlo a `graphical_desktop`;
|
|
||||||
3. usare Sway, oppure aggiungerlo a `desktop_niri` per selezionare Niri;
|
|
||||||
4. lasciare eventuali dettagli hardware in `host_vars/<host>.yml`.
|
|
||||||
|
|
||||||
I gruppi legacy `void` e `desktop` sono parent di compatibilita, quindi un host
|
|
||||||
in `platform_void` e `graphical_desktop` continua a ricevere anche le variabili
|
|
||||||
Void e desktop esistenti.
|
|
||||||
|
|
||||||
Per prove in VM sono disponibili gruppi di esempio in
|
|
||||||
`ansible/inventory/examples/platform-test-hosts.yml`, da passare esplicitamente
|
|
||||||
con `-i` insieme all'inventory principale.
|
|
||||||
|
|
||||||
Per il flusso mail desktop esiste inoltre uno script dedicato:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
scripts/bootstrap_mail.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
Lo script si occupa del bootstrap dei secret nel keyring, del primo sync con `mbsync` e dell'inizializzazione di `mu` usando la configurazione mail generata dai template.
|
|
||||||
|
|
||||||
Se modifichi questo script, valida almeno con:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sh -n scripts/bootstrap_mail.sh
|
|
||||||
shellcheck scripts/bootstrap_mail.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Filosofia del progetto
|
|
||||||
|
|
||||||
Il repository segue alcuni principi chiave:
|
|
||||||
|
|
||||||
- Infrastructure as Code
|
|
||||||
- configurazione dichiarativa
|
|
||||||
- idempotenza
|
|
||||||
- ambienti riproducibili
|
|
||||||
- separazione tra configurazione sistema e configurazione utente
|
|
||||||
|
|
||||||
Questo consente di ricreare qualsiasi macchina partendo esclusivamente dal repository.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Roadmap
|
|
||||||
|
|
||||||
Possibili evoluzioni future:
|
|
||||||
|
|
||||||
- hardening sicurezza server
|
|
||||||
- configurazione backup
|
|
||||||
- testing automatico playbook
|
|
||||||
- integrazione CI
|
|
||||||
- supporto ad altre distribuzioni Linux
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Licenza
|
|
||||||
|
|
||||||
Questo progetto è distribuito sotto licenza **LGPL-3.0**.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user