Come installare Dify su un VPS con Docker Compose

Che cos’è Dify e cosa comporta eseguirlo

Dify è una piattaforma self-hostable per creare applicazioni basate su modelli linguistici di grandi dimensioni. Offre un’interfaccia web per progettare app di chat, agenti e pipeline di retrieval, un’API per richiamarli dal proprio codice e un unico punto in cui gestire prompt, dataset e chiavi dei modelli. È lo strumento che un piccolo team può installare affinché tutti lavorino su una base privata condivisa, invece di distribuire chiavi API in vari script. Se termini come agente, chiamata a uno strumento e pipeline di retrieval non sono ancora chiari, partire dalle basi per comprenderli renderà le schermate di progettazione di Dify più simili a controlli familiari che a una parete di interruttori senza etichette.

Eseguirlo autonomamente significa gestire molti componenti. A ottobre 2026, lo stack predefinito documentato di Dify avvia 15 container a esecuzione continuativa, oltre a un’attività eseguita una sola volta che imposta i permessi dei file e termina. Sette sono servizi propri di Dify: il server API, un server websocket, un worker in background, uno scheduler, il frontend web, un demone per i plugin e un backend per gli agenti. Gli altri otto sono dipendenze: un database Postgres, una cache Redis, un database vettoriale Weaviate, un punto di accesso nginx, due sandbox per l’esecuzione del codice e due proxy SSRF. Docker Compose li collega tutti, ma si tratta di uno stack reale, e il minimo documentato da Dify è 4 GiB di RAM e due core CPU. Se quel VPS deve eseguire anche altri servizi, dimensionarlo sulla base di valori misurati anziché di quelli dichiarati, perché i requisiti RAM reali di PhotoPrism e Immich sono molto superiori ai minimi pubblicati e un server fotografico che condivide la macchina consumerà per primi le risorse del database e del database vettoriale di Dify. La contesa sulla CPU produce un effetto analogo: una libreria Jellyfin trasformata in un videonoleggio degli anni 90 richiede risorse quasi nulle durante la semplice consultazione delle copertine, ma appena qualcuno avvia una transcodifica, le code dei worker di Dify devono attenderne il completamento. Il vantaggio è che il numero di container di Dify rimane fisso indipendentemente dal numero di applicazioni create, con un andamento dei costi più prevedibile rispetto a OpenBot, in cui ogni collega AI riceve il proprio container e il proprio browser e ogni nuova aggiunta aumenta nuovamente 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 lo esegui fin dal primo minuto. Questa guida installa Dify e poi lo mette in sicurezza come faresti con qualsiasi servizio che conserva secret.

Prerequisiti

Sono necessari un VPS con Ubuntu 24.04, almeno 4 GiB di RAM e due core CPU, Docker con il plugin Docker Compose installato (Dify richiede Compose 2.24.0 o versioni successive) e un utente con sudo o appartenente al gruppo docker. Il comando di clonazione riportato di seguito usa inoltre git, curl e jq. Se Docker è una novità, le basi di Docker Compose su un VPS illustrano l'installazione e i comandi principali presupposti da questa guida. È consigliabile avere un nome di dominio che punti al server, perché per Dify è preferibile usare TLS invece di esporre un semplice indirizzo IP.

Passo 1: Scaricare Dify e i relativi file Compose

Dify mantiene la configurazione Docker nel repository principale. Clona l'ultima release, non il ramo di sviluppo, quindi accedi alla directory docker:

git clone --branch "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r .tag_name)" https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env

Se il clone non riesce con l'errore "Remote branch null", la ricerca tramite API di GitHub non ha restituito risultati; scegli una versione dalla pagina delle release e passala manualmente a --branch.

Il file .env contiene la configurazione principale. Leggilo prima di avviare qualsiasi operazione. I primi valori da controllare sono quelli che definiscono password e secret: SECRET_KEY, la password di Postgres e la password di Redis. SECRET_KEY viene distribuito vuoto. Se lo lasci così, Dify genera una chiave e la conserva nella propria directory di archiviazione. Per le password il discorso è diverso: il file di esempio imposta lo stesso difyai123456 per Postgres e Redis, oltre a chiavi fisse e pubblicamente note per il sandbox del codice, il plugin daemon e Weaviate. Lasciare questi valori invariati è il modo più comune con cui un'installazione Dify self-hosted viene compromessa. Se preferisci impostare una chiave secret personalizzata, generane una:

openssl rand -base64 42

Incollala in SECRET_KEY e imposta un valore robusto e univoco per ogni campo relativo a password e chiavi nel file. La password di Redis compare anche in CELERY_BROKER_URL, quindi modificala anche lì; in caso contrario il worker non può raggiungere Redis.

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 a esecuzione continua dovrebbe leggere running; l'attività per le autorizzazioni, eseguita una sola volta, termina dopo aver completato il proprio compito. 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 qualsiasi altra persona 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 nginx integrato di Dify è in ascolto sulla porta 80, senza cifratura, su tutte le interfacce, e pubblica anche la porta 443. Non vuoi che le credenziali di accesso amministrativo e le chiavi dei modelli viaggino su HTTP in chiaro. Inoltre, non vuoi che i servizi interni siano raggiungibili dall'esterno.

Proteggi il server con un firewall configurato per negare tutto per impostazione predefinita e consentire 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 sorprende molti utenti che gestiscono servizi self-hosted. Verifica che entrambi gli stack siano filtrati. Tieni inoltre presente che le porte pubblicate da Docker sono gestite dalle regole firewall di Docker, non da quelle di ufw, e che lo stack predefinito pubblica la porta di debug del demone dei plugin, 5003, su tutte le interfacce. Imposta EXPOSE_PLUGIN_DEBUGGING_PORT in .env su 127.0.0.1:5003, a meno che tu non debba realmente eseguire il debug dei plugin da un'altra macchina.

Per TLS, la soluzione più pulita consiste nel vincolare la porta web di Dify al loopback e mettere davanti un reverse proxy con un certificato Let's Encrypt, in modo che su Internet sia esposto soltanto il proxy, che comunica tramite HTTPS. .env di Dify consente di modificare la porta esposta; impostalo in modo che sia associato a 127.0.0.1 e configura il proxy perché inoltri le richieste a quella porta. Fai lo stesso per EXPOSE_NGINX_SSL_PORT, perché il nginx di Dify acquisisce per impostazione predefinita la porta 443 dell'host e il proxy deve poterla utilizzare. I principi per rendere sicuro un agent descritti in eseguire in sicurezza un agent AI su un VPS si applicano anche qui: mantieni i componenti sul 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 serve soltanto a te e non richiede mai un certificato, salta il proxy e raggiungila tramite un tunnel SSH, come in self-hosting dello scanner di sicurezza open-kritt, che mantiene la dashboard associata al loopback e la inoltra al laptop invece di pubblicarla. Se Dify deve essere utilizzato da un intero team, ma non deve essere esposto a 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 coding agent invece che manualmente, stabilisci quanto può fare senza supervisione prima di affidargli le credenziali, 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, le due sessioni possono scambiarsi testo sullo stesso server, evitando di 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. Poiché hai clonato un tag di release, per aggiornare devi effettuare il checkout del tag successivo invece di eseguire il pull di un branch. Esegui prima il backup del database, quindi, dalla directory docker:

docker compose down
git fetch --tags
git checkout NEW_VERSION
docker compose pull
docker compose up -d

Le migrazioni del database vengono eseguite automaticamente all'avvio e alcune non possono essere annullate. Per questo il backup viene eseguito prima. Leggi le note di rilascio prima di ogni aggiornamento, non solo di quelli principali: Dify specifica che i passaggi di aggiornamento variano tra le release e, per esempio, le note della versione 1.17.1 (settembre 2026) indicano a chi utilizza Weaviate incluso con dati esistenti di non passare direttamente a quella versione, ma di procedere attraverso ogni release minor. Dify modifica anche lo schema .env tra una release e l'altra. Dopo avere effettuato il checkout di un nuovo tag, confronta .env.example con il tuo .env e riporta le tue modifiche, perché una nuova variabile che non hai impostato 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 indica come requisiti minimi 4 GiB di RAM e due core CPU, oltre a Docker Compose 2.24.0 o versioni successive. Questo limite riflette le dimensioni dello stack predefinito: 15 container a esecuzione prolungata più un'attività di inizializzazione eseguita una sola volta, a ottobre 2026. Prevedi spazio su disco sufficiente per i documenti caricati e l'indice vettoriale, oltre a memoria aggiuntiva se il server esegue anche altri servizi.

È sicuro esporre direttamente Dify sulla porta 80?

No. Il web server incluso in Dify è in ascolto su HTTP non cifrato e protegge la pagina di accesso amministrativo e le chiavi API dei modelli. Colloca davanti un reverse proxy con un certificato Let's Encrypt, associa la porta di Dify a loopback e lascia che sia soltanto il proxy HTTPS a essere esposto a Internet. Abbina questa configurazione a un firewall con criterio default-deny, applicato sia a IPv4 sia a IPv6.

Come si aggiorna un'installazione self-hosted di Dify?

Esegui il backup del database, quindi dalla directory docker esegui docker compose down, git fetch --tags, git checkout il nuovo tag della release, docker compose pull e docker compose up -d. Leggi prima le note di rilascio, perché i passaggi di aggiornamento variano tra le release, le migrazioni possono essere irreversibili e Dify aggiunge talvolta nuove variabili .env; se una variabile manca, un container può non avviarsi.

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

Visita /install e crea subito l'account amministratore. Finché l'account non esiste, chiunque possa raggiungere la pagina può appropriarsene. Configuralo non appena i container risultano funzionanti e prima di aprire il firewall al mondo esterno.