From 100b20659664d7ae9ae70dce28e3f7b1d54351fe Mon Sep 17 00:00:00 2001
From: Fabio Sinibaldi <fabio.sinibaldi@isti.cnr.it>
Date: Mon, 14 Sep 2026 17:04:48 +0200
Subject: [PATCH] Update playbook docs

---
 ansible/playbooks/README.md | 77 ++++++++++++++++++++++++++++++++-----
 1 file changed, 67 insertions(+), 10 deletions(-)

diff --git a/ansible/playbooks/README.md b/ansible/playbooks/README.md
index 6b84aeb..5e656ee 100644
--- a/ansible/playbooks/README.md
+++ b/ansible/playbooks/README.md
@@ -14,9 +14,6 @@ Qui vengono riportati i playbook disponibili, descrizione e utilizzo.
 - [Borg Backups](#borg-backups)
 
 
-
-
-
 ### Bootstrap
 
 Implementa la configurazione di base di un nodo per poter essere gestito dagli altri playbook, in particolare : 
@@ -82,13 +79,73 @@ Il playbook installa docker e docker compose. Attraverso docker compose vengono
 
 Il playbook utilizza : 
 - [geerlingguy.docker](https://github.com/geerlingguy/ansible-role-docker) attraverso ansible galaxy
-- I ruoli common e pangolin definiti in [pangolin-ansible-terraform](https://github.com/patelanuj21/pangolin-ansible-terraform/tree/main), riportati staticamente come ruolo *pangolin*
-
+- Il ruolo ***prepare_node***
+- Il ruolo ***pangolin*** preso da [pangolin-ansible-terraform](https://github.com/patelanuj21/pangolin-ansible-terraform/tree/main)
 
 I parametri attesi dal playbook sono quelli definiti nei ruoli da cui dipende. 
 
-#### Forgejo
-#### Authentik 
-#### Nextcloud
-#### Static Nginx Page
-#### Borg Backups
+### Forgejo
+Il playbook installa docker e docker compose. Attraverso docker compose vengono poi lanciati container per [forgejo](https://forgejo.org/) e [newt_client](https://docs.pangolin.net/manage/sites/install-site).
+
+Il playbook utilizza : 
+- [geerlingguy.docker](https://github.com/geerlingguy/ansible-role-docker) attraverso ansible galaxy
+- I ruoli ***forgejo*** e ***newt_client***
+
+### Authentik 
+Il playbook installa docker e docker compose. Attraverso docker compose vengono poi lanciati container per [authentik](https://docs.goauthentik.io/) e [newt_client](https://docs.pangolin.net/manage/sites/install-site).
+
+Il playbook utilizza : 
+- [geerlingguy.docker](https://github.com/geerlingguy/ansible-role-docker) attraverso ansible galaxy
+- [ax-bzh.authentik](https://galaxy.ansible.com/ui/standalone/roles/ax-bzh/authentik/documentation/) attraverso ***ansible galaxy***
+- Il ruolo ***newt_client***
+
+### Nextcloud
+Il playbook installa docker e docker compose. Attraverso docker viene poi lanciato il container per [Nextcloud AIO](https://github.com/nextcloud/all-in-one) e [newt_client](https://docs.pangolin.net/manage/sites/install-site).
+
+Il playbook utilizza : 
+- [geerlingguy.docker](https://github.com/geerlingguy/ansible-role-docker) attraverso ansible galaxy
+- I ruoli ***newt_client*** e ***nextcloud_aio***
+
+### Static Nginx Page
+Il playbook installa docker e docker compose. Attraverso docker viene poi lanciato il container per [Nginx](https://nginx.org/) e [newt_client](https://docs.pangolin.net/manage/sites/install-site).
+
+Il playbook utilizza : 
+- [geerlingguy.docker](https://github.com/geerlingguy/ansible-role-docker) attraverso ansible galaxy
+- I ruoli ***newt_client*** e ***nginx***
+
+### Borg Backups
+Il playbook configura sia i client che il server per i backup effettuati con [borg](https://www.borgbackup.org/). I client vengono risolti dinamicamente verificando la presenza della seguente configurazione in esempio: 
+
+```
+configure_borg_client: True
+borg_repos:
+  - name: test
+    borg_passphrase: "dummy_secret"
+    paths_to_backup: 
+      - "/home/{{ ansible_user }}"
+      - "/proc/version"
+```
+
+Per ogni client vengono configurati : 
+- l'utente e relative credenziali per connettersi al borg server
+- Un servizio systemd **borg\_backup.service** e relativo timer **borg\_backup.timer** per eseguire il backup
+- Uno script che esegue effettivamente il backup **"/home/{{borg_user}}/backup\_script.sh"** verso *"ssh://{{ borg\_user }}@{{ borg\_backup_server }}/./"*
+
+Sul server vengono configurati: 
+- L'utente con cui eseguire borg service
+- Le credenziali attese utilizzate dai vari client e i rispettivi path permessi per eseguire i report. 
+
+Sul server i permessi concessi ai vari client vengono limitati definendo su ***/home/{{borg\_user}}/.ssh/authorized\_keys*** le limitazioni di path (accesso solo al proprio repo) e di operation (solo ***"borg serve"***) con la seguente istruzione : 
+```
+command=\"cd {{ borg_pool }}/{{ item.host }};borg serve --restrict-to-path {{ borg_pool }}/{{ item.host }}\",restrict
+```
+
+E' possibile configurare il server per servire borg anche con altre credenziali e path, per casi non coperti dal playbook (e.g. borg backups usato direttamente da Nextcloud AIO) attraverso il seguente attributo: 
+
+```
+borg_auth_users:
+  - host: fabotest
+    key: "ssh-rsa ********"
+```
+
+Il playbook utilizza il role ***borg***