Guida all'installazione di n8n su server Linux

Che cos'è n8n?

n8n (pronunciato "n-eight-n") è una piattaforma di automazione dei workflow open-source e auto-ospitabile. Permette di connettere diverse applicazioni e servizi tra loro per automatizzare compiti ripetitivi, il tutto tramite un'interfaccia visiva intuitiva di tipo "drag and drop".

n8n è spesso presentato come un'alternativa auto-ospitata a soluzioni SaaS come Zapier, Make (ex-Integromat) o Microsoft Power Automate, con il vantaggio di mantenere il controllo totale sui propri dati.

Funzionalità principali

+400 integrazioni native: Gmail, Slack, Notion, GitHub, Google Sheets, Stripe, database, API REST, ecc.
Editor visivo di workflow: Creazione di workflow tramite drag-and-drop
Nodi IA integrati: Supporto nativo di OpenAI, Ollama e altri modelli LLM
Esecuzione basata su eventi: Webhook, pianificazione cron, trigger manuali
Codice personalizzato: Possibilità di integrare JavaScript o Python nei workflow
API completa: Gestione programmatica dei workflow
Multi-utente: Gestione dei team e delle autorizzazioni (versione Enterprise)

Casi d'uso tipici

Sincronizzazione automatica dei dati tra applicazioni
Notifiche e avvisi automatizzati
Raccolta e trattamento di lead di marketing
Automazione di report e dashboard
Integrazione con strumenti di IA per l'analisi dei dati
Automazione DevOps (CI/CD, monitoraggio, avvisi)

Versione documentata

Questa guida copre l'installazione di n8n versione 1.123.x (versione stabile raccomandata per la produzione).

ℹ️ Nota: La versione 2.0 è attualmente in beta (dicembre 2025). Porta miglioramenti di sicurezza e stabilità ma richiede una migrazione. Per un ambiente di produzione, raccomandiamo la versione 1.x stabile.

Requisiti

Configurazione hardware

Risorsa	Minimo	Raccomandato (Produzione)
CPU	2 core	4 core
RAM	2 GB	4-8 GB
Storage	10 GB SSD	50 GB SSD
Bandwidth	100 Mbps	1 Gbps

💡 Consiglio: Per workflow complessi o un uso intensivo con molti utenti, prevedere 8 GB di RAM e 4 core CPU minimo.

Software richiesti

Software	Versione minima	Ruolo
Sistema operativo	Debian 12 / Ubuntu 22.04+	OS server
Docker	20.10+	Containerizzazione
Docker Compose	2.0+ (plugin)	Orchestrazione dei container
Nginx	1.18+	Reverse proxy
Certbot	2.0+	Certificati SSL Let's Encrypt

Porti di rete utilizzati

Porto	Protocollo	Uso	Esposizione
22	TCP	SSH	Esterno (amministrazione)
80	TCP	HTTP (reindirizzamento HTTPS)	Esterno
443	TCP	HTTPS	Esterno
5678	TCP	n8n (interno)	Solo localhost
5432	TCP	PostgreSQL (interno)	Solo localhost

Nome di dominio e DNS

Prima di iniziare, assicurati di avere:

Un nome di dominio o sottodominio (es: n8n.iltuodominio.it)
Un record DNS di tipo A che punta all'IP pubblico del tuo server

Esempio di configurazione DNS:

n8n.iltuodominio.it.    IN    A    203.0.113.50

Installazione passo dopo passo

Passo 1: Aggiornamento del sistema

Collegati al tuo server via SSH e aggiorna i pacchetti:

sudo apt update && sudo apt upgrade -y

Questo comando aggiorna l'elenco dei pacchetti disponibili e installa le ultime versioni dei pacchetti installati.

Passo 2: Installazione di Docker

Installa le dipendenze necessarie:

sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

Aggiungi la chiave GPG ufficiale di Docker:

curl -fsSL https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Aggiungi il repository Docker:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/$(. /etc/os-release && echo "$ID") $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Installa Docker Engine e il plugin Compose:

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Aggiungi il tuo utente al gruppo docker (per evitare di usare sudo):

sudo usermod -aG docker $USER
newgrp docker

Punto di verifica: Controlla l'installazione:

docker --version
docker compose version

Dovresti vedere le versioni installate (Docker 24.x+ e Compose 2.x+).

Passo 3: Creazione della struttura delle directory

Crea la directory di lavoro per n8n:

sudo mkdir -p /opt/docker-compose/n8n
cd /opt/docker-compose/n8n

Crea le sottodirectory per i dati persistenti:

sudo mkdir -p n8n_data postgres_data

Assegna i permessi corretti:

sudo chown -R 1000:1000 n8n_data
sudo chown -R 999:999 postgres_data

ℹ️ Spiegazione: Gli UID 1000 e 999 corrispondono rispettivamente agli utenti node (nel container n8n) e postgres (nel container PostgreSQL).

Passo 4: Creazione del file di ambiente

Crea il file .env per memorizzare le variabili sensibili:

sudo nano /opt/docker-compose/n8n/.env

Aggiungi il seguente contenuto modificando i valori:

# ===========================================
# Configurazione n8n - OuiHeberg
# ===========================================

# Dominio e URL
N8N_HOST=n8n.iltuodominio.it
N8N_PORT=5678
N8N_PROTOCOL=https
WEBHOOK_URL=https://n8n.iltuodominio.it/

# Sicurezza
N8N_ENCRYPTION_KEY=LaTuaChiaveDiCrittografia32CaratteriMin!
N8N_PROXY_HOPS=1

# Fuso orario
GENERIC_TIMEZONE=Europe/Rome
TZ=Europe/Rome

# Database PostgreSQL
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_DATABASE=n8n
DB_POSTGRESDB_USER=n8n
DB_POSTGRESDB_PASSWORD=LaTuaPasswordPostgres123!

# Variabili PostgreSQL (per il container)
POSTGRES_DB=n8n
POSTGRES_USER=n8n
POSTGRES_PASSWORD=LaTuaPasswordPostgres123!
POSTGRES_NON_ROOT_USER=n8n
POSTGRES_NON_ROOT_PASSWORD=LaTuaPasswordPostgres123!

⚠️ Importante: Sostituisci assolutamente:

n8n.iltuodominio.it con il tuo dominio reale

LaTuaChiaveDiCrittografia32CaratteriMin! con una chiave unica e complessa (min. 32 caratteri)

LaTuaPasswordPostgres123! con una password sicura

Genera una chiave di crittografia sicura:

openssl rand -hex 32

Passo 5: Creazione del file Docker Compose

Crea il file docker-compose.yml:

sudo nano /opt/docker-compose/n8n/docker-compose.yml

Aggiungi il seguente contenuto:

version: '3.8'

services:
  # ===========================================
  # Database PostgreSQL
  # ===========================================
  postgres:
    image: postgres:15-alpine
    container_name: n8n-postgres
    restart: unless-stopped
    environment:
      - POSTGRES_DB=${POSTGRES_DB}
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - ./postgres_data:/var/lib/postgresql/data
    networks:
      - n8n-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5

  # ===========================================
  # Applicazione n8n
  # ===========================================
  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      # Configurazione generale
      - N8N_HOST=${N8N_HOST}
      - N8N_PORT=${N8N_PORT}
      - N8N_PROTOCOL=${N8N_PROTOCOL}
      - WEBHOOK_URL=${WEBHOOK_URL}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - N8N_PROXY_HOPS=${N8N_PROXY_HOPS}
      # Fuso orario
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - TZ=${TZ}
      # Database
      - DB_TYPE=${DB_TYPE}
      - DB_POSTGRESDB_HOST=${DB_POSTGRESDB_HOST}
      - DB_POSTGRESDB_PORT=${DB_POSTGRESDB_PORT}
      - DB_POSTGRESDB_DATABASE=${DB_POSTGRESDB_DATABASE}
      - DB_POSTGRESDB_USER=${DB_POSTGRESDB_USER}
      - DB_POSTGRESDB_PASSWORD=${DB_POSTGRESDB_PASSWORD}
    ports:
      - "127.0.0.1:5678:5678"
    volumes:
      - ./n8n_data:/home/node/.n8n
    networks:
      - n8n-network

networks:
  n8n-network:
    driver: bridge

💡 Nota: La porta 5678 è esposta solo su 127.0.0.1 (localhost) per motivi di sicurezza. L'accesso esterno avverrà tramite il reverse proxy Nginx.

Passo 6: Avvio dei container

Avvia i container in background:

cd /opt/docker-compose/n8n
docker compose up -d

Punto di verifica: Controlla che i container siano in esecuzione:

docker compose ps

Dovresti vedere i due container (n8n e n8n-postgres) con lo stato Up o running (healthy).

Controlla i log in caso di problemi:

docker compose logs -f n8n

Testa l'accesso locale:

curl http://localhost:5678/healthz

La risposta dovrebbe essere {"status":"ok"}.

Configurazione

Configurazione del reverse proxy Nginx

Installazione di Nginx

sudo apt install -y nginx

Controlla che Nginx sia attivo:

sudo systemctl status nginx

Creazione del file di configurazione

Crea il file di configurazione per n8n:

sudo nano /etc/nginx/sites-available/n8n

Aggiungi il seguente contenuto:

# ===========================================
# Configurazione Nginx per n8n - OuiHeberg
# ===========================================

# Mappa per la gestione dei WebSocket
map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

# Reindirizzamento HTTP verso HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name n8n.iltuodominio.it;

    # Reindirizzamento permanente verso HTTPS
    return 301 https://$host$request_uri;
}

# Configurazione HTTPS
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name n8n.iltuodominio.it;

    # Certificati SSL (saranno configurati da Certbot)
    # ssl_certificate /etc/letsencrypt/live/n8n.iltuodominio.it/fullchain.pem;
    # ssl_certificate_key /etc/letsencrypt/live/n8n.iltuodominio.it/privkey.pem;

    # Parametri SSL raccomandati
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;

    # Intestazioni di sicurezza
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Dimensione massima degli upload (importante per i workflow con file)
    client_max_body_size 50M;

    # Timeout per i workflow lunghi
    proxy_connect_timeout 300;
    proxy_send_timeout 300;
    proxy_read_timeout 300;

    location / {
        proxy_pass http://127.0.0.1:5678;
        proxy_http_version 1.1;
        
        # Supporto WebSocket (essenziale per l'editor n8n)
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        
        # Intestazioni proxy
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        
        # Disattivazione del buffering per eventi in tempo reale
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding off;
    }
}

⚠️ Importante: Sostituisci n8n.iltuodominio.it con il tuo dominio reale.

Attiva la configurazione:

sudo ln -s /etc/nginx/sites-available/n8n /etc/nginx/sites-enabled/

Rimuovi la configurazione predefinita se esiste:

sudo rm -f /etc/nginx/sites-enabled/default

Testa la configurazione di Nginx:

sudo nginx -t

Ottenimento del certificato SSL Let's Encrypt

Installa Certbot con il plugin Nginx:

sudo apt install -y certbot python3-certbot-nginx

Ottieni il certificato SSL:

sudo certbot --nginx -d n8n.iltuodominio.it

Segui le istruzioni:

Inserisci il tuo indirizzo email
Accetta i termini di utilizzo
Scegli se desideri condividere la tua email con l'EFF
Certbot configurerà automaticamente Nginx per HTTPS

Punto di verifica: Controlla il rinnovo automatico:

sudo certbot renew --dry-run

Riavvia Nginx per applicare tutte le modifiche:

sudo systemctl restart nginx

Variabili d'ambiente importanti

Variabile	Descrizione	Valore predefinito
`N8N_HOST`	Nome di dominio dell'istanza	localhost
`N8N_PORT`	Porto di ascolto interno	5678
`N8N_PROTOCOL`	Protocollo (http/https)	http
`WEBHOOK_URL`	URL pubblico per i webhook	-
`N8N_ENCRYPTION_KEY`	Chiave di crittografia delle credenziali	-
`N8N_PROXY_HOPS`	Numero di proxy davanti a n8n	0
`GENERIC_TIMEZONE`	Fuso orario	UTC
`DB_TYPE`	Tipo di BDD (postgresdb/sqlite)	sqlite
`N8N_METRICS`	Attivare le metriche Prometheus	false
`N8N_LOG_LEVEL`	Livello di log (info/debug/warn/error)	info

Primo utilizzo

Accesso all'interfaccia

Apri il tuo browser e accedi a:

https://n8n.iltuodominio.it

Configurazione iniziale

Al primo accesso, n8n ti chiederà di creare un account proprietario:

Email: Inserisci il tuo indirizzo email professionale
Nome e Cognome: Le tue informazioni di identità
Password: Scegli una password forte (min. 8 caratteri, maiuscole, numeri, caratteri speciali)

Creazione dell'account amministratore

Dopo aver compilato il modulo:

Clicca su "Create account" (Crea un account)
Una popup appare per attivare la licenza comunitaria (gratuita)
Clicca su "Activate" per beneficiare di tutte le funzionalità self-hosted

💡 Consiglio: La licenza comunitaria è gratuita e dà accesso a tutte le funzionalità di automazione senza restrizioni.

Primo workflow

Per testare la tua installazione:

Clicca su "Create Workflow" nel menu laterale
Clicca sul "+" per aggiungere un nodo
Cerca "Schedule Trigger" e aggiungilo
Aggiungi un nodo "Set" per definire dei dati
Collega i due nodi
Clicca su "Execute Workflow" per testare

Manutenzione

Aggiornamento di n8n

Per aggiornare n8n all'ultima versione:

cd /opt/docker-compose/n8n

# Arresto dei container
docker compose down

# Download della nuova immagine
docker compose pull

# Riavvio
docker compose up -d

# Verifica
docker compose ps

⚠️ Prima di qualsiasi aggiornamento maggiore (es: 1.x verso 2.x), consulta le note di rilascio e fai un backup completo.

Backup

Backup completo (raccomandato)

Crea uno script di backup /opt/docker-compose/n8n/backup.sh:

#!/bin/bash
# ===========================================
# Script di backup n8n - OuiHeberg
# ===========================================

BACKUP_DIR="/opt/backups/n8n"
DATE=$(date +%Y%m%d_%H%M%S)
N8N_DIR="/opt/docker-compose/n8n"

# Creazione della directory di backup
mkdir -p $BACKUP_DIR

# Backup del database PostgreSQL
docker exec n8n-postgres pg_dump -U n8n n8n > $BACKUP_DIR/n8n_db_$DATE.sql

# Backup dei file n8n
tar -czf $BACKUP_DIR/n8n_data_$DATE.tar.gz -C $N8N_DIR n8n_data

# Backup dei file di configurazione
tar -czf $BACKUP_DIR/n8n_config_$DATE.tar.gz -C $N8N_DIR .env docker-compose.yml

# Pulizia dei backup di oltre 30 giorni
find $BACKUP_DIR -type f -mtime +30 -delete

echo "Backup completato : $DATE"

Rendi lo script eseguibile e pianificalo:

sudo chmod +x /opt/docker-compose/n8n/backup.sh

# Aggiunta al cron (backup quotidiano alle 3 del mattino)
echo "0 3 * * * /opt/docker-compose/n8n/backup.sh >> /var/log/n8n-backup.log 2>&1" | sudo tee -a /etc/crontab

Ripristino

Per ripristinare da un backup:

cd /opt/docker-compose/n8n

# Arresto dei contenitori
docker compose down

# Ripristino del database
cat /opt/backups/n8n/n8n_db_YYYYMMDD_HHMMSS.sql | docker exec -i n8n-postgres psql -U n8n n8n

# Ripristino dei file n8n
tar -xzf /opt/backups/n8n/n8n_data_YYYYMMDD_HHMMSS.tar.gz -C /opt/docker-compose/n8n/

# Riavvio
docker compose up -d

Log e monitoraggio

Consultazione dei log

# Log n8n in tempo reale
docker compose logs -f n8n

# Log PostgreSQL
docker compose logs -f postgres

# Ultime 100 righe di log n8n
docker compose logs --tail=100 n8n

Verifica dello stato dei servizi

# Stato dei contenitori
docker compose ps

# Utilizzo delle risorse
docker stats n8n n8n-postgres

# Spazio su disco utilizzato
docker system df

Endpoint di salute

n8n espone un endpoint di salute accessibile localmente:

curl http://localhost:5678/healthz

Risoluzione dei problemi

Problemi comuni e soluzioni

1. "Connection lost" nell'editor

Cause : Problema di WebSocket con il reverse proxy.

Soluzione :

# Controlla la configurazione Nginx
sudo nginx -t

# Assicurati che queste righe siano presenti nella configurazione Nginx :
# proxy_set_header Upgrade $http_upgrade;
# proxy_set_header Connection $connection_upgrade;

2. I webhook non funzionano

Cause : URL del webhook errato o variabile WEBHOOK_URL non definita.

Soluzione :

Controlla il file .env :

grep WEBHOOK_URL /opt/docker-compose/n8n/.env

L'URL deve essere https://n8n.votredomaine.fr/
Riavvia n8n dopo la modifica :
```
docker compose restart n8n
```

3. Errore "EACCES: permission denied"

Cause : Permessi errati sui volumi.

Soluzione :

sudo chown -R 1000:1000 /opt/docker-compose/n8n/n8n_data
sudo chown -R 999:999 /opt/docker-compose/n8n/postgres_data
sudo chmod -R 755 /opt/docker-compose/n8n/n8n_data

4. "Connection to database failed"

Cause : PostgreSQL non è pronto o credenziali errate.

Soluzione :

Controlla lo stato di PostgreSQL :
```
docker compose logs postgres
```
Controlla la coerenza delle variabili in .env

Testa la connessione :

docker exec -it n8n-postgres psql -U n8n -d n8n -c "SELECT 1;"

5. L'interfaccia è lenta o non risponde

Cause : Risorse insufficienti.

Soluzione :

# Controlla l'utilizzo delle risorse
docker stats

# Se la RAM è satura, aumentala o aggiungi limiti :
# Nel docker-compose.yml, sotto il servizio n8n :
# deploy:
#   resources:
#     limits:
#       memory: 2G

Comandi di diagnostica

# Stato completo del sistema Docker
docker system info

# Ispezione del contenitore n8n
docker inspect n8n

# Verifica delle reti Docker
docker network ls
docker network inspect n8n_n8n-network

# Test di connettività interna
docker exec n8n ping -c 3 postgres

# Verifica delle porte utilizzate
sudo netstat -tlnp | grep -E "80|443|5678"

Dove trovare aiuto

Documentazione ufficiale : https://docs.n8n.io
Forum comunitario : https://community.n8n.io
GitHub Issues : https://github.com/n8n-io/n8n/issues
Discord : Server comunitario n8n

Risorse

Link ufficiali

Risorsa	URL
Sito ufficiale	https://n8n.io
Documentazione	https://docs.n8n.io
GitHub	https://github.com/n8n-io/n8n
Docker Hub	https://hub.docker.com/r/n8nio/n8n
Forum	https://community.n8n.io
Note di rilascio	https://docs.n8n.io/release-notes/
Blog ufficiale	https://blog.n8n.io

Template di workflow

n8n offre una libreria di workflow pronti all'uso :

https://n8n.io/workflows

Integrazioni popolari

Google Workspace (Gmail, Sheets, Drive, Calendar)
Slack, Discord, Microsoft Teams
GitHub, GitLab, Bitbucket
Notion, Airtable, Coda
Stripe, PayPal
OpenAI, Anthropic, Ollama

Appendice : Configurazione avanzata

Attivazione delle metriche Prometheus

Aggiungi nel file .env :

N8N_METRICS=true
N8N_METRICS_PREFIX=n8n_

Le metriche saranno disponibili su http://localhost:5678/metrics.

Configurazione SMTP per le notifiche

Aggiungi nel file .env :

N8N_EMAIL_MODE=smtp
N8N_SMTP_HOST=smtp.votredomaine.fr
N8N_SMTP_PORT=587
[email protected]
N8N_SMTP_PASS=LaTuaPasswordSMTP
[email protected]
N8N_SMTP_SSL=false

Modalità coda con Redis (alta disponibilità)

Per i deployment ad alto carico, n8n supporta una modalità "coda" con Redis :

# Aggiungi questo servizio in docker-compose.yml
redis:
  image: redis:7-alpine
  container_name: n8n-redis
  restart: unless-stopped
  networks:
    - n8n-network

E queste variabili in .env :

EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=redis
QUEUE_BULL_REDIS_PORT=6379

Guida redatta da OuiHeberg - Dicembre 2025 Ultimo aggiornamento : 12/12/2025

Guida all'installazione di n8n su server Linux