Gestione della Configurazione
Twenty offre due modalità di configurazione per soddisfare diverse esigenze di distribuzione:
Accesso al pannello di amministrazione: Solo gli utenti con privilegi di amministrazione (canAccessFullAdminPanel: true) possono accedere all’interfaccia di configurazione.
1. Configurazione del Pannello di Amministrazione (Predefinito)
IS_CONFIG_VARIABLES_IN_DB_ENABLED=true # predefinito
- Accedi alla tua istanza Twenty (solitamente
http://localhost:3000)
- Vai a Impostazioni / Pannello di Amministrazione / Variabili di Configurazione
- Configura integrazioni, email, storage e altro
- Le modifiche hanno effetto immediato (entro 15 secondi per distribuzioni multi-container)
Distribuzioni Multi-Container: Quando si utilizza la configurazione del database (IS_CONFIG_VARIABLES_IN_DB_ENABLED=true), sia i container server che worker leggono dallo stesso database. Le modifiche al pannello di amministrazione influiscono su entrambi automaticamente, eliminando la necessità di duplicare le variabili di ambiente tra i container (eccetto per le variabili infrastrutturali).
- Autenticazione - Google/Microsoft OAuth, impostazioni della password
- Email - Impostazioni SMTP, modelli, verifica
- Storage - Configurazione S3, percorsi storage locale
- Integrazioni - Gmail, Google Calendar, servizi Microsoft
- Workflow e limitazione della frequenza - Limiti di esecuzione, throttling delle API
- E molto altro ancora…
Ogni variabile è documentata con descrizioni nel tuo pannello di amministrazione in Impostazioni → Pannello di Amministrazione → Variabili di Configurazione.
Alcune impostazioni infrastrutturali come connessioni al database (PG_DATABASE_URL), URL del server (SERVER_URL) e segreti dell’app (APP_SECRET) possono essere configurati solo tramite file .env.Riferimento tecnico completo → 2. Configurazione Solo-Ambiente
IS_CONFIG_VARIABLES_IN_DB_ENABLED=false
.env:
- Imposta
IS_CONFIG_VARIABLES_IN_DB_ENABLED=false nel tuo file .env
- Aggiungi tutte le variabili di configurazione nel tuo file
.env
- Riavvia i container per applicare le modifiche
- Il pannello di amministrazione mostrerà i valori attuali ma non potrà modificarli
Modalità multi-workspace
Per impostazione predefinita, Twenty viene eseguito in modalità a workspace singolo — ideale per la maggior parte delle distribuzioni self-hosted in cui è necessaria un’istanza di CRM per la tua organizzazione.
Modalità a workspace singolo (predefinita)
IS_MULTIWORKSPACE_ENABLED=false # default
- Un workspace per istanza di Twenty
- Il primo utente diventa automaticamente amministratore con privilegi completi (
canImpersonate e canAccessFullAdminPanel)
- Le nuove registrazioni sono disabilitate dopo la creazione del primo workspace
- Struttura URL semplice:
https://your-domain.com
Abilitare la modalità multi-workspace
IS_MULTIWORKSPACE_ENABLED=true
DEFAULT_SUBDOMAIN=app # default value
- È possibile creare più workspace sulla stessa istanza
- Ogni workspace ottiene il proprio sottodominio (ad es.,
sales.your-domain.com, marketing.your-domain.com)
- Gli utenti si registrano e accedono su
{DEFAULT_SUBDOMAIN}.your-domain.com (ad es., app.your-domain.com)
- Nessun privilegio amministrativo automatico — il primo utente in ogni workspace è un utente normale
- Le impostazioni specifiche del workspace, come sottodominio e dominio personalizzato, diventano disponibili nelle impostazioni del workspace
Impostazione solo per l’ambiente: IS_MULTIWORKSPACE_ENABLED può essere configurata solo tramite il file .env e richiede un riavvio. Non può essere modificata tramite il pannello di amministrazione.
Configurazione DNS per la modalità multi-workspace
Quando si utilizza la modalità multi-workspace, configura il DNS con un record wildcard per consentire la creazione dinamica dei sottodomini:
*.your-domain.com -> your-server-ip
Limitare la creazione di workspace
In modalità multi-workspace, potresti voler limitare chi può creare nuovi workspace:
IS_WORKSPACE_CREATION_LIMITED_TO_SERVER_ADMINS=true
canAccessFullAdminPanel possono creare workspace aggiuntivi. Gli utenti possono comunque creare il loro primo workspace durante la registrazione iniziale.
Integrazione Gmail & Google Calendar
Crea Progetto nel Google Cloud
- Vai a Google Cloud Console
- Crea un nuovo progetto o seleziona uno esistente
- Abilita queste API:
Configura OAuth
- Vai a Credenziali
- Crea ID client OAuth 2.0
- Aggiungi questi URI di reindirizzamento:
https://{your-domain}/auth/google/redirect (per SSO)https://{your-domain}/auth/google-apis/get-access-token (per integrazioni)
Configura in Twenty
- Vai a Impostazioni → Pannello di Amministrazione → Variabili di Configurazione
- Trova la sezione Google Auth
- Imposta queste variabili:
MESSAGING_PROVIDER_GMAIL_ENABLED=trueCALENDAR_PROVIDER_GOOGLE_ENABLED=trueAUTH_GOOGLE_CLIENT_ID={client-id}AUTH_GOOGLE_CLIENT_SECRET={client-secret}AUTH_GOOGLE_CALLBACK_URL=https://{your-domain}/auth/google/redirectAUTH_GOOGLE_APIS_CALLBACK_URL=https://{your-domain}/auth/google-apis/get-access-token
Modalità solo ambiente: Se imposti IS_CONFIG_VARIABLES_IN_DB_ENABLED=false, aggiungi queste variabili al tuo file .env invece.
https://www.googleapis.com/auth/calendar.eventshttps://www.googleapis.com/auth/gmail.readonlyhttps://www.googleapis.com/auth/profile.emails.read
Se la tua app è in modalità di test
Se la tua app è in modalità di test, dovrai aggiungere utenti di prova al tuo progetto.
Sotto Schermo di Consenso OAuth, aggiungi i tuoi utenti di prova nella sezione “Utenti di Prova”.
Integrazione Microsoft 365
Gli utenti devono avere una Licenza Microsoft 365 per poter utilizzare l’API Calendario e Messaggi. Non potranno sincronizzare il loro account su Twenty senza una. Crea un progetto in Microsoft Azure
Avrai bisogno di creare un progetto in Microsoft Azure e ottenere le credenziali.
Abilita API
Nel Microsoft Azure Console abilita le seguenti API in “Permessi”:
- Microsoft Graph: Mail.ReadWrite
- Microsoft Graph: Mail.Send
- Microsoft Graph: Calendars.Read
- Microsoft Graph: User.Read
- Microsoft Graph: openid
- Microsoft Graph: email
- Microsoft Graph: profile
- Microsoft Graph: offline_access
Nota: “Mail.ReadWrite” e “Mail.Send” sono obbligatori solo se vuoi inviare email utilizzando le nostre azioni di flusso di lavoro. Puoi usare “Mail.Read” invece se vuoi solo ricevere email.
URI di Riindirizzamento Autorizzati
Devi aggiungere i seguenti URI di reindirizzamento al tuo progetto:
https://{your-domain}/auth/microsoft/redirect se vuoi usare Microsoft SSOhttps://{your-domain}/auth/microsoft-apis/get-access-token
Configura in Twenty
- Vai a Impostazioni → Pannello di Amministrazione → Variabili di Configurazione
- Trova la sezione Microsoft Auth
- Imposta queste variabili:
MESSAGING_PROVIDER_MICROSOFT_ENABLED=trueCALENDAR_PROVIDER_MICROSOFT_ENABLED=trueAUTH_MICROSOFT_ENABLED=trueAUTH_MICROSOFT_CLIENT_ID={client-id}AUTH_MICROSOFT_CLIENT_SECRET={client-secret}AUTH_MICROSOFT_CALLBACK_URL=https://{your-domain}/auth/microsoft/redirectAUTH_MICROSOFT_APIS_CALLBACK_URL=https://{your-domain}/auth/microsoft-apis/get-access-token
Modalità solo ambiente: Se imposti IS_CONFIG_VARIABLES_IN_DB_ENABLED=false, aggiungi queste variabili al tuo file .env invece.
Configura scope
Vedi il codice sorgente pertinente
- ‘openid’
- ‘email’
- ‘profilo’
- ‘offline_access’
- ‘Mail.ReadWrite’
- ‘Mail.Send’
- ‘Calendars.Read’
Se la tua app è in modalità di test
Se la tua app è in modalità di test, dovrai aggiungere utenti di prova al tuo progetto.
Aggiungi i tuoi utenti di prova nella sezione “Utenti e gruppi”.
Lavori in Background per Calendario & Messaggistica
Dopo aver configurato le integrazioni di Gmail, Google Calendar o Microsoft 365, devi avviare i lavori in background che sincronizzano i dati.
Registrare i seguenti lavori ricorrenti nel tuo container worker:
# dal tuo container worker
yarn command:prod cron:messaging:messages-import
yarn command:prod cron:messaging:message-list-fetch
yarn command:prod cron:calendar:calendar-event-list-fetch
yarn command:prod cron:calendar:calendar-events-import
yarn command:prod cron:messaging:ongoing-stale
yarn command:prod cron:calendar:ongoing-stale
yarn command:prod cron:workflow:automated-cron-trigger
Configurazione Email
- Vai a Impostazioni → Pannello di Amministrazione → Variabili di Configurazione
- Trova la sezione Email
- Configura le impostazioni SMTP:
Modalità solo ambiente: Se imposti IS_CONFIG_VARIABLES_IN_DB_ENABLED=false, aggiungi queste variabili al tuo file .env invece.
Archiviazione S3
Per impostazione predefinita, Twenty archivia i file caricati nel file system locale. Per le distribuzioni in produzione, usa S3 o un servizio compatibile con S3 (MinIO, DigitalOcean Spaces, ecc.). per garantire che i file persistano tra i riavvii dei container e per poter scalare su più istanze server.
STORAGE_TYPE=S_3 e configura le variabili STORAGE_S3_* tramite il pannello di amministrazione o .env. Consulta il riferimento a config-variables.ts per l’elenco completo delle variabili S3.
Quando si usa S3 con funzionalità che dipendono da CORS (ad esempio i download di file nel browser), assicurati che il tuo bucket consenta l’origine del tuo frontend di Twenty nella sua configurazione CORS.
Funzioni logiche & interprete del codice
Twenty supporta le funzioni logiche per i workflow e l’interprete del codice per l’analisi dei dati con IA. Entrambi eseguono codice fornito dall’utente e richiedono una configurazione esplicita per motivi di sicurezza.
Impostazioni di sicurezza predefinite
In produzione (NODE_ENV=production): Sia le funzioni logiche sia l’interprete del codice hanno come impostazione predefinita Disabilitato. È necessario abilitarli esplicitamente con LOGIC_FUNCTION_TYPE e CODE_INTERPRETER_TYPE se queste funzionalità sono necessarie.
In sviluppo (NODE_ENV=development): Entrambi sono impostati su LOCAL per comodità quando vengono eseguiti in locale.
Avviso di sicurezza: Il driver locale (LOGIC_FUNCTION_TYPE=LOCAL o CODE_INTERPRETER_TYPE=LOCAL) esegue il codice direttamente sull’host in un processo Node.js senza sandboxing. Dovrebbe essere utilizzato solo per codice attendibile in fase di sviluppo. Per le distribuzioni in produzione che gestiscono codice non affidabile, usa LOGIC_FUNCTION_TYPE=LAMBDA o CODE_INTERPRETER_TYPE=E2B (con sandboxing), oppure lasciali disabilitati.
Funzioni logiche - Driver disponibili
| Driver | Variabile di ambiente | Caso d’uso | Livello di sicurezza |
|---|
| Disabilitato | LOGIC_FUNCTION_TYPE=DISABLED | Disabilita completamente le funzioni logiche | N/A |
| Locale | LOGIC_FUNCTION_TYPE=LOCAL | Ambienti di sviluppo e attendibili | Basso (nessuna sandbox) |
| Lambda | LOGIC_FUNCTION_TYPE=LAMBDA | Produzione con codice non attendibile | Alto (isolamento a livello hardware) |
Funzioni logiche - Configurazione consigliata
Per lo sviluppo:
LOGIC_FUNCTION_TYPE=LOCAL # default when NODE_ENV=development
LOGIC_FUNCTION_TYPE=LAMBDA
LOGIC_FUNCTION_LAMBDA_REGION=us-east-1
LOGIC_FUNCTION_LAMBDA_ROLE=arn:aws:iam::123456789:role/your-lambda-role
LOGIC_FUNCTION_LAMBDA_ACCESS_KEY_ID=your-access-key
LOGIC_FUNCTION_LAMBDA_SECRET_ACCESS_KEY=your-secret-key
LOGIC_FUNCTION_TYPE=DISABLED # default when NODE_ENV=production
Interprete del codice - Driver disponibili
| Driver | Variabile di ambiente | Caso d’uso | Livello di sicurezza |
|---|
| Disabilitato | CODE_INTERPRETER_TYPE=DISABLED | Disabilita l’esecuzione del codice IA | N/A |
| Locale | CODE_INTERPRETER_TYPE=LOCAL | Solo per lo sviluppo | Basso (nessuna sandbox) |
| E2B | CODE_INTERPRETER_TYPE=E_2_B | Produzione con esecuzione in sandbox | Alta (sandbox isolata) |
Quando si utilizza LOGIC_FUNCTION_TYPE=DISABLED o CODE_INTERPRETER_TYPE=DISABLED, qualsiasi tentativo di esecuzione restituirà un errore. Ciò è utile se si desidera eseguire Twenty senza queste funzionalità.
