Einrichtung

​

Konfigurationsverwaltung

Erstinstallation? Folgen Sie dem Docker Compose-Installationshandbuch, um Twenty zum Laufen zu bringen, und kehren Sie dann hierher zurück, um die Konfiguration fortzusetzen.

Twenty bietet zwei Konfigurationsmodi, um unterschiedlichen Implementierungsbedürfnissen gerecht zu werden:

Zugriff auf das Admin-Panel: Nur Benutzer mit Admin-Berechtigungen (canAccessFullAdminPanel: true) können auf die Konfigurationsoberfläche zugreifen.

​

1. Admin-Panel-Konfiguration (Standard)

IS_CONFIG_VARIABLES_IN_DB_ENABLED=true  # default

Die meiste Konfiguration erfolgt über die Benutzeroberfläche nach der Installation:

1. Greifen Sie auf Ihre Twenty-Instanz zu (normalerweise http://localhost:3000)
2. Gehen Sie zu Einstellungen / Admin-Panel / Konfigurationsvariablen
3. Konfigurieren Sie Integrationen, E-Mail, Speicherung und mehr
4. Änderungen werden sofort wirksam (innerhalb von 15 Sekunden für Mehrcontainer-Bereitstellungen)

Mehr-Container-Bereitstellungen: Bei Verwendung der Datenbankkonfiguration (IS_CONFIG_VARIABLES_IN_DB_ENABLED=true) lesen sowohl Server- als auch Worker-Container aus derselben Datenbank. Änderungen im Admin-Panel wirken sich auf beide Container aus, wodurch die Notwendigkeit entfällt, Umgebungsvariablen zwischen den Containern zu duplizieren (außer Infrastrukturvariablen).

Was Sie über das Admin-Panel konfigurieren können:

• Authentifizierung - Google/Microsoft OAuth, Passwort-Einstellungen
• E-Mail - SMTP-Einstellungen, Vorlagen, Verifizierung
• Speicherung - S3-Konfiguration, lokale Speicherpfade
• Integrationen - Gmail, Google Kalender, Microsoft-Dienste
• Arbeitsablauf & Ratenbegrenzung - Ausführungslimits, API-Drosselung
• Und vieles mehr…

Jede Variable ist mit Beschreibungen in Ihrem Admin-Panel dokumentiert unter Einstellungen → Admin-Panel → Konfigurationsvariablen. Einige Infrastruktureinstellungen wie Datenbankverbindungen (PG_DATABASE_URL), Server-URLs (SERVER_URL) und Secrets (ENCRYPTION_KEY, FALLBACK_ENCRYPTION_KEY) können nur über die .env-Datei konfiguriert werden.

Vollständige technische Referenz →

​

Verschlüsselungsschlüssel

Twenty verwendet zwei ausschließlich über Umgebungsvariablen konfigurierbare Verschlüsselungsschlüssel:

Variable	Zweck	Erforderlich
ENCRYPTION_KEY	Primärer Schlüssel, der für die Verschlüsselung von Secrets im Ruhezustand verwendet wird (OAuth-Tokens, Anwendungsvariablen, private Schlüssel von Signierschlüsseln, TOTP-Secrets, sensible Konfigurationswerte).	Ja, für neue Installationen (Legacy-Installationen können stattdessen auf APP_SECRET zurückgreifen – siehe unten).
FALLBACK_ENCRYPTION_KEY	Nur zur Verifizierung verwendeter Schlüssel. Während einer Rotation auf den vorherigen ENCRYPTION_KEY gesetzt, damit vorhandene Zeilen weiterhin entschlüsselt werden können.	Nur während der Rotation

Aus Gründen der Abwärtskompatibilität greift Twenty, falls ENCRYPTION_KEY nicht gesetzt ist, für die Verschlüsselung im Ruhezustand auf APP_SECRET zurück – entsprechend dem Legacy-Verhalten älterer Deployments. Neue Installationen sollten immer einen eigenen ENCRYPTION_KEY setzen.

Werte mit openssl rand -base64 32 generieren und sie an einem sicheren Ort aufbewahren (einen Secrets-Manager, eine versiegelte Konfiguration usw.). Der Verlust des ENCRYPTION_KEY bedeutet den Verlust des Zugriffs auf jedes in der Datenbank gespeicherte Secret.

Um ENCRYPTION_KEY ohne Downtime zu rotieren, siehe die Anleitung zur Schlüsselrotation.

​

2. Nur-Umgebungs-Konfiguration

IS_CONFIG_VARIABLES_IN_DB_ENABLED=false

Alle Konfiguration wird über .env-Dateien verwaltet:

1. Setzen Sie IS_CONFIG_VARIABLES_IN_DB_ENABLED=false in Ihrer .env-Datei
2. Fügen Sie alle Konfigurationsvariablen zu Ihrer .env-Datei hinzu
3. Starten Sie Container neu, damit Änderungen wirksam werden
4. Im Admin-Panel werden aktuelle Werte angezeigt, können jedoch nicht geändert werden

​

Multi-Workspace-Modus

Standardmäßig läuft Twenty im Single-Workspace-Modus — ideal für die meisten selbstgehosteten Bereitstellungen, bei denen Sie eine CRM-Instanz für Ihre Organisation benötigen.

​

Single-Workspace-Modus (Standard)

IS_MULTIWORKSPACE_ENABLED=false  # default

• Ein Workspace pro Twenty-Instanz
• Der erste Benutzer wird automatisch zum Admin mit vollen Berechtigungen (canImpersonate und canAccessFullAdminPanel).
• Neue Registrierungen werden deaktiviert, nachdem der erste Workspace erstellt wurde.
• Einfache URL-Struktur: https://your-domain.com

​

Multi-Workspace-Modus aktivieren

IS_MULTIWORKSPACE_ENABLED=true
DEFAULT_SUBDOMAIN=app  # default value

Aktivieren Sie den Multi-Workspace-Modus für SaaS-ähnliche Bereitstellungen, bei denen mehrere unabhängige Teams eigene Workspaces auf derselben Twenty-Instanz benötigen.

Wesentliche Unterschiede zum Single-Workspace-Modus:

• Auf derselben Instanz können mehrere Workspaces erstellt werden.
• Jeder Workspace erhält seine eigene Subdomain (z. B. sales.your-domain.com, marketing.your-domain.com).
• Benutzer registrieren sich und melden sich unter {DEFAULT_SUBDOMAIN}.your-domain.com an (z. B. app.your-domain.com).
• Keine automatischen Admin-Berechtigungen — der erste Benutzer in jedem Workspace ist ein normaler Benutzer.
• Workspacespezifische Einstellungen wie Subdomain und benutzerdefinierte Domain werden in den Workspace-Einstellungen verfügbar.

Nur-Umgebungs-Einstellung: IS_MULTIWORKSPACE_ENABLED kann nur über die .env-Datei konfiguriert werden und erfordert einen Neustart. Dies kann nicht über das Admin-Panel geändert werden.

​

DNS-Konfiguration für Multi-Workspace

Wenn Sie den Multi-Workspace-Modus verwenden, konfigurieren Sie Ihr DNS mit einem Wildcard-Eintrag, um die dynamische Erstellung von Subdomains zu ermöglichen:

*.your-domain.com -> your-server-ip

Dadurch wird das automatische Subdomain-Routing für neue Workspaces ohne manuelle DNS-Konfiguration ermöglicht.

​

Einschränkung der Workspace-Erstellung

Im Multi-Workspace-Modus möchten Sie möglicherweise einschränken, wer neue Workspaces erstellen darf:

IS_WORKSPACE_CREATION_LIMITED_TO_SERVER_ADMINS=true

Wenn aktiviert, können nur Benutzer mit canAccessFullAdminPanel zusätzliche Workspaces erstellen. Benutzer können bei der Erstregistrierung weiterhin ihren ersten Workspace erstellen.

​

Gmail- & Google Kalender-Integration

​

Erstellen Sie ein Projekt auf Google Cloud

1. Gehen Sie zum Google Cloud-Konsole
2. Erstellen Sie ein neues Projekt oder wählen Sie ein vorhandenes aus
3. Aktivieren Sie diese APIs:

• Gmail API
• Google Kalender API
• People API

​

OAuth konfigurieren

1. Gehen Sie zu Anmeldedaten
2. Erstellen Sie eine OAuth 2.0-Client-ID
3. Fügen Sie diese Weiterleitungs-URIs hinzu:
   • https://{your-domain}/auth/google/redirect (für SSO)
   • https://{your-domain}/auth/google-apis/get-access-token (für Integrationen)

​

In Twenty konfigurieren

1. Gehen Sie zu Einstellungen → Admin-Panel → Konfigurationsvariablen
2. Finden Sie den Abschnitt Google Auth
3. Setzen Sie diese Variablen:
   • MESSAGING_PROVIDER_GMAIL_ENABLED=true
   • CALENDAR_PROVIDER_GOOGLE_ENABLED=true
   • AUTH_GOOGLE_CLIENT_ID={client-id}
   • AUTH_GOOGLE_CLIENT_SECRET={client-secret}
   • AUTH_GOOGLE_CALLBACK_URL=https://{your-domain}/auth/google/redirect
   • AUTH_GOOGLE_APIS_CALLBACK_URL=https://{your-domain}/auth/google-apis/get-access-token

Nur-Umgebungsmodus: Wenn Sie IS_CONFIG_VARIABLES_IN_DB_ENABLED=false setzen, fügen Sie diese Variablen stattdessen Ihrer .env-Datei hinzu.

Erforderliche Scopes (automatisch konfiguriert): Siehe relevanten Quellcode

• https://www.googleapis.com/auth/calendar.events
• https://www.googleapis.com/auth/gmail.readonly
• https://www.googleapis.com/auth/profile.emails.read

​

Wenn Ihre Anwendung im Testmodus ist

Wenn Ihre Anwendung im Testmodus ist, müssen Sie Testbenutzer zu Ihrem Projekt hinzufügen.

Fügen Sie im OAuth-Zustimmungsbildschirm Ihre Testbenutzer dem Abschnitt “Testbenutzer” hinzu.

​

Microsoft 365-Integration

Benutzer müssen eine Microsoft 365-Lizenz besitzen, um die Kalender- und Messaging-API verwenden zu können. Ohne eine solche Lizenz können sie ihr Konto nicht mit Twenty synchronisieren.

​

Erstellen Sie ein Projekt in Microsoft Azure

Sie müssen ein Projekt in Microsoft Azure erstellen und die Anmeldeinformationen erhalten.

​

APIs aktivieren

Aktivieren Sie diese APIs im “Berechtigungen”-Bereich der Microsoft Azure-Konsole:

• Microsoft Graph: Mail.ReadWrite
• Microsoft Graph: Mail.Send
• Microsoft Graph: Kalender.Read
• Microsoft Graph: Benutzer.Read
• Microsoft Graph: openid
• Microsoft Graph: email
• Microsoft Graph: profil
• Microsoft Graph: offline_access

Hinweis: “Mail.ReadWrite” und “Mail.Send” sind nur erforderlich, wenn Sie E-Mails mit unseren Workflow-Aktionen senden möchten. Sie können stattdessen “Mail.Read” verwenden, wenn Sie nur E-Mails empfangen möchten.

​

Autorisierte Redirect-URIs

Sie müssen die folgenden Weiterleitungs-URIs zu Ihrem Projekt hinzufügen:

• https://{your-domain}/auth/microsoft/redirect, falls Sie das Microsoft-SSO verwenden möchten
• https://{your-domain}/auth/microsoft-apis/get-access-token

​

In Twenty konfigurieren

1. Gehen Sie zu Einstellungen → Admin-Panel → Konfigurationsvariablen
2. Finden Sie den Abschnitt Microsoft Auth
3. Setzen Sie diese Variablen:
   • MESSAGING_PROVIDER_MICROSOFT_ENABLED=true
   • CALENDAR_PROVIDER_MICROSOFT_ENABLED=true
   • AUTH_MICROSOFT_ENABLED=true
   • AUTH_MICROSOFT_CLIENT_ID={client-id}
   • AUTH_MICROSOFT_CLIENT_SECRET={client-secret}
   • AUTH_MICROSOFT_CALLBACK_URL=https://{your-domain}/auth/microsoft/redirect
   • AUTH_MICROSOFT_APIS_CALLBACK_URL=https://{your-domain}/auth/microsoft-apis/get-access-token

Nur-Umgebungsmodus: Wenn Sie IS_CONFIG_VARIABLES_IN_DB_ENABLED=false setzen, fügen Sie diese Variablen stattdessen Ihrer .env-Datei hinzu.

​

Scopes konfigurieren

Siehe relevanten Quellcode

• ‘openid’
• ‘e-Mail’
• ‘profil’
• ‘offline_access’
• ‘Mail.ReadWrite’
• ‘Mail.Send’
• ‘Kalender.Read’

​

Wenn Ihre Anwendung im Testmodus ist

Wenn Ihre Anwendung im Testmodus ist, müssen Sie Testbenutzer zu Ihrem Projekt hinzufügen.

Fügen Sie Ihre Testbenutzer dem Abschnitt “Benutzer und Gruppen” hinzu.

​

Hintergrundaufgaben für Kalender & Messaging

Nachdem Sie Gmail-, Google Kalender- oder Microsoft 365-Integrationen konfiguriert haben, müssen Sie die Hintergrundaufgaben starten, die Daten synchronisieren.

Registrieren Sie die folgenden wiederkehrenden Aufgaben in Ihrem Worker-Container:

# from your worker container
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

​

E-Mail-Konfiguration

1. Gehen Sie zu Einstellungen → Admin-Panel → Konfigurationsvariablen
2. Finden Sie den Abschnitt E-Mail
3. Konfigurieren Sie Ihre SMTP-Einstellungen:

Nur-Umgebungsmodus: Wenn Sie IS_CONFIG_VARIABLES_IN_DB_ENABLED=false setzen, fügen Sie diese Variablen stattdessen Ihrer .env-Datei hinzu.

​

S3-Speicher

Standardmäßig speichert Twenty hochgeladene Dateien auf dem lokalen Dateisystem. Für Produktionsbereitstellungen verwenden Sie S3 oder einen S3-kompatiblen Dienst (MinIO, DigitalOcean Spaces usw.). um sicherzustellen, dass Dateien Container-Neustarts überdauern und über mehrere Serverinstanzen skaliert werden können.

Setzen Sie STORAGE_TYPE=S_3 und konfigurieren Sie die Variablen STORAGE_S3_* über das Admin-Panel oder .env. Siehe die Referenz zu config-variables.ts für die vollständige Liste der S3-Variablen.

Wenn Sie S3 mit CORS-abhängigen Funktionen verwenden (z. B. Dateidownloads im Browser), stellen Sie sicher, dass Ihr Bucket in seiner CORS-Konfiguration die Origin Ihres Twenty-Frontends zulässt.

​

Logikfunktionen & Code-Interpreter

Twenty unterstützt Logikfunktionen für Workflows und den Code-Interpreter für KI-Datenanalyse. Beide führen vom Benutzer bereitgestellten Code aus und erfordern aus Sicherheitsgründen eine explizite Konfiguration.

​

Sicherheits-Standardeinstellungen

In Produktion (NODE_ENV=production): Sowohl Logikfunktionen als auch der Code-Interpreter sind standardmäßig deaktiviert. Sie müssen sie, wenn Sie diese Funktionen benötigen, explizit mit LOGIC_FUNCTION_TYPE und CODE_INTERPRETER_TYPE aktivieren.

In der Entwicklung (NODE_ENV=development): Beide sind der Einfachheit halber beim lokalen Betrieb standardmäßig LOCAL.

Sicherheitshinweis: Der lokale Treiber (LOGIC_FUNCTION_TYPE=LOCAL oder CODE_INTERPRETER_TYPE=LOCAL) führt Code ohne Sandbox direkt auf dem Host in einem Node.js-Prozess aus. Er sollte nur für vertrauenswürdigen Code in der Entwicklung verwendet werden. Für Produktionsbereitstellungen, die nicht vertrauenswürdigen Code verarbeiten, verwenden Sie LOGIC_FUNCTION_TYPE=LAMBDA oder CODE_INTERPRETER_TYPE=E2B (mit Sandbox-Isolierung), oder lassen Sie sie deaktiviert.

​

Logikfunktionen - Verfügbare Treiber

Treiber	Umgebungsvariable	Anwendungsfall	Sicherheitsstufe
Deaktiviert	LOGIC_FUNCTION_TYPE=DISABLED	Logikfunktionen vollständig deaktivieren	N/A
Lokal	LOGIC_FUNCTION_TYPE=LOCAL	Entwicklung und vertrauenswürdige Umgebungen	Niedrig (keine Sandbox)
Lambda	LOGIC_FUNCTION_TYPE=LAMBDA	Produktivbetrieb mit nicht vertrauenswürdigem Code	Hoch (Isolation auf Hardwareebene)

​

Logikfunktionen - Empfohlene Konfiguration

Für die Entwicklung:

LOGIC_FUNCTION_TYPE=LOCAL  # default when NODE_ENV=development

Für den Produktivbetrieb (AWS):

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

Zum Deaktivieren von Logikfunktionen:

LOGIC_FUNCTION_TYPE=DISABLED  # default when NODE_ENV=production

​

Code-Interpreter - Verfügbare Treiber

Treiber	Umgebungsvariable	Anwendungsfall	Sicherheitsstufe
Deaktiviert	CODE_INTERPRETER_TYPE=DISABLED	KI-Codeausführung deaktivieren	N/A
Lokal	CODE_INTERPRETER_TYPE=LOCAL	Nur für die Entwicklung	Niedrig (keine Sandbox)
E2B	CODE_INTERPRETER_TYPE=E_2_B	Produktion mit Ausführung in einer Sandbox	Hoch (isolierte Sandbox)

Bei Verwendung von LOGIC_FUNCTION_TYPE=DISABLED oder CODE_INTERPRETER_TYPE=DISABLED führt jeder Ausführungsversuch zu einem Fehler. Dies ist nützlich, wenn Sie Twenty ohne diese Funktionen betreiben möchten.