From f5b7367f754bd28873680102cf564eee09e42a9a Mon Sep 17 00:00:00 2001 From: Matteo Cherubini Date: Sat, 20 Jun 2026 22:23:57 +0200 Subject: [PATCH] docs: Add Nexus deployment README --- deploy/nexus/README.md | 81 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 deploy/nexus/README.md diff --git a/deploy/nexus/README.md b/deploy/nexus/README.md new file mode 100644 index 0000000..bd8ada0 --- /dev/null +++ b/deploy/nexus/README.md @@ -0,0 +1,81 @@ +# Componenti di Sistema — Gestione Sincronizzazione e Automazione Genoma + +Questo modulo contiene gli script di backend che vengono installati sul server `nexus` per gestire il ciclo di vita dei vault locali (scratch di lavoro), l'integrazione con Syncthing e l'autocommit dei file grezzi (`raw/`) provenienti dai dispositivi mobili o desktop (es. Obsidian). + +## Architettura dei File di Sistema + +Gli script sono progettati per girare in un ambiente multi-utente protetto, dove l'istanza globale di `n8n` (tramite l'utente di sistema `n8n-runner`) pilota le operazioni senza possedere i diritti di lettura/scrittura diretti sui file del genoma o sui segreti di configurazione. + +### 1. Posizionamento e Permessi degli Script + +I file inclusi in questa cartella devono essere installati sul server di produzione nella directory `/usr/local/bin/` con privilegi di esecuzione globali, ma modificabili solo da `root`. + +- **Destinazione:** `/usr/local/bin/` +- **Proprietario (Owner):** `root:root` +- **Permessi (Chmod):** `0755` (`-rwxr-xr-x`) + +#### Elenco degli Script: + +- `ensure-genome-vault`: Script idempotente che inizializza o riallinea il vault locale clonandolo da Forgejo (in loopback) sul branch `develop`, configura gli `.stignore` ed effettua il provisioning automatico della cartella condivisa su Syncthing via API. +- `genome-askpass`: Helper di autenticazione per Git (`GIT_ASKPASS`). Intercetta le richieste di credenziali di Git durante i cloni e i push HTTP su Forgejo, iniettando l'utente e il token applicativo senza esporli nei log di sistema o negli argomenti dei processi. +- `genome-raw-commit`: Script di polling periodico invocato da n8n. Isola i file modificati nella cartella `raw/`, interroga Syncthing per capire quale dispositivo (e quindi quale autore umano) ha generato la modifica, crea commit atomici attribuiti al singolo autore e pusha le modifiche su Forgejo (`develop`). + +--- + +## Modello di Sicurezza e Visibilità + +Per garantire l'isolamento del sistema operativo, l'infrastruttura si basa su tre livelli di confinamento: + +### A. Variabili d'Ambiente Protette (`.env`) + +Le credenziali (Token Forgejo, API Key Syncthing) risiedono nella Home dell'utente operativo del servizio (`homelab`) e sono completamente invisibili a n8n e ad altri utenti del sistema. + +- **Path:** `/home/homelab/.config/knowledge-genome.env` +- **Permessi:** `0600` (`-rw-------`), di proprietà esclusiva di `homelab:homelab`. + +#### env + +Nella cartella `~/.config/knowledge-genome.env`. + +```text +# knowledge-genome.env Configuration Profile +# Requirements: Must be owned by the service user with 0600 permissions. + +# Vault path and operational branch +GENOME_VAULTS_ROOT=/srv/genome-vaults +GENOME_BASE=develop + +# Forgejo Target Instance +# Replace 127.0.0.1 with vm101 IP if Forgejo is hosted on the virtual machine +FORGEJO_HOST=127.0.0.1:3001 +FORGEJO_OWNER=Keru +FORGEJO_USER=n8n-bot +FORGEJO_TOKEN="............" + +# Git Commit Identity +COMMITTER_NAME=n8n-bot +COMMITTER_EMAIL=n8n-bot@homelab +DEFAULT_AUTHOR_NAME="Matteo Cherubini" +DEFAULT_AUTHOR_EMAIL=matteo@keruhomelab.com + +# Syncthing Target Instance +# Replace 127.0.0.1 with vm101 IP if Syncthing API is hosted on the virtual machine +SYNCTHING_URL=http://127.0.0.1:8384 +SYNCTHING_API_KEY="............" +``` + +### B. Confine dei Privilegi in Sudoers + +L'utente di automazione `n8n-runner` (usato dall'agente SSH di n8n) non ha accesso alla shell e non può invocare comandi arbitrari. Può unicamente chiamare i due script principali impersonando l'utente `homelab` senza l'inserimento della password. + +Configurazione da applicare in `/etc/sudoers.d/n8n-genome` (con permessi rigorosi `0440`): + +```text +n8n-runner ALL=(homelab) NOPASSWD: /usr/local/bin/ensure-genome-vault, /usr/local/bin/genome-raw-commit +``` + +### C. Directory dei Vault + +I dati veri e propri sincronizzati da Syncthing risiedono isolati in `/srv/genome-vaults/`. + +- **Proprietario**: homelab:homelab (UID/GID 1000), permettendo la convivenza nativa e fluida tra il demone Syncthing in esecuzione nel container e gli script Git locali.