Gestire i segreti in Docker: env file, volumi e la encryption key di n8n

Tempo di lettura: 7 minuti — Livello: intermedio

La domanda da cui tutto parte

Ogni sistema self-hosted vive di segreti: chiavi API, token di bot, password di database. La domanda "dove li metto?" sembra banale e invece definisce quanto è sicuro — e quanto è recuperabile — tutto il tuo stack. Questo articolo è la mappa che avrei voluto avere io, con in fondo la storia della encryption key di n8n: il segreto più insidioso di tutti, perché non l'hai creato tu.

I posti sbagliati (partiamo dal cosa NON fare)

Nel comando docker run. docker run -e API_KEY=sk-abc123... sembra comodo. Peccato che quel comando finisca nella cronologia della shell, e che chiunque possa leggere le variabili di un container con docker inspect. I segreti nei comandi sono segreti urlati.

Nel codice o nel Dockerfile. Il classico "lo metto qui un attimo poi lo sposto". Poi arriva il commit, e un segreto committato è per sempre: anche se lo cancelli dopo, resta nella storia di Git. L'unico rimedio vero è rigenerare la chiave — dieci minuti se te ne accorgi subito, un incidente se se ne accorge qualcun altro prima.

Nei log. Il più subdolo. Un nodo di debug che stampa l'oggetto di configurazione, un errore che include gli header della richiesta... e la chiave finisce nei log, che spesso hanno permessi più larghi e vita più lunga di qualsiasi altro file. Quando loggi, logga che una chiave c'è, mai quale.

La soluzione base che uso: l'env file esterno

Un file di testo fuori dal progetto (quindi fuori da Git per costruzione), con dentro le variabili:

# n8n.env
N8N_HOST=n8n.miodominio.it
TELEGRAM_BOT_TOKEN=...
OPENAI_API_KEY=...

E il container che lo carica all'avvio:

docker run -d --name n8n \
  --env-file /percorso/sicuro/n8n.env \
  ...

Vantaggi: un posto solo da proteggere e backuppare, niente segreti nella cronologia della shell, e la separazione netta tra configurazione (nel file) e infrastruttura (nel comando). Non è il massimo teorico della sicurezza — per quello esistono i secret manager — ma per un self-hoster singolo è il punto di equilibrio giusto tra sicurezza e gestibilità. La sicurezza che non riesci a mantenere è peggio di una sicurezza media che mantieni sempre.

Due accorgimenti che completano il quadro: permessi restrittivi sul file (solo il tuo utente lo legge) e — importante — l'env file va incluso nei backup, cifrato. Ricreare un server si può; ricordarsi a memoria trenta chiavi API, no.

Il caso speciale: la encryption key di n8n

E ora la storia che dà il titolo all'articolo. n8n salva le credenziali che gli affidi (i tuoi accessi Google, i token, le password dei database) cifrate nel suo database interno. Ottimo. La chiave di cifratura, la encryption key, la genera n8n stesso al primo avvio.

Domanda: dove la salva? Istinto di chiunque: "nell'env file, come tutto il resto". No. Di default vive in un file di configurazione dentro la cartella dati di n8n — cioè dentro il volume Docker (/home/node/.n8n/config).

Le conseguenze pratiche, che è meglio imparare da un articolo che da un incidente:

1. Il volume È il segreto. Se distruggi il volume n8n_data, non perdi solo i workflow: perdi la chiave, e con lei la capacità di decifrare qualsiasi backup delle credenziali. Backup del database senza la chiave = archivio di casseforti senza combinazione.
2. Ricreare il container è sicuro, ricreare il volume è fatale. docker rm n8n non tocca il volume: è l'operazione di routine di ogni aggiornamento. Il momento di massima attenzione è quando si toccano i volumi — un docker volume prune distratto e la giornata cambia colore.
3. La chiave va estratta e conservata anche fuori. Copiala dal file di config del volume e mettila nel tuo posto sicuro (password manager). Così anche nello scenario peggiore — volume perso, ma backup del database presente — puoi ripartire impostando la chiave via variabile d'ambiente.

La mappa mentale finale

Tre categorie di segreti, tre trattamenti:

• Segreti che dai tu alle app (API key, token) → env file esterno, permessi stretti, backup cifrato
• Segreti che le app generano da sole (encryption key e simili) → scopri DOVE li tengono, ed estraine una copia nel password manager
• Segreti nel posto sbagliato (codice, log, cronologia) → non si "spostano": si rigenerano La terza è quella che fa male, perché l'istinto dice "lo tolgo e siamo a posto". No: un segreto esposto è compromesso per definizione, e l'unica igiene vera è la rotazione. Il lato buono? Dopo la prima volta che ruoti una chiave per davvero, impari a metterle nel posto giusto con una motivazione che nessun articolo può darti.

---

Questo articolo fa parte della serie "Stack & Infrastruttura" su perfetti.tech — dove racconto quello che costruisco davvero, errori compresi.