Panoramica
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 filedocker-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:- Sostituisci x.y.z con il numero di versione desiderato.
- Sostituisci nome-ramo con il nome del ramo che vuoi installare.
Opzione 2: Passaggi manuali
Segui questi passaggi per un setup manuale.Passo 1: Configura il File di Ambiente
-
Crea il File .env
Copia il file di ambiente di esempio in un nuovo file .env nella tua directory di lavoro:
-
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_KEYsignifica perdere l’accesso a tutti i segreti archiviati nel database (token OAuth, variabili dell’applicazione, segreti TOTP, ecc.). -
Aggiorna il
.envSostituisci 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à. -
Imposta la Password di Postgres
Aggiorna il valore
PG_DATABASE_PASSWORDnel file .env con una password forte senza caratteri speciali.
Passo 2: Ottieni il File Docker Compose
Scarica il filedocker-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 conConfigurazione
Esponi Twenty per Accesso Esterno
Per impostazione predefinita, Twenty gira sulocalhost 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
httpohttpsa seconda della tua configurazione.- Usa
httpse non hai configurato SSL. - Usa
httpsse hai configurato SSL.
- Usa
- 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 (
80perhttp,443perhttps).
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.Configurare SERVER_URL
-
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:
-
Senza Proxy Inverso (Accesso Diretto):
Se accedi all’applicazione direttamente senza un proxy inverso:
-
Aggiorna il File
.envApri il tuo file.enve aggiorna ilSERVER_URL:Esempi:- Accesso diretto senza SSL:
- Accesso tramite dominio con SSL:
- Accesso diretto senza SSL:
-
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 (
3000per 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_URLdeve 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
- Arresta l’applicazione:
- Ripristina il database:
- 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