AI Automation Italia

Variabili d’Ambiente in n8n: Guida per l’Hosting Self-Managed

Variabili d’Ambiente in n8n: Guida per l’Hosting Self-Managed

Quando ospiti n8n in autonomia, le variabili d’ambiente sono la chiave per ottenere un setup riproducibile, sicuro e pronto per la produzione. Con hosting self managed n8n puoi definire URL pubblici dietro reverse proxy, configurare database PostgreSQL, abilitare lo scaling in queue mode con Redis e applicare policy di sicurezza come la cifratura delle credenziali. In questa guida pratica vedrai cosa fanno le variabili di ambiente n8n più importanti, come organizzarle in Docker o Kubernetes, e come evitare i classici problemi (webhook non raggiungibili, mismatch di URL, limiti di payload). Troverai snippet testati per Docker Compose, esempi con _FILE per caricare segreti da file, e consigli operativi su ambienti dev/stage/prod. Obiettivo: passare da un’installazione “di prova” a un’istanza stabile e governata con poche, chiare impostazioni.

📚 Nuovo a n8n? Parti dalla guida completa: cos'è n8n e come funziona.

[IMG: Diagramma: Client → Reverse Proxy (TLS) → n8n Web + Workers (Queue Mode) → Postgres + Redis]

Fondamenta: cosa controllano le variabili e perché sono importanti

Le variabili d’ambiente controllano gli aspetti critici della configurazione n8n:

  • URL e webhooks: host, protocollo, percorsi endpoint e URL pubblico dietro reverse proxy.
  • Database/persistenza: passaggio da SQLite a PostgreSQL per affidabilità e scaling.
  • Sicurezza: chiave di cifratura delle credenziali, TLS/SSL, accesso editor pubblico.
  • Scaling: attivazione del queue mode con Redis per carichi elevati e più processi.
  • Rete e proxy: porte, indirizzi, proxy HTTP/HTTPS.

Benefici per un hosting self managed n8n:

  • Riproducibilità e separazione ambienti (dev/stage/prod).
  • Sicurezza e governance (chiave di cifratura, segreti fuori dal codice).
  • Scalabilità prevedibile (queue mode, sticky sessions, Redis).
  • Troubleshooting più veloce (config chiara, auditabile come “IaC”).

[IMG: Tabella concettuale: Categoria → Variabili chiave → Effetto sul runtime]

Metodi di configurazione e precedenze: env, _FILE e file-based config

n8n supporta più modi per applicare configurazioni:

  • Variabili d’ambiente classiche (es. export VAR=valore o environment in Docker/K8s).
  • Suffisso FILE per caricare il valore da un file (es. DBPOSTGRESDBPASSWORDFILE=/run/secrets/pg_password).
  • Configurazione “file-based” aggiuntiva con N8NCONFIGFILES per puntare a JSON di configurazione.

Note operative utili:

  • In Docker/Kubernetes, preferisci _FILE e secret manager per credenziali.
  • Per proxy, le variabili tipo HTTPPROXY/HTTPSPROXY rispettano precedenze specifiche: le versioni minuscole (httpproxy/httpsproxy) possono avere priorità, quindi non impostarle in modo incoerente nella stessa istanza.
  • Regola d’oro: dopo aver aggiornato le variabili, riavvia il servizio (container/pod) per applicare i cambiamenti.

Comandi tipici:

  • Impostare una variabile in bash:
    export =
  • Esempio FILE (carica da file):
    DB    POSTGRESDBPASSWORDFILE=/run/secrets/pg_password

[IMG: Schermata .env con placeholder non sensibili e riferimenti a Docker secrets]

URL pubblici, reverse proxy e webhook: le variabili essenziali

Per definire host, porte e protocolli:

  • N8N_HOST: host name (default: localhost)
  • N8N_PORT: porta HTTP (default: 5678)
  • N8NLISTENADDRESS: IP di ascolto (default: ::)
  • N8N_PROTOCOL: http | https
  • N8NEDITORBASE_URL: URL pubblico dell’editor (usato anche nelle email e redirect SAML)
  • WEBHOOK_URL: URL pubblico dei webhook quando n8n è dietro un reverse proxy

Per i percorsi endpoint:

  • N8NENDPOINTWEBHOOK: path per i webhook (default: webhook)
  • N8NENDPOINTWEBHOOK_TEST: path per i test webhook (default: webhook-test)
  • N8NENDPOINTWEBHOOK_WAIT: path per i waiting webhook (default: webhook-waiting)

Controllo dimensione payload per Webhook node:

  • N8NPAYLOADSIZE_MAX: massima dimensione payload (default 16MB); aumenta solo se necessario.

Best practice dietro reverse proxy:

  • Imposta WEBHOOK_URL con l’indirizzo pubblico completo (HTTPS consigliato).
  • Allinea i path personalizzati (N8NENDPOINTWEBHOOK*) con le regole del proxy/load balancer.
  • Abilita sticky sessions sul bilanciatore quando hai più processi main in queue mode.

Esempio (bash):
export N8NHOST=n8n.example.com
export N8NPROTOCOL=https
export N8NEDITORBASEURL=https://n8n.example.com
export WEBHOOKURL=https://n8n.example.com/

[IMG: Pannello reverse proxy con host/SSL e inoltro verso n8n interno]

Database e persistenza: da SQLite a PostgreSQL con cifratura credenziali

Per produzione, usa PostgreSQL:

  • DB_TYPE=postgresdb
  • DBPOSTGRESDBHOST (default: localhost)
  • DBPOSTGRESDBPORT (default: 5432)
  • DBPOSTGRESDBDATABASE (default: n8n)
  • DBPOSTGRESDBUSER (default: postgres)
  • DBPOSTGRESDBPASSWORD
  • DBPOSTGRESDBSCHEMA (default: public)
  • Opzionale: DBPOSTGRESDBSSLCA, DBPOSTGRESDBSSLREJECT_UNAUTHORIZED

Chiave di cifratura credenziali:

  • N8NENCRYPTIONKEY: imposta una chiave personalizzata per cifrare le credenziali nel DB (se non fornita, n8n ne genera una al primo avvio). Conservala come secret e includila nei backup.

Persistenza:

  • Monta /home/node/.n8n (contiene dati utente e chiave) su volume persistente.
  • Prima migrazione: backup dello stato e test di rollback.

Esempio “docker run” con Postgres (semplificato):
docker run -it –rm \
–name n8n \
-p 5678:5678 \
-e DBTYPE=postgresdb \
-e DBPOSTGRESDBHOST=postgres \
-e DBPOSTGRESDBPORT=5432 \
-e DBPOSTGRESDBDATABASE=n8n \
-e DBPOSTGRESDBUSER=n8n \
-e DBPOSTGRESDBPASSWORD=$POSTGRESPASSWORD \
-e N8NENCRYPTIONKEY=$N8NENCRYPTIONKEY \
-v n8n_data:/home/node/.n8n \
docker.n8n.io/n8nio/n8n

[IMG: Console con variabili DB* impostate e volume n8ndata montato]

Scaling in produzione: queue mode con Redis e più processi

Per abilitare lo scaling:

  • EXECUTIONS_MODE=queue su main e worker.
  • Redis per la coda; variabili tipiche:
  • QUEUEBULLREDISHOST e QUEUEBULLREDISPORT per connessioni standard
  • QUEUEBULLREDISCLUSTERNODES per cluster (host:port separati da virgola)
  • QUEUEBULLREDIS_TLS=true per TLS verso Redis
  • N8NMULTIMAINSETUPENABLED=true su tutti i processi “main” quando ne hai più dietro LB (richiede sticky sessions).

Note:

  • Postgres consigliato (SQLite non raccomandato in queue).
  • I webhook processor sono componenti opzionali per scalare gli ingressi webhook; ricordati EXECUTIONS_MODE=queue anche lì e routing corretto dei path (webhook/webhook-test).

Esempio docker-compose con main+worker+Redis+Postgres:

services:
  n8n-main:
    image: n8nio/n8n:latest
    container_name: n8n-main
    environment:
      - N8N_HOST=n8n.example.com
      - N8N_PROTOCOL=https
      - N8N_EDITOR_BASE_URL=https://n8n.example.com
      - WEBHOOK_URL=https://n8n.example.com/
      - N8N_LISTEN_ADDRESS=0.0.0.0
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - EXECUTIONS_MODE=queue
      - N8N_MULTI_MAIN_SETUP_ENABLED=true
      - QUEUE_BULL_REDIS_HOST=redis
      - QUEUE_BULL_REDIS_PORT=6379
    ports:
      - "5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on: [postgres, redis]

  n8n-worker:
    image: n8nio/n8n:latest
    command: worker
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=redis
      - QUEUE_BULL_REDIS_PORT=6379
    depends_on: [postgres, redis]

  postgres:
    image: postgres:13
    environment:
      - POSTGRES_USER=n8n
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=n8n
    volumes:
      - pg_data:/var/lib/postgresql/data

  redis:
    image: redis:7

volumes:
  n8n_data:
  pg_data:

[IMG: Canvas di scaling: LB (sticky) → n8n-main (queue) → n8n-worker → Redis → Postgres]

Sicurezza e gestione segreti: cifratura, TLS e repository puliti

Punti chiave:

  • Non committare file .env con segreti. Usa secret manager, Docker/K8s Secrets o _FILE.
  • N8NENCRYPTIONKEY va trattata come segreto e salvata nei backup.
  • TLS end‑to‑end: abilita HTTPS a monte (reverse proxy) o usa N8NSSLKEY/N8NSSLCERT se termini TLS in n8n.
  • Editor pubblico: N8NEDITORBASE_URL deve puntare all’URL corretto; limita l’accesso di amministrazione.
  • Per integrazioni che richiedono HTTPS nei webhook (es. Telegram Trigger), assicurati WEBHOOK_URL in HTTPS e certificati validi.

Esempio con _FILE (secrets):

  • DBPOSTGRESDBPASSWORDFILE=/run/secrets/pgpassword
  • N8NENCRYPTIONKEYFILE=/run/secrets/n8nencryption_key

[IMG: Pannello secrets Docker/K8s con mapping a variabili _FILE]

Rete e proxy: porte, base path e variabili proxy

Rete di base:

  • N8NPORT e N8NLISTEN_ADDRESS determinano binding locale.
  • N8N_PROTOCOL influisce su come n8n costruisce URL di servizio.

Proxy e base URL:

  • WEBHOOK_URL imposta l’URL pubblico dei webhook quando sei dietro reverse proxy.
  • Personalizza i path degli endpoint con N8NENDPOINTWEBHOOK*, aggiornando le regole del proxy.

Proxy HTTP/HTTPS:

  • HTTPPROXY e HTTPSPROXY per instradare il traffico dei nodi (rispettano precedenze del pacchetto proxy-from-env; le versioni in minuscolo hanno priorità se presenti).
  • Evita configurazioni duplicate o conflittuali (httpproxy vs HTTPPROXY).

[IMG: Schema reverse proxy con header X-Forwarded-* e inoltro a n8n interno]

Troubleshooting: problemi comuni e come risolverli

Webhook non raggiungibili

  • Sintomi: errori su trigger (es. Telegram Trigger) o callback falliti.
  • Fix: configura WEBHOOKURL con URL pubblico HTTPS; verifica certificati TLS sul proxy; sincronizza i path N8NENDPOINT_WEBHOOK* con il routing del LB.

Errori DB

  • Sintomi: connessioni rifiutate, timeout, migrazioni fallite.
  • Fix: controlla DBTYPE=postgresdb e i parametri DBPOSTGRESDB_*; verifica reachability del servizio e permessi; aumenta risorse se il pool satura.

Variabili non applicate

  • Sintomi: comportamento invariato dopo update.
  • Fix: attenzione a typo nei nomi; verifica con docker compose config / printenv nel container; riavvia il servizio per applicare.

Limiti payload

  • Sintomi: 413 o body troncati su Webhook.
  • Fix: aumenta N8NPAYLOADSIZE_MAX (solo se necessario) e allinea i limiti sul reverse proxy.

Queue mode e bilanciamento

  • Sintomi: sessioni perse, comportamenti incoerenti.
  • Fix: abilita sticky sessions; N8NMULTIMAINSETUPENABLED=true su main multipli; versioni allineate tra main/worker.

[IMG: Tabella “Sintomo → Causa → Variabile/Fix” per 5 casi ricorrenti]

Template Docker Compose per produzione: pronto all’uso

version: "3.8"
services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    environment:
      - N8N_HOST=n8n.example.com
      - N8N_PROTOCOL=https
      - N8N_EDITOR_BASE_URL=https://n8n.example.com
      - WEBHOOK_URL=https://n8n.example.com/
      - N8N_LISTEN_ADDRESS=0.0.0.0
      - N8N_ENDPOINT_WEBHOOK=webhook
      - N8N_ENDPOINT_WEBHOOK_TEST=webhook-test
      - N8N_ENDPOINT_WEBHOOK_WAIT=webhook-waiting
      - N8N_PAYLOAD_SIZE_MAX=16777216
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD_FILE=/run/secrets/pg_password
      - N8N_ENCRYPTION_KEY_FILE=/run/secrets/n8n_encryption_key
      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=redis
      - QUEUE_BULL_REDIS_PORT=6379
    ports:
      - "5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on: [postgres, redis]
    secrets:
      - pg_password
      - n8n_encryption_key

  postgres:
    image: postgres:13
    environment:
      - POSTGRES_USER=n8n
      - POSTGRES_PASSWORD_FILE=/run/secrets/pg_password
      - POSTGRES_DB=n8n
    volumes:
      - pg_data:/var/lib/postgresql/data
    secrets:
      - pg_password

  redis:
    image: redis:7

secrets:
  pg_password:
    file: ./secrets/pg_password
  n8n_encryption_key:
    file: ./secrets/n8n_encryption_key

volumes:
  n8n_data:
  pg_data:

[IMG: Vista Docker Compose con secrets montati e volumi persistenti]

Quick Takeaways

  • Imposta URL e webhook in modo esplicito dietro proxy: N8NHOST/N8NPROTOCOL/N8NEDITORBASEURL e WEBHOOKURL.
  • Passa a Postgres con DBTYPE=postgresdb e DBPOSTGRESDB*, monta /home/node/.n8n e imposta N8NENCRYPTION_KEY.
  • Scala con EXECUTIONSMODE=queue e Redis (QUEUEBULLREDIS*), abilitando sticky sessions e, se servono, più main con N8NMULTIMAINSETUPENABLED.
  • Personalizza i path degli endpoint con N8NENDPOINTWEBHOOK*, e adegua il proxy.
  • Usa _FILE e secret manager; non committare segreti. Riavvia sempre il servizio dopo modifiche alle variabili.
  • Risolvi i 413 sui webhook con N8NPAYLOADSIZE_MAX e limiti proxy allineati.

Conclusione

Le variabili d’ambiente sono il linguaggio con cui “parli” all’istanza n8n in produzione. Con poche impostazioni mirate definisci URL pubblici affidabili, webhooks raggiungibili, database robusto, cifratura sicura e uno scaling prevedibile in queue mode. Un hosting self managed n8n ben configurato significa meno incidenti, meno tempo speso in diagnosi e più focus su automazioni che generano valore. Parti dal template Docker Compose proposto, adatta N8NHOST/WEBHOOKURL ai tuoi domini, porta i dati su PostgreSQL e abilita Redis se prevedi carichi crescenti. Tieni i segreti fuori dal repo con _FILE e secret manager, e documenta le tue scelte per ambienti dev/stage/prod. Con questa base solida, potrai far crescere i workflow senza “impastare” configurazioni, ottenendo una piattaforma di automazione più sicura, scalabile e produttiva.

FAQ

1) Come imposto correttamente gli URL pubblici e i webhook dietro proxy?
Definisci N8NHOST/N8NPROTOCOL/N8NEDITORBASEURL e soprattutto WEBHOOKURL con l’URL pubblico completo (HTTPS). Se personalizzi i path, usa N8NENDPOINTWEBHOOK*, e aggiorna le regole del reverse proxy.

2) Quali variabili servono per usare PostgreSQL?
Imposta DBTYPE=postgresdb e configura DBPOSTGRESDBHOST/PORT/DATABASE/USER/PASSWORD (e opzionalmente SCHEMA/SSL). Monta /home/node/.n8n e imposta N8NENCRYPTION_KEY per la cifratura credenziali.

3) Come abilito lo scaling con queue mode?
Imposta EXECUTIONSMODE=queue su main e worker, collega Redis con QUEUEBULLREDISHOST/PORT (o QUEUEBULLREDISCLUSTERNODES, TLS se richiesto). Con più main dietro LB, usa N8NMULTIMAINSETUPENABLED=true e sticky sessions.

4) Come gestisco i segreti in modo sicuro?
Usa FILE per caricarli da file (es. DBPOSTGRESDBPASSWORDFILE, N8NENCRYPTIONKEY_FILE) e secret manager di Docker/K8s. Non committare mai .env con segreti. Riavvia il servizio dopo modifiche.

5) Perché i miei webhook falliscono o restituiscono 413?
Controlla WEBHOOKURL (HTTPS e host corretti), i path N8NENDPOINTWEBHOOK*, e aumenta N8NPAYLOADSIZEMAX solo se necessario. Allinea anche i limiti del reverse proxy e verifica i certificati TLS.

Ci dai una mano?

Quale sezione configurerai per prima: URL/webhook dietro proxy o migrazione a PostgreSQL? Raccontacelo e condividi l’articolo con il tuo team: mettiamo in sicurezza e in scala il vostro n8n in poche mosse!

Articoli correlati

Vuoi automazioni AI su misura per la tua azienda?
Scopri la consulenza →
, , , , , , ,