Vai al contenuto principale

​
Panoramica

I container Docker sono destinati all’hosting in produzione o al self-hosting. Per contribuire, consulta Configurazione locale.
Questa guida fornisce istruzioni passo passo per installare e configurare l’applicazione Twenty usando Docker Compose. L’obiettivo è rendere il processo semplice ed evitare gli errori comuni che potrebbero compromettere il tuo setup. Importante: Modifica solo le impostazioni esplicitamente menzionate in questa guida. Modificare altre configurazioni potrebbe portare a problemi. Consulta Configurazione delle variabili di ambiente per configurazioni avanzate. Tutte le variabili di ambiente devono essere dichiarate nel file docker-compose.yml a livello di server e/o di worker, a seconda della variabile.

​
Requisiti di Sistema

  • RAM: Assicurati che il tuo ambiente abbia almeno 2GB di RAM. Memoria insufficiente può causare arresti anomali dei processi.
  • Docker & Docker Compose: Assicurati che entrambi siano installati e aggiornati.

​
Opzione 1: Script a riga singola

Installa l’ultima versione stabile di Twenty con un unico comando:
Per installare una versione specifica:
  • VERSION deve essere un tag di release completo pubblicato su Docker Hub, ad esempio v2.38.1. Gli alias come v2 o latest non sono accettati.
  • Il file docker-compose.yml corrispondente viene recuperato dal tag git twenty/<version>, quindi le release precedenti a questi tag (v2.9.0 e precedenti) non possono essere installate con lo script.
Per recuperare invece i file di configurazione da un ramo, ad esempio per testare modifiche non ancora rilasciate:
  • Sostituisci branch-name con il branch da cui recuperare docker-compose.yml e .env.example. L’immagine continua a usare per impostazione predefinita l’ultima release, a meno che non sia impostato anche VERSION.

​
Opzione 2: Passaggi manuali

Segui questi passaggi per un setup manuale.

​
Passo 1: Configura il File di Ambiente

  1. Crea il File .env Copia il file di ambiente di esempio in un nuovo file .env nella tua directory di lavoro:
  2. Genera una chiave di cifratura Esegui il seguente comando per generare una stringa casuale unica:
    Importante: Tieni questo valore segreto / non condividerlo. La perdita di ENCRYPTION_KEY significa perdere l’accesso a tutti i segreti archiviati nel database (token OAuth, variabili dell’applicazione, segreti TOTP, ecc.).
  3. Aggiorna il .env Sostituisci il valore segnaposto nel tuo file .env con il token generato:
    Consulta la Guida alla rotazione delle chiavi per le istruzioni su come ruotarla senza tempi di inattività.
  4. Imposta la Password di Postgres Aggiorna il valore PG_DATABASE_PASSWORD nel file .env con una password forte senza caratteri speciali. La password viene inserita senza codifica nell’URL di connessione Postgres, pertanto caratteri quali @, /, # o % interrompono la stringa di connessione. Generane uno con:
Le variabili che docker-compose.yml inoltra senza un valore predefinito :-, come SERVER_URL e le variabili STORAGE_S3_*, raggiungono il server come stringa vuota quando sono vuote o mancanti in .env, e il server considera una stringa vuota come un valore configurato anziché non impostato. Mantieni impostato SERVER_URL e, quando STORAGE_TYPE=S_3, imposta ogni variabile STORAGE_S3_* richiesta: un valore STORAGE_S3_NAME vuoto interrompe ogni caricamento. Le variabili con un valore predefinito in docker-compose.yml, come le parti PG_DATABASE_* e REDIS_URL, utilizzano tale valore predefinito quando sono vuote o mancanti.

​
Passo 2: Ottieni il File Docker Compose

Scarica il file docker-compose.yml nella tua directory di lavoro:

​
Passo 3: Avvia l’Applicazione

Avvia i container Docker:

​
Passo 4: Accedi all’Applicazione

Se ospiti twentyCRM sul tuo computer, apri il browser e naviga a http://localhost:3000. Se lo ospiti su un server, controlla che il server sia in esecuzione e che tutto sia ok con

​
Configurazione

​
Esponi Twenty per Accesso Esterno

Per impostazione predefinita, Twenty gira su localhost alla porta 3000. L’interfaccia utente risolve l’API dall’origine del browser, quindi viene caricata da qualsiasi hostname che raggiunga il container — ma imposta comunque SERVER_URL sul tuo URL pubblico: il server lo usa per i link generati (email, callback OAuth) e per rilevare l’HTTPS per i cookie sicuri.

​
Comprendere SERVER_URL

  • Protocollo: Usa http o https a seconda della tua configurazione.
    • Usa http se non hai configurato SSL.
    • Usa https se hai configurato SSL.
  • Dominio/IP: Questo è il nome del dominio o indirizzo IP dove la tua applicazione è accessibile.
  • Porta: Includi il numero di porta se non stai usando le porte predefinite (80 per http, 443 per https).

​
Requisiti SSL

SSL (HTTPS) è necessario affinché alcune caratteristiche del browser funzionino correttamente. Mentre queste caratteristiche potrebbero funzionare durante lo sviluppo locale (poiché i browser trattano localhost in modo diverso), è necessario un setup SSL adeguato quando si ospita Twenty su un dominio regolare. Ad esempio, l’API degli appunti potrebbe richiedere un contesto sicuro - alcune funzionalità come i pulsanti di copia in tutta l’applicazione potrebbero non funzionare senza HTTPS abilitato. Raccomandiamo fortemente di configurare Twenty dietro un proxy inverso con terminazione SSL per una sicurezza e funzionalità ottimali.
Prima di esporre Twenty a Internet, leggi Protezione dell’istanza. La maggior parte dei team può mantenere privata l’app e aprire solo alcuni percorsi.

​
Configurare SERVER_URL

  1. Determina il tuo URL di Accesso
    • Senza Proxy Inverso (Accesso Diretto): Se accedi all’applicazione direttamente senza un proxy inverso:
    • Con Proxy Inverso (Porte Standard): Se usi un proxy inverso come Nginx o Traefik e hai configurato SSL:
    • Con Proxy Inverso (Porte Personalizzate): Se usi porte non standard:
  2. Aggiorna il File .env Apri il tuo file .env e aggiorna il SERVER_URL:
    Esempi:
    • Accesso diretto senza SSL:
    • Accesso tramite dominio con SSL:
  3. Riavvia l’Applicazione Per rendere effettive le modifiche, riavvia i container Docker:

​
Considerazioni

  • Configurazione del Reverse Proxy: Assicurati che il tuo reverse proxy inoltri le richieste alla porta interna corretta (3000 per impostazione predefinita). Configura la terminazione SSL e tutte le intestazioni necessarie.
  • Impostazioni Firewall: Apri le porte necessarie nel tuo firewall per consentire l’accesso esterno.
  • Coerenza: Il SERVER_URL deve corrispondere a come gli utenti accedono alla tua applicazione nei loro browser.

​
Persistenza

  • Volumi di Dati: La configurazione di Docker Compose utilizza volumi per mantenere i dati per il database e l’archiviazione del server.
  • Ambienti Senza Stato: Se si distribuisce in un ambiente senza stato (ad esempio, alcuni servizi di cloud), configura l’archiviazione esterna per mantenere i dati.

​
Backup e ripristino

I backup regolari proteggono i dati del tuo CRM dalla perdita.

​
Crea un backup del database

​
Automatizza i backup giornalieri

Aggiungi al tuo crontab (crontab -e):

​
Ripristina dal backup

  1. Arresta l’applicazione:
  1. Ripristina il database:
  1. Riavvia i servizi:

​
Pratiche migliori per i backup

  • Esegui regolarmente test di ripristino — verifica che i backup funzionino davvero
  • Conserva i backup off-site — usa l’archiviazione cloud (S3, GCS, ecc.)
  • Crittografa i dati sensibili — proteggi i backup con la crittografia
  • Mantieni più copie — conserva backup giornalieri, settimanali e mensili

​
Risoluzione dei problemi

Se riscontri problemi, controlla Risoluzione dei problemi per le soluzioni.

​
Hosting gestito

Preferisci non gestire e mantenere Twenty in autonomia? Trova un partner Twenty certificato per distribuire, ospitare e gestire la tua istanza end-to-end. (Oppure contatta il nostro team: contact@twenty.com.)