Come installare Dify su un VPS con Docker Compose

Che cos’è Dify e cosa comporta eseguire il servizio

Dify è una piattaforma self-hosted per creare applicazioni basate su modelli linguistici di grandi dimensioni. Offre un’interfaccia web per progettare applicazioni di chat, agenti e pipeline di retrieval, un’API per richiamarli dal proprio codice e un unico punto per gestire prompt, dataset e chiavi dei modelli. È lo strumento che un piccolo team installa per lavorare tutti sulla stessa base privata, invece di distribuire le chiavi API in vari script. Se termini come agente, chiamata a uno strumento e pipeline di retrieval non sono ancora chiari, ripartire dalle basi per comprendere questi concetti renderà le schermate del builder di Dify più simili a controlli comprensibili che a un insieme di opzioni senza etichette.

Eseguire Dify in autonomia significa gestire diversi componenti. Dify viene distribuito come un insieme di container Docker: un server API, un worker in background, un frontend web, un database Postgres, una cache Redis e un database vettoriale, tutti collegati tramite Docker Compose. Non si tratta di un singolo binario, ma Compose gestisce i collegamenti e un VPS con un paio di gigabyte di RAM disponibili lo esegue senza difficoltà. Se sullo stesso VPS devono essere eseguiti anche altri servizi, dimensionarlo sulla base di valori misurati e non di quelli dichiarati, perché i requisiti reali di RAM di PhotoPrism e Immich sono molto superiori ai minimi pubblicati e un server fotografico che condivide la macchina esaurirà prima le risorse del database e del vector store di Dify. Lo stesso vale per la contesa della CPU: una libreria Jellyfin trasformata nell’aspetto in un videonoleggio degli anni 90 richiede pochissime risorse quando si limita alla consultazione delle copertine, ma non appena qualcuno avvia una transcodifica, le code dei worker di Dify devono attendere. Il vantaggio è che il numero di container di Dify rimane fisso indipendentemente dal numero di applicazioni create, con una crescita dei costi più prevedibile rispetto a OpenBot, in cui ogni collega AI ha il proprio container e il proprio browser, e ogni nuova aggiunta aumenta ulteriormente il requisito minimo di memoria.

Poiché Dify conserva le chiavi API dei modelli e spesso anche documenti privati caricati per il retrieval, considera sensibile il server su cui viene eseguito fin dal primo momento. Questa guida installa Dify e poi ne rafforza la configurazione come faresti con qualsiasi servizio che gestisce secret.

Prerequisiti

Serve un VPS con Ubuntu 24.04, Docker e il plugin Docker Compose installati, oltre a un utente con sudo oppure appartenente al gruppo docker. Se Docker è una novità, le nozioni di base di Docker Compose su un VPS spiegano l’installazione e i comandi principali presupposti da questa guida. È consigliabile avere un nome di dominio puntato al server, perché conviene usare TLS davanti a Dify invece di un semplice indirizzo IP.

Passaggio 1: Scaricare Dify e i relativi file Compose

Dify include la configurazione Docker nel repository principale. Clonalo e accedi alla directory docker:

git clone https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env

Il file .env contiene l’intera configurazione. Leggilo prima di avviare qualsiasi componente. I primi valori da controllare sono quelli che definiscono password e secret: SECRET_KEY, la password di Postgres e la password di Redis. Il file di esempio contiene valori segnaposto. Lasciarli invariati è il modo più comune con cui un’installazione self-hosted di Dify viene compromessa. Genera una chiave secret reale:

openssl rand -base64 42

Incollala in SECRET_KEY e imposta un valore forte e univoco per ogni campo relativo alle password nel file.

Passaggio 2: Avvio

Avvia lo stack:

docker compose up -d

La prima esecuzione scarica diverse immagini e inizializza il database, quindi attendi un minuto. Verifica che i container siano in stato healthy:

docker compose ps

Ogni servizio dovrebbe leggere running. Per impostazione predefinita, Dify pubblica la propria interfaccia web tramite un container nginx incluso, sulla porta 80. Alla prima visita a http://YOUR_SERVER/install crea l'account amministratore. Esegui subito questa operazione, prima che altro possa raggiungere la porta, perché finché l'account non esiste chiunque carichi la pagina può registrarlo e assumere il controllo della tua istanza.

Passaggio 3: non esporlo direttamente. Metti TLS e un firewall davanti

È qui che terminano la maggior parte delle installazioni rapide e iniziano la maggior parte degli incidenti. Il server nginx incluso in Dify è in ascolto sulla porta 80, senza cifratura, su tutte le interfacce. Le credenziali di accesso amministrativo e le chiavi dei modelli non devono transitare su HTTP in chiaro. Inoltre, i servizi interni non devono essere raggiungibili dall'esterno.

Proteggi il server con un firewall in modalità deny predefinita, consentendo soltanto SSH e il traffico web:

sudo ufw default deny incoming
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Ricorda che un firewall che copre soltanto IPv4 può lasciare aperte le stesse porte su IPv6: è il problema del firewall IPv6 che colpisce molti utenti che gestiscono servizi self-hosted. Verifica che entrambi gli stack siano filtrati.

Per TLS, la soluzione più pulita consiste nel collegare la porta web di Dify all'interfaccia di loopback e mettere davanti un reverse proxy con un certificato Let's Encrypt. In questo modo, su Internet è esposto soltanto il proxy, che comunica tramite HTTPS. .env di Dify consente di modificare la porta esposta; impostalo in modo che si colleghi a 127.0.0.1 e configura il proxy perché inoltri le richieste a quell'indirizzo. I principi per rendere sicuri gli agenti descritti in eseguire in sicurezza un agente AI su un VPS si applicano anche qui: mantieni i componenti sulla loopback, esponi soltanto ciò che deve essere pubblico e lascia che un unico punto di accesso protetto gestisca TLS. Se l'interfaccia di uno strumento è destinata esclusivamente a te e non richiede mai un certificato, puoi evitare il proxy e raggiungerla tramite un tunnel SSH, come avviene in self-hosting dello scanner di sicurezza open-kritt, dove la dashboard resta collegata alla loopback e viene inoltrata al laptop invece di essere pubblicata. Se un intero team deve usare Dify ma non vuoi esporlo su Internet, una rete overlay estende questo approccio oltre un singolo laptop: pubblicare la subnet privata del server sulla tua tailnet consente a ogni dispositivo autorizzato di raggiungere il builder tramite un indirizzo privato, mentre il firewall continua a bloccare tutto tranne SSH. Se amministri questo server tramite un agente di coding invece che manualmente, stabilisci prima quali operazioni possa eseguire senza supervisione, perché la modalità dei permessi in cui lasci Claude Code determina se si fermerà per chiedere conferma prima di riscrivere .env o riavviare lo stack. Se una sessione segue i log dei container mentre un'altra modifica la configurazione del proxy, queste due sessioni possono scambiarsi testo sullo stesso server: è più pratico che copiare ogni volta l'output tra i terminali quando riavvii lo stack.

Passaggio 4: Mantieni il sistema aggiornato

Dify evolve rapidamente e gli aggiornamenti includono correzioni di sicurezza. Per aggiornare, esegui un pull e riavvia i container dalla directory docker:

git pull
docker compose pull
docker compose up -d

Leggi le note di rilascio prima di passare a una versione principale successiva, perché Dify a volte modifica lo schema .env tra una release e l’altra. Inoltre, una nuova variabile non configurata può impedire l’avvio di un container.

Passaggio 5: esegui il backup di ciò che non puoi rigenerare

Due elementi di un'installazione Dify sono insostituibili: il database Postgres, che contiene applicazioni, utenti e impostazioni, e il volume che memorizza i documenti caricati e l'indice vettoriale. Entrambi si trovano nei volumi Docker nella directory docker. Crea snapshot secondo una pianificazione e copia gli snapshot fuori dal server. Questi snapshot contengono tutte le chiavi dei modelli e i documenti caricati in un unico file, quindi cifrali prima di trasferirli fuori dal server, per lo stesso motivo per cui un backup di Vaultwarden può rivelarsi il punto debole di un server per le password altrimenti solido. Una chiave API di un modello può essere rigenerata; l'applicazione a cui hai dedicato una settimana no. Lo stesso principio vale per qualsiasi agente il cui stato debba sopravvivere alla macchina su cui viene eseguito: mantenere KiroCrew in esecuzione come container sempre attivo significa creare snapshot della memoria e delle pianificazioni che altrimenti scomparirebbero al riavvio successivo.

Quando vuoi che gli agenti creati qui possano andare oltre i tuoi dataset e cercare sul web in tempo reale, indirizzarli a un'istanza SearXNG self-hosted mantiene il flusso delle query sull'hardware che controlli, anche se è opportuno informarsi sulla superficie di attacco del prompt injection che si apre prima di abilitarla. Per un agente più autonomo, in grado di eseguire codice, consulta self-hosting di Agent Zero; creare un tuo agente AI su un VPS illustra invece le basi comuni a tutte queste soluzioni.

FAQ

Quali sono i requisiti di sistema per eseguire Dify in self-hosting?

Dify viene eseguito come stack Docker Compose composto da circa sei container. Pianifica quindi un VPS con almeno 2 GB di RAM liberi, idealmente 4 GB, oltre a un paio di core CPU e spazio disco sufficiente per i documenti caricati e l'indice vettoriale. La pressione sulla memoria dipende dal database e dal vector store, non da Dify.

È sicuro esporre direttamente Dify sulla porta 80?

No. Il web server incluso in Dify resta in ascolto su HTTP non cifrato e gestisce l'accesso amministrativo e le API key dei modelli. Configura un reverse proxy con un certificato Let's Encrypt davanti a Dify, associa la porta del servizio Dify al loopback e consenti solo al proxy HTTPS di essere esposto a Internet. Abbina questa configurazione a un firewall con criterio default-deny che copra sia IPv4 sia IPv6.

Come si aggiorna un'installazione Dify in self-hosting?

Dalla directory docker, esegui git pull, quindi docker compose pull e docker compose up -d per scaricare le nuove immagini e riavviare i container. Leggi prima le note di rilascio, perché tra una versione e l'altra Dify può aggiungere nuove variabili .env e una variabile mancante può impedire l'avvio di un container.

Qual è la prima operazione da eseguire dopo aver installato Dify?

Apri /install e crea subito l'account amministratore. Finché l'account non esiste, chiunque possa raggiungere la pagina può registrarlo. Configuralo non appena i container risultano operativi e prima di esporre il firewall a Internet.