knowledge-genome-orchestrator/deploy/nexus

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.

# 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):

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.