Installazione di n8n AI Starter Kit con Ollama

Il Self-hosted AI Starter Kit è un template Docker Compose del team n8n per creare workflow di IA che vengono eseguiti interamente sul vostro server. Prompt e documenti vengono elaborati da un modello linguistico locale e non vengono inviati a servizi di IA esterni.

Il kit comprende quattro componenti:

• n8n, la piattaforma di automazione dei workflow con nodi di IA;
• Ollama, che esegue localmente modelli linguistici aperti;
• Qdrant, un database vettoriale per archiviare e cercare gli embedding dei documenti;
• PostgreSQL, il database di n8n.

Il kit ufficiale è indicato dai suoi autori come destinato ai test. Al momento della stesura, eseguito come descritto nel suo README, presenta diversi problemi su un server con indirizzo IP pubblico: n8n, Ollama e Qdrant sono esposti a internet, Ollama e Qdrant non hanno autenticazione, i segreti nella configurazione sono gli stessi per ogni installazione e il workflow demo non viene importato. Questa guida installa il kit così com'è e risolve tutti questi problemi con un file di override separato, in modo da poter continuare ad aggiornare il kit dal suo repository.

Questa guida è scritta per Ubuntu 24.04 LTS, n8n 2.47.3, Ollama 0.40.16, Qdrant 1.20.0, Docker 29 e Docker Compose v5.

Prima di iniziare

Vi serviranno:

• un server con Ubuntu 24.04 LTS e accesso root tramite SSH;
• almeno 15 GB di spazio libero su disco: le immagini Docker occupano circa 11 GB e il modello Llama 3.2 predefinito circa 2 GB;
• un dominio o sottodominio per n8n, ad esempio n8n.example.com, con un record A che punti all'indirizzo IPv4 del server.

Tutti i comandi seguenti vengono eseguiti come root. Se lavorate come utente normale con privilegi sudo, aggiungete sudo prima di ogni comando.

Installare Docker

Installate Docker Engine e il plugin Compose dal repository ufficiale di Docker:

apt update && apt install -y ca-certificates curl git
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

Aggiungete il repository:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" > /etc/apt/sources.list.d/docker.list

Installate i pacchetti e verificate le versioni:

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

Scaricare il kit

Clonate il repository in /opt e create il file di configurazione dall'esempio:

cd /opt
git clone https://github.com/n8n-io/self-hosted-ai-starter-kit.git
cd self-hosted-ai-starter-kit
cp .env.example .env

Sostituire i segreti predefiniti

Il file di esempio contiene valori fissi, come password per PostgreSQL e super-secret-key per la chiave di cifratura di n8n. Sono identici in ogni copia del kit, quindi sostituiteli con valori casuali:

sed -i "s/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$(openssl rand -hex 24)/" .env
sed -i "s/^N8N_ENCRYPTION_KEY=.*/N8N_ENCRYPTION_KEY=$(openssl rand -hex 32)/" .env
sed -i "s/^N8N_USER_MANAGEMENT_JWT_SECRET=.*/N8N_USER_MANAGEMENT_JWT_SECRET=$(openssl rand -hex 32)/" .env
chmod 600 .env

N8N_ENCRYPTION_KEY cifra le credenziali che salvate in n8n. N8N_USER_MANAGEMENT_JWT_SECRET firma le sessioni utente.

Chiudere le porte e aggiungere HTTPS

Nel file docker-compose.yml del kit, n8n (porta 5678), Ollama (11434) e Qdrant (6333) sono pubblicati su tutte le interfacce di rete. Docker aggiunge proprie regole firewall per le porte pubblicate, e queste aggirano UFW. Su un server con indirizzo IP pubblico, questo significa che chiunque può aprire l'editor di n8n tramite HTTP in chiaro e usare le API di Ollama e Qdrant, che non hanno autenticazione.

Invece di modificare docker-compose.yml, create accanto ad esso il file docker-compose.override.yml. Docker Compose legge automaticamente questo file e lo applica sopra quello principale. I file del kit restano invariati, quindi aggiornarli dal repository non sovrascrive le vostre impostazioni.

Create /opt/self-hosted-ai-starter-kit/docker-compose.override.yml e sostituite n8n.example.com con il vostro dominio:

services:
  n8n:
    ports: !override
      - "127.0.0.1:5678:5678"
    environment:
      - N8N_HOST=n8n.example.com
      - N8N_PROTOCOL=https
      - N8N_PROXY_HOPS=1
      - N8N_WEBHOOK_URL=https://n8n.example.com/

  ollama-cpu:
    ports: !reset []

  ollama-gpu:
    ports: !reset []

  qdrant:
    ports: !reset []

  caddy:
    image: caddy:2
    restart: unless-stopped
    networks: ['demo']
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:

Ecco cosa modifica questo file:

• n8n resta in ascolto solo su 127.0.0.1 e gli utenti lo raggiungono tramite Caddy su HTTPS;
• Ollama e Qdrant non vengono pubblicati affatto: n8n li raggiunge tramite la rete Docker interna con i nomi ollama e qdrant;
• viene aggiunto Caddy come reverse proxy che ottiene e rinnova un certificato Let's Encrypt, a condizione che il dominio punti al server e le porte 80 e 443 siano aperte;
• i volumi di dati di n8n, PostgreSQL, Qdrant e Ollama restano come definiti nel docker-compose.yml del kit; il file di override non li modifica.

N8N_WEBHOOK_URL imposta l'indirizzo che n8n usa per i webhook, compresa la finestra di chat nell'editor. Il dominio deve risolversi sul vostro server dal computer da cui aprite n8n. In caso contrario, la chat mostra solo il messaggio «Failed to receive response», senza indicare il DNS come causa.

Create /opt/self-hosted-ai-starter-kit/Caddyfile con il vostro dominio:

n8n.example.com {
    reverse_proxy n8n:5678
}

Verificate la configurazione unificata:

docker compose --profile cpu config | grep -A4 "ports:"

Dovrebbero essere elencati solo n8n su 127.0.0.1:5678 e Caddy sulle porte 80 e 443.

Configurare il firewall

Il file di override tiene già i servizi interni del kit fuori dalla rete. UFW blocca tutto il resto del traffico in ingresso verso il server, ad eccezione di SSH, HTTP e HTTPS. Consentite queste porte e abilitate UFW:

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable

Avviare il kit

Avviate lo stack in modalità CPU:

docker compose --profile cpu up -d

Al primo avvio, Docker scarica circa 11 GB di immagini e un container separato scarica il modello Llama 3.2. Ci vorrà un po', a seconda della velocità della connessione. Verificate che il modello sia presente:

docker exec ollama ollama list

L'elenco dovrebbe includere llama3.2:latest.

Verificate che sul server siano aperte solo le porte previste:

ss -tlnp

Le porte 80 e 443 dovrebbero essere aperte su tutte le interfacce, la porta 5678 solo su 127.0.0.1. Le porte 11434 e 6333 non dovrebbero comparire nell'elenco.

Importare il workflow demo

Il kit include un workflow demo e due credenziali demo. Dovrebbero essere importati al primo avvio, ma al momento della stesura il controllo di importazione nel docker-compose.yml del kit non viene mai superato, quindi non viene importato nulla. Eseguite l'importazione manualmente:

docker compose --profile cpu run --rm n8n-import -c "n8n import:credentials --separate --input=/demo-data/credentials"
docker compose --profile cpu run --rm n8n-import -c "n8n import:workflow --separate --input=/demo-data/workflows"

L'opzione -c è obbligatoria: il servizio n8n-import avvia una shell e, senza -c, il comando termina con l'errore «can't open 'n8n'».

Creare l'account owner

Aprite https://n8n.example.com nel browser e create l'account owner: inserite la vostra email, nome e cognome e una password di almeno 8 caratteri con almeno un numero e una lettera maiuscola. Dopo il primo accesso, n8n può mostrare un breve sondaggio e l'offerta di una chiave di licenza gratuita per alcune funzionalità della Community Edition. Entrambi sono facoltativi.

La pagina panoramica elenca il Demo workflow importato.

Correggere le credenziali demo

Le credenziali demo sono state cifrate con la chiave predefinita di .env.example. Dopo che avete sostituito N8N_ENCRYPTION_KEY, n8n non può decifrarle, quindi entrambe devono essere compilate di nuovo. Le impostazioni vengono salvate cifrate con la vostra chiave.

Aprite Overview, andate alla scheda Credentials e aprite Local Ollama service. La connessione non riesce e il campo Base URL mostra http://localhost:11434. All'interno del container di n8n, localhost è n8n stesso, non Ollama.

Impostate Base URL su http://ollama:11434, lasciate vuoto API Key e fate clic su Save. n8n verifica la connessione e mostra Connection tested successfully.

Aprite Local QdrantApi database. Impostate Qdrant URL su http://qdrant:6333, lasciate vuoto API Key e fate clic su Save.

Testare il workflow demo

Aprite Demo workflow. Contiene tre nodi: Chat Trigger riceve un messaggio, Basic LLM Chain lo passa al modello e Ollama Chat Model lo invia a Llama 3.2 in Ollama.

Fate clic su Open chat nella parte inferiore dell'area di lavoro (canvas) e inviate una breve domanda. I nodi diventano verdi man mano che il workflow viene eseguito e la risposta del modello compare nella chat. La prima risposta richiede più tempo, perché Ollama carica il modello in memoria.

Se la chat mostra «Failed to receive response» e il workflow non si avvia, verificate che il dominio in N8N_WEBHOOK_URL si risolva sul vostro server dal vostro computer.

Usare una GPU NVIDIA

Se il server dispone di una GPU NVIDIA, il kit può eseguire Ollama su di essa. A tal fine Docker richiede il NVIDIA Container Toolkit. Se non avete ancora usato la GPU con Docker su questo server, installatelo prima seguendo le istruzioni di Ollama per Docker.

Quindi avviate il kit con il profilo gpu-nvidia invece di cpu:

docker compose --profile gpu-nvidia up -d

Il file di override riportato sopra chiude già la porta di Ollama per questo profilo. Usate lo stesso profilo in tutti gli altri comandi. Ad esempio, l'importazione della demo con il profilo GPU:

docker compose --profile gpu-nvidia run --rm n8n-import -c "n8n import:credentials --separate --input=/demo-data/credentials"
docker compose --profile gpu-nvidia run --rm n8n-import -c "n8n import:workflow --separate --input=/demo-data/workflows"

E l'aggiornamento:

cd /opt/self-hosted-ai-starter-kit
git pull
docker compose --profile gpu-nvidia pull
docker compose --profile gpu-nvidia up -d

Aggiornare il kit

Per aggiornare i file e le immagini del kit, eseguite i comandi con il profilo che utilizzate:

cd /opt/self-hosted-ai-starter-kit
git pull
docker compose --profile cpu pull
docker compose --profile cpu up -d

I vostri file docker-compose.override.yml, Caddyfile e .env non fanno parte del repository, quindi git pull non li modifica.

Prossimi passi

Il kit è pronto per i vostri workflow di IA. Da qui potete:

• scaricare altri modelli con docker exec ollama ollama pull seguito dal nome del modello e selezionarli nel nodo Ollama Chat Model;
• usare Qdrant per cercare nei vostri documenti con i nodi vector store di n8n;
• collegare i vostri servizi e creare workflow che li combinino con il modello locale.

Per un'installazione generale di n8n senza componenti di IA, consultate la guida Installazione di n8n con Docker e PostgreSQL . Spiega anche come eseguire il backup e il ripristino di un database n8n.