snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/de/developers/self-host/capabilities/docker-compose.mdx

@@ -0,0 +1,262 @@
+---
+title: Docker Compose
+icon: docker
+---
+
+<Warning>
+Docker-Container sind für produktives Hosting oder Selbsthosting vorgesehen. Zum Mitwirken siehe [Lokale Einrichtung](/l/de/developers/contribute/capabilities/local-setup).
+</Warning>
+
+## Überblick
+
+Diese Anleitung enthält Schritt-für-Schritt-Anweisungen, um die Twenty-Anwendung mit Docker Compose zu installieren und zu konfigurieren. Das Ziel ist, den Prozess übersichtlich zu gestalten und häufige Fallstricke zu vermeiden, die Ihre Einrichtung unterbrechen könnten.
+
+**Wichtig:** Ändern Sie nur die in dieser Anleitung explizit erwähnten Einstellungen. Andere Konfigurationen zu ändern, kann zu Problemen führen.
+
+Siehe die Dokumentation [Umgebungsvariablen einrichten](/l/de/developers/self-host/capabilities/setup) zur erweiterten Konfiguration. Alle Umgebungsvariablen müssen in der Datei `docker-compose.yml` auf Server- und/oder Worker-Ebene deklariert werden, je nach Variable.
+
+## Systemanforderungen
+
+* RAM: Stellen Sie sicher, dass Ihre Umgebung mindestens 2 GB RAM hat. Unzureichender Speicher kann dazu führen, dass Prozesse abstürzen.
+* Docker & Docker Compose: Stellen Sie sicher, dass beide installiert und aktuell sind.
+
+## Option 1: Einzeiliges Skript
+
+Installieren Sie die neueste stabile Version von Twenty mit einem einzigen Befehl:
+
+```bash
+bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)
+```
+
+Um eine spezifische Version oder Zweig zu installieren:
+
+```bash
+VERSION=vx.y.z BRANCH=branch-name bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)
+```
+
+* Ersetzen Sie x.y.z mit der gewünschten Versionsnummer.
+* Ersetzen Sie branch-name durch den Namen des Zweigs, den Sie installieren möchten.
+
+## Option 2: Manuelle Schritte
+
+Befolgen Sie diese Schritte für eine manuelle Einrichtung.
+
+### Schritt 1: Einrichten der Umgebungsdatei
+
+1. **Erstellen Sie die .env Datei**
+
+   Kopieren Sie die Beispielumgebungsdatei in eine neue .env-Datei in Ihrem Arbeitsverzeichnis:
+
+   ```bash
+   curl -o .env https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/.env.example
+   ```
+
+2. **Einen Verschlüsselungsschlüssel generieren**
+
+   Führen Sie den folgenden Befehl aus, um eine eindeutige Zufallszeichenfolge zu generieren:
+
+   ```bash
+   openssl rand -base64 32
+   ```
+
+   **Wichtig:** Bewahren Sie diesen Wert geheim auf / teilen Sie ihn nicht. Der Verlust von `ENCRYPTION_KEY` bedeutet den Verlust des Zugriffs auf alle in der Datenbank gespeicherten Secrets (OAuth-Tokens, Anwendungsvariablen, TOTP-Secrets usw.).
+
+3. **Aktualisieren Sie die `.env`**
+
+   Ersetzen Sie den Platzhalterwert in Ihrer .env-Datei durch das generierte Token:
+
+   ```ini
+   ENCRYPTION_KEY=random_string
+   ```
+
+   Weitere Informationen findest du im [Leitfaden zur Schlüsselrotation](/l/de/developers/self-host/capabilities/key-rotation) mit Anweisungen zur Rotation ohne Ausfallzeit.
+
+4. **Setzen Sie das Postgres-Passwort**
+
+   Aktualisieren Sie den Wert `PG_DATABASE_PASSWORD` in der .env-Datei mit einem starken Passwort ohne Sonderzeichen.
+
+   ```ini
+   PG_DATABASE_PASSWORD=my_strong_password
+   ```
+
+### Schritt 2: Beschaffen Sie die Docker Compose-Datei
+
+Laden Sie die `docker-compose.yml`-Datei in Ihr Arbeitsverzeichnis herunter:
+
+```bash
+curl -o docker-compose.yml https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/docker-compose.yml
+```
+
+### Schritt 3: Anwendung starten
+
+Starten Sie die Docker-Container:
+
+```bash
+docker compose up -d
+```
+
+### Schritt 4: Auf die Anwendung zugreifen
+
+Wenn Sie twentyCRM auf Ihrem eigenen Computer hosten, öffnen Sie Ihren Browser und navigieren Sie zu [http://localhost:3000](http://localhost:3000).
+
+Wenn Sie es auf einem Server hosten, prüfen Sie, ob der Server läuft und ob alles in Ordnung ist mit
+
+```bash
+curl http://localhost:3000
+```
+
+## Konfiguration
+
+### Twenty für externen Zugriff freigeben
+
+Standardmäßig läuft Twenty auf `localhost` an Port `3000`. Die UI bestimmt den API-Endpunkt aus dem eigenen Origin des Browsers, sodass sie von jedem Hostnamen geladen wird, der den Container erreicht – setze dennoch `SERVER_URL` auf deine öffentliche URL: Der Server verwendet sie für generierte Links (E-Mails, OAuth-Callbacks) und um HTTPS für sichere Cookies zu erkennen.
+
+#### Erläuterung von `SERVER_URL`
+
+* **Protokoll:** Verwenden Sie `http` oder `https` je nach Konfiguration.
+  * Verwenden Sie `http`, wenn Sie kein SSL eingerichtet haben.
+  * Verwenden Sie `https`, wenn Sie SSL konfiguriert haben.
+* **Domain/IP:** Dies ist der Domainname oder die IP-Adresse, unter der Ihre Anwendung zugänglich ist.
+* **Port:** Geben Sie die Portnummer an, wenn Sie nicht die Standardports verwenden (`80` für `http`, `443` für `https`).
+
+### SSL-Anforderungen
+
+SSL (HTTPS) ist erforderlich, damit bestimmte Browserfunktionen ordnungsgemäß funktionieren. Obwohl diese Funktionen möglicherweise während der lokalen Entwicklung funktionieren (da Browser localhost anders behandeln), ist eine ordnungsgemäße SSL-Einrichtung erforderlich, wenn Twenty auf einer regulären Domain gehostet wird.
+
+Zum Beispiel erfordert die Clipboard-API möglicherweise einen sicheren Kontext - einige Funktionen wie Kopierknöpfe in der gesamten Anwendung funktionieren möglicherweise nicht ohne aktiviertes HTTPS.
+
+Wir empfehlen dringend, Twenty hinter einem Reverse-Proxy mit SSL-Beendigung für optimale Sicherheit und Funktionalität zu konfigurieren.
+
+#### Konfiguration der `SERVER_URL`
+
+1. **Bestimmen Sie Ihre Zugriffs-URL**
+   * **Ohne Reverse-Proxy (Direkter Zugriff):**
+
+     Wenn Sie direkt ohne Reverse-Proxy auf die Anwendung zugreifen:
+
+     ```ini
+     SERVER_URL=http://your-domain-or-ip:3000
+     ```
+
+   * **Mit Reverse-Proxy (Standard-Ports):**
+
+     Wenn Sie einen Reverse-Proxy wie Nginx oder Traefik verwenden und SSL konfiguriert haben:
+
+     ```ini
+     SERVER_URL=https://your-domain-or-ip
+     ```
+
+   * **Mit Reverse-Proxy (Benutzerdefinierte Ports):**
+
+     Wenn Sie nicht standardisierte Ports verwenden:
+
+     ```ini
+     SERVER_URL=https://your-domain-or-ip:custom-port
+     ```
+
+2. **Aktualisieren Sie die `.env` Datei**
+
+   Öffnen Sie Ihre `.env`-Datei und aktualisieren Sie die `SERVER_URL`:
+
+   ```ini
+   SERVER_URL=http(s)://your-domain-or-ip:your-port
+   ```
+
+   **Beispiele:**
+
+   * Direkter Zugriff ohne SSL:
+     ```ini
+     SERVER_URL=http://123.45.67.89:3000
+     ```
+   * Zugriff über Domain mit SSL:
+     ```ini
+     SERVER_URL=https://mytwentyapp.com
+     ```
+
+3. **Starten Sie die Anwendung neu**
+
+   Damit die Änderungen wirksam werden, starten Sie die Docker-Container neu:
+
+   ```bash
+   docker compose down
+   docker compose up -d
+   ```
+
+#### Überlegungen
+
+* **Reverse Proxy-Konfiguration:**
+
+  Stellen Sie sicher, dass Ihr Reverse-Proxy Anfragen an den richtigen internen Port weiterleitet (`3000` standardmäßig). Konfigurieren Sie die SSL-Terminierung und alle erforderlichen Header.
+
+* **Firewall-Einstellungen:**
+
+  Öffnen Sie die notwendigen Ports in Ihrer Firewall, um externen Zugriff zu ermöglichen.
+
+* **Konsistenz:**
+
+  Die `SERVER_URL` muss mit der Art und Weise übereinstimmen, wie Nutzer in ihren Browsern auf Ihre Anwendung zugreifen.
+
+#### Persistenz
+
+* **Daten-Volumes:**
+
+  Die Docker-Compose-Konfiguration verwendet Volumes, um Daten für die Datenbank und den Serverspeicher persistent zu speichern.
+
+* **Zustandslose Umgebungen:**
+
+  Wenn Sie in einer zustandslosen Umgebung bereitstellen (z. B. bei bestimmten Cloud-Diensten), konfigurieren Sie externen Speicher, um Daten persistent zu speichern.
+
+## Sicherung und Wiederherstellung
+
+Regelmäßige Sicherungen schützen Ihre CRM-Daten vor Verlust.
+
+### Datenbanksicherung erstellen
+
+```bash
+docker exec twenty-postgres pg_dump -U postgres twenty > backup_$(date +%Y%m%d).sql
+```
+
+### Tägliche Sicherungen automatisieren
+
+Zu Ihrer Crontab hinzufügen (`crontab -e`):
+
+```bash
+0 2 * * * docker exec twenty-postgres pg_dump -U postgres twenty > /backups/twenty_$(date +\%Y\%m\%d).sql
+```
+
+### Aus Sicherung wiederherstellen
+
+1. Anwendung stoppen:
+
+```bash
+docker compose stop server worker
+```
+
+2. Datenbank wiederherstellen:
+
+```bash
+docker exec -i twenty-postgres psql -U postgres twenty < backup_20240115.sql
+```
+
+3. Dienste neu starten:
+
+```bash
+docker compose up -d
+```
+
+### Best Practices für Sicherungen
+
+* **Wiederherstellungen regelmäßig testen** — überprüfen Sie, dass die Sicherungen tatsächlich funktionieren
+* **Sicherungen extern aufbewahren** — Cloud-Speicher verwenden (S3, GCS usw.)
+* **Sensible Daten verschlüsseln** — Sicherungen mit Verschlüsselung schützen
+* **Mehrere Kopien aufbewahren** — tägliche, wöchentliche und monatliche Sicherungen vorhalten
+
+## Fehlerbehebung
+
+Sollten Sie auf ein Problem stoßen, schauen Sie sich die [Fehlerbehebung](/l/de/developers/self-host/capabilities/troubleshooting) für Lösungen an.
+
+## Managed Hosting
+
+<Tip>
+  Möchten Sie Twenty lieber nicht selbst betreiben und warten? [Finden Sie einen zertifizierten Twenty-Hosting-Partner](https://twenty.com/partners/list?categories=HOSTING\&ref=docs-docker-compose), der Ihre Instanz Ende-zu-Ende bereitstellt, hostet und verwaltet. *(Oder wenden Sie sich an unser Team: [contact@twenty.com](mailto:contact@twenty.com).)*
+</Tip>

packages/twenty-docs/l/de/developers/self-host/capabilities/key-rotation.mdx

@@ -0,0 +1,60 @@
+---
+title: Schlüsselrotation
+icon: rotate
+---
+
+Twenty hat zwei unabhängige Schlüsselfamilien:
+
+* **JWT-Signaturschlüssel** — asymmetrische ES256-Schlüsselpaare (`kid`-markiert), die in `core."signingKey"` gespeichert sind und zum Signieren und Verifizieren von Access-/Refresh-Tokens verwendet werden.
+* **Verschlüsselungsschlüssel im Ruhezustand** — `ENCRYPTION_KEY`, wird verwendet, um OAuth-Tokens, Anwendungsvariablen, die privaten Schlüssel der Signierschlüssel, sensible Konfigurationswerte und TOTP-Geheimnisse innerhalb eines `enc:v2:`-Umschlags zu verschlüsseln.
+
+`APP_SECRET` ist ein veraltetes Secret, das aus Gründen der Abwärtskompatibilität beibehalten wird: Wenn `ENCRYPTION_KEY` nicht gesetzt ist, fungiert es als Fallback für At-Rest-Verschlüsselung / Session-Cookie und verifiziert weiterhin bereits bestehende HS256-Access-Tokens. Es wird als veraltet markiert werden.
+
+## JWT-Signierschlüssel
+
+Jeder Schlüssel enthält einen `publicKey` (unbefristet aufbewahrt, damit er zuvor ausgestellte Tokens verifizieren kann), einen verschlüsselten `privateKey` (nur verwendet, solange der Schlüssel aktuell ist), ein `isCurrent`-Flag (zu jedem Zeitpunkt genau eine Zeile) und ein optionales `revokedAt`.
+
+### Aktuellen Schlüssel rotieren
+
+Setzen Sie `SIGNING_KEY_ROTATION_DAYS`, um die Funktion zu aktivieren: Ein täglicher Cronjob erstellt dann einen neuen aktuellen Schlüssel, sobald der bestehende Schlüssel älter als dieser Schwellenwert ist. Frühere Schlüssel werden *nicht* widerrufen, daher werden Tokens, die darunter signiert wurden, weiterhin verifiziert. Lassen Sie die Variable ungesetzt, um die automatische Rotation zu deaktivieren.
+
+<Note>Die automatische Rotation ist ab Version v2.6 verfügbar.</Note>
+
+### Einen Schlüssel widerrufen (nur bei Leak / Notfall)
+
+**Settings → Admin Panel → Signing keys → Revoke** in einer nicht aktuellen Zeile. Löscht das verschlüsselte private Material, setzt `revokedAt` und weist jedes vorhandene Token zurück, das unter diesem `kid` signiert wurde.
+
+## `ENCRYPTION_KEY` rotieren
+
+<Note>Der unten beschriebene Befehl `secret-encryption:rotate` ist ab v2.6+ enthalten.</Note>
+
+Jeder verschlüsselte Wert wird als `enc:v2:\<keyId>:\<payload>` verpackt, wobei `\<keyId>` ein 8-stelliges Hex-Präfix ist, das aus dem Rohschlüssel abgeleitet wird. Die Rotation erfolgt online und ist fortsetzbar.
+
+1. **Einen neuen Schlüssel generieren**: `openssl rand -base64 32`.
+
+2. **Beide Schlüssel nebeneinander konfigurieren** in `.env` und dann neu starten:
+   ```ini
+   ENCRYPTION_KEY=NEW_VALUE
+   FALLBACK_ENCRYPTION_KEY=OLD_VALUE
+   ```
+   Neue Schreibvorgänge verwenden den neuen Schlüssel, vorhandene Zeilen werden weiterhin über den Fallback entschlüsselt.
+
+3. **Vorhandene Zeilen erneut verschlüsseln**:
+
+   ```bash
+   docker exec -it {server_container} yarn command:prod secret-encryption:rotate
+   ```
+
+   Der Befehl durchläuft sechs Sites (`connected-account-tokens`, `application-variable`, `application-registration-variable`, `signing-key-private-keys`, `sensitive-config-storage`, `totp-secrets`). Ein SQL-Filter überspringt Zeilen, die bereits auf dem neuen `\<keyId>` sind, sodass der Befehl idempotent ist: Unterbrechen und bei Bedarf erneut ausführen. Beendet sich mit einem von Null verschiedenen Exit-Code, wenn irgendeine Zeile fehlschlägt — zum Wiederholen erneut ausführen.
+
+   | Flag                                     | Beschreibung                                                                 |
+   | ---------------------------------------- | ---------------------------------------------------------------------------- |
+   | `-s, --site \<site>`    | Auf eine einzelne Site beschränken.                                          |
+   | `-b, --batch-size \<n>` | Zeilen pro Batch (Standard `200`, Maximum `5000`).                           |
+   | `-d, --dry-run`                          | Entschlüsseln + erneut im Speicher verschlüsseln, das `UPDATE` überspringen. |
+
+4. **Den Fallback entfernen**, sobald `--dry-run` null verbleibende Zeilen anzeigt: `FALLBACK_ENCRYPTION_KEY` entfernen und neu starten.
+
+## Legacy-Unterstützung für `APP_SECRET`
+
+Ältere Instanzen, die niemals `ENCRYPTION_KEY` gesetzt haben, verwenden `APP_SECRET` als At-Rest-Verschlüsselungsschlüssel (und als Session-Cookie-Secret, das daraus abgeleitet wird). Dieser Pfad wird aus Gründen der Abwärtskompatibilität beibehalten, ist aber **veraltet** — setze einen dedizierten `ENCRYPTION_KEY` und folge dem oben beschriebenen Rotationsverfahren, um davon zu migrieren. `APP_SECRET` selbst bleibt in Verwendung, um Legacy-HS256-Access-Tokens zu verifizieren.

packages/twenty-docs/l/de/developers/self-host/capabilities/setup.mdx

@@ -0,0 +1,414 @@
+---
+title: Einrichtung
+icon: gear
+---
+
+# Konfigurationsverwaltung
+
+<Warning>
+**Erstinstallation?** Folgen Sie dem [Docker Compose-Installationshandbuch](/l/de/developers/self-host/capabilities/docker-compose), um Twenty zum Laufen zu bringen, und kehren Sie dann hierher zurück, um die Konfiguration fortzusetzen.
+</Warning>
+
+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)
+
+```bash
+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)
+
+<Warning>
+**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).
+</Warning>
+
+**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...**
+
+![Konfigurationsvariablen des Admin-Panels](/images/user-guide/setup/admin-panel-config-variables.png)
+
+<Warning>
+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 →](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts)
+</Warning>
+
+## 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](/l/de/developers/self-host/capabilities/key-rotation).
+
+## 2. Nur-Umgebungs-Konfiguration
+
+```bash
+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)
+
+```bash
+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
+
+```bash
+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.
+
+<Warning>
+**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.
+</Warning>
+
+### 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:
+
+```bash
+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](https://console.cloud.google.com/)
+2. Erstellen Sie ein neues Projekt oder wählen Sie ein vorhandenes aus
+3. Aktivieren Sie diese APIs:
+
+* [Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com)
+* [Google Kalender API](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com)
+* [People API](https://console.cloud.google.com/apis/library/people.googleapis.com)
+
+### OAuth konfigurieren
+
+1. Gehen Sie zu [Anmeldedaten](https://console.cloud.google.com/apis/credentials)
+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`
+
+<Warning>
+**Nur-Umgebungsmodus:** Wenn Sie `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false` setzen, fügen Sie diese Variablen stattdessen Ihrer `.env`-Datei hinzu.
+</Warning>
+
+**Erforderliche Scopes** (automatisch konfiguriert):
+[Siehe relevanten Quellcode](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/auth/utils/get-google-apis-oauth-scopes.ts#L4-L10)
+
+* `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](https://console.cloud.google.com/apis/credentials/consent) Ihre Testbenutzer dem Abschnitt "Testbenutzer" hinzu.
+
+## Microsoft 365-Integration
+
+<Warning>
+Benutzer müssen eine [Microsoft 365-Lizenz](https://admin.microsoft.com/Adminportal/Home) besitzen, um die Kalender- und Messaging-API verwenden zu können. Ohne eine solche Lizenz können sie ihr Konto nicht mit Twenty synchronisieren.
+</Warning>
+
+### Erstellen Sie ein Projekt in Microsoft Azure
+
+Sie müssen ein Projekt in [Microsoft Azure](https://portal.azure.com/#view/Microsoft_AAD_IAM/AppGalleryBladeV2) 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
+
+<Note>
+"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.
+</Note>
+
+<Note>
+"Calendars.ReadWrite" ist erforderlich, wenn Sie Kalenderereignisse mit unseren Workflow-Aktionen erstellen möchten. Wenn Sie nur Kalenderereignisse synchronisieren möchten, verwenden Sie "Calendars.Read".
+</Note>
+
+### 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`
+
+<Warning>
+**Nur-Umgebungsmodus:** Wenn Sie `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false` setzen, fügen Sie diese Variablen stattdessen Ihrer `.env`-Datei hinzu.
+</Warning>
+
+### Scopes konfigurieren
+
+[Siehe relevanten Quellcode](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/auth/utils/get-microsoft-apis-oauth-scopes.ts#L2-L9)
+
+* '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:
+
+```bash
+# 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:
+
+<Tabs>
+
+  <Tab title="Gmail">
+
+  Sie müssen ein [App-Passwort](https://support.google.com/accounts/answer/185833) bereitstellen.
+  * EMAIL_DRIVER=smtp
+  * EMAIL_SMTP_HOST=smtp.gmail.com
+  * EMAIL_SMTP_PORT=465
+  * EMAIL_SMTP_USER=gmail_email_address
+  * EMAIL_SMTP_PASSWORD='gmail_app_password'
+
+  </Tab>
+
+  <Tab title="Office365">
+
+  Beachten Sie, dass, wenn Sie die Zwei-Faktor-Authentifizierung aktiviert haben, ein [App-Passwort](https://support.microsoft.com/en-us/account-billing/manage-app-passwords-for-two-step-verification-d6dc8c6d-4bf7-4851-ad95-6d07799387e9) bereitgestellt werden muss.
+  * EMAIL_DRIVER=smtp
+  * EMAIL_SMTP_HOST=smtp.office365.com
+  * EMAIL_SMTP_PORT=587
+  * EMAIL_SMTP_USER=office365_email_address
+  * EMAIL_SMTP_PASSWORD='office365_password'
+
+  </Tab>
+
+  <Tab title="smtp4dev">
+
+  **smtp4dev** ist ein Fake-SMTP-Mailserver für Entwicklung und Tests.
+  * Führen Sie das smtp4dev-Image aus: `docker run --rm -it -p 8090:80 -p 2525:25 rnwood/smtp4dev`
+  * Rufen Sie die smtp4dev-Benutzeroberfläche hier auf: [http://localhost:8090](http://localhost:8090)
+  * Setzen Sie die folgenden Variablen:
+    * EMAIL_DRIVER=smtp
+    * EMAIL_SMTP_HOST=localhost
+    * EMAIL_SMTP_PORT=2525
+
+  </Tab>
+
+</Tabs>
+
+<Warning>
+**Nur-Umgebungsmodus:** Wenn Sie `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false` setzen, fügen Sie diese Variablen stattdessen Ihrer `.env`-Datei hinzu.
+</Warning>
+
+## S3-Speicher
+
+<Warning>
+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.
+</Warning>
+
+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](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/twenty-config/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**.
+
+<Warning>
+**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.
+</Warning>
+
+### 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:**
+
+```bash
+LOGIC_FUNCTION_TYPE=LOCAL  # default when NODE_ENV=development
+```
+
+**Für den Produktivbetrieb (AWS):**
+
+```bash
+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:**
+
+```bash
+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) |
+
+<Note>
+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.
+</Note>
+
+## API und Frontend auf getrennten Hosts
+
+Nur relevant, wenn Sie das Frontend nicht vom Backend ausliefern lassen. Same-Origin-
+Bereitstellungen benötigen hier nichts.
+
+Geben Sie alle Browser-Ursprünge an, die mit der API kommunizieren, kommagetrennt. `SERVER_URL`
+und `FRONTEND_URL` sind bereits vertrauenswürdig. Der Server protokolliert eine Warnung, wenn ein Browser
+diese aus nicht deklariertem Ursprung aufruft.
+
+```bash
+AUTH_COOKIE_ALLOWED_ORIGINS=https://app.example.com
+```
+
+<Warning>
+Das Frontend sendet Anmeldeinformationen auf jeder Anfrage, und Browser lehnen eine
+Anmeldebestätigung von nicht angemeldeter Herkunft ab, so dass die App nicht geladen werden kann, bis
+Sie dies gesetzt haben.
+</Warning>
+
+Wenn sich die beiden Hosts auf unterschiedlichen registrierbaren Domains befinden (nicht nur auf unterschiedlichen Subdomains), setzen Sie außerdem `AUTH_COOKIE_SAME_SITE=none`, was HTTPS erfordert.
+
+Wenn Multiworkspace aktiviert ist, listet hier nicht jede Workspace-Subdomain auf.
+Stattdessen Route API Pfade (`/graphql`, `/metadata`, `/rest`, `/auth/`,
+`/client-config`, `/file`) in das Backend jedes Hostnamens des Arbeitsbereichs, also bleibt jeder
+Arbeitsbereich gleich — so läuft 20 Cloud.

packages/twenty-docs/l/de/developers/self-host/capabilities/troubleshooting.mdx

@@ -0,0 +1,254 @@
+---
+title: Fehlerbehebung
+icon: wrench
+---
+
+## Fehlerbehebung
+
+Wenn Sie bei der Einrichtung der Entwicklungsumgebung, dem Upgrade Ihrer Instanz oder dem Self-Hosting auf Probleme stoßen, finden Sie hier einige Lösungen für häufige Probleme.
+
+### Selbsthosting
+
+#### Erste Installation führt zu `password authentication failed for user "postgres"`
+
+🚨 **WICHTIG: Diese Lösung ist NUR für Neuinstallationen** 🚨
+Wenn Sie bereits eine bestehende Twenty-Instanz mit Produktionsdaten haben, **NICHT** diesen Schritten folgen, da diese permanent Ihre Datenbank löschen!
+
+Bei der ersten Installation von Twenty möchten Sie möglicherweise das Standard-Datenbankpasswort ändern.
+Das während der ersten Installation gesetzte Passwort wird dauerhaft im Datenbank-Volumen gespeichert. Wenn Sie später versuchen, dieses Passwort in Ihrer Konfiguration zu ändern, ohne das alte Volumen zu entfernen, erhalten Sie Authentifizierungsfehler, da die Datenbank noch das ursprüngliche Passwort verwendet.
+
+⚠️ WARNUNG: Die folgenden Schritte werden ALLE Datenbankdaten PERMANENT LÖSCHEN! ⚠️
+Fahren Sie nur fort, wenn dies eine Neuinstallation ohne wichtige Daten ist.
+
+Um den `PG_DATABASE_PASSWORD` zu aktualisieren, müssen Sie auf:
+
+```sh
+# Update the PG_DATABASE_PASSWORD in .env
+docker compose down --volumes
+docker compose up -d
+```
+
+#### CR-Zeilenumbrüche gefunden [Windows]
+
+Dies geschieht aufgrund von Windows-Zeilenenden in Kombination mit Ihrer Git-Konfiguration. Versuchen Sie Folgendes auszuführen:
+
+```
+git config --global core.autocrlf false
+```
+
+Löschen Sie dann das Repository und klonen Sie es erneut.
+
+#### Fehlendes Metadaten-Schema
+
+Während der Twenty-Installation müssen Sie Ihre Postgres-Datenbank mit den richtigen Schemata, Erweiterungen und Benutzern bereitstellen.
+Wenn Sie diese Bereitstellung erfolgreich durchführen, sollten Sie `default` und `metadata` Schemata in Ihrer Datenbank haben.
+Wenn Sie dies nicht tun, stellen Sie sicher, dass nicht mehr als eine PostgreSQL-Instanz auf Ihrem Computer läuft.
+
+#### Modul 'twenty-emails' oder seine entsprechenden Typdeklarationen nicht gefunden.
+
+Du musst das »21«-Paket erstellen (`npx nx nx nx führen Sie einundzwanzig:build`) bevor du die Datenbank-Initialisierung ausführst.
+
+#### Fehlendes Twenty-x Paket
+
+Stellen Sie sicher, dass Sie `yarn` im Root-Verzeichnis ausführen und dann `npx nx server:dev twenty-server` ausführen. Wenn das immer noch nicht funktioniert, versuchen Sie, das fehlende Paket manuell zu erstellen.
+
+#### Lint beim Speichern funktioniert nicht
+
+Normalerweise sollte dies sofort mit der installierten Oxc-Erweiterung (`oxc.oxc-vscode`) funktionieren. Wenn dies nicht funktioniert, versuchen Sie dies zu Ihren VS Code Einstellungen zu hinzufügen (dev Containerbereich):
+
+```
+"editor.codeActionsOnSave": {
+
+  "source.fixAll.oxc": "explicit"
+
+}
+```
+
+#### Beim Ausführen von `npx nx start` oder `npx nx nx nx start`, wird ein Fehler außerhalb des Speichers angezeigt
+
+Führen Sie nur die Services aus, die Sie benötigen, anstatt `npx nx start`. Wenn Sie zum Beispiel am Server arbeiten, führen Sie nur `npx nx worker twenty-server` aus.
+
+**Wenn es nicht funktioniert:**
+Wenn Sie versucht haben, nur `npx nx run twenty-server:start` auf WSL zu starten und es mit dem untenstehenden Speicherfehler fehlschlägt:
+
+`FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory`
+
+Eine Workaround ist es, den folgenden Befehl in deinem Terminal auszuführen, oder füge ihn zu deinem `.bashrc`-Profil hinzu, damit er automatisch angewendet wird:
+
+`export NODE_OPTIONS="--max-old-space-size=8192"`
+
+Das Flag --max-old-space-size=8192 setzt ein oberes Limit von 8GB für den Node.js-Heap; der Verbrauch steigt mit dem Bedarf der Anwendung.
+Referenz: https://stackoverflow.com/questions/56982005/where-do-i-set-node-options-max-old-space-size-2048
+
+**Wenn es nicht funktioniert:**
+Investigate, welche Prozesse den Großteil des Arbeitsspeichers deiner Maschine in Anspruch nehmen. Bei Twenty haben wir festgestellt, dass einige VS Code Erweiterungen viel RAM in Anspruch nahmen, so dass wir sie vorübergehend deaktiviert haben.
+
+**Wenn es nicht funktioniert:**
+Ein Neustart des Rechners hilft, Geisterprozesse zu bereinigen.
+
+#### Beim Ausführen von `npx nx start` gibt es seltsame [0] und [1] in den Logs
+
+Das ist zu erwarten, da der Befehl `npx nx start` im Hintergrund weitere Befehle ausführt.
+
+#### Es werden keine E-Mails gesendet
+
+Meistens liegt das daran, dass der `worker` nicht im Hintergrund läuft. Versuchen Sie auszuführen
+
+```
+npx nx worker twenty-server
+```
+
+#### Mein Microsoft 365-Konto kann nicht mit 20 verbunden werden
+
+Meistens liegt das daran, dass Ihr Administrator die Microsoft 365-Lizenz für Ihr Konto nicht aktiviert hat. Überprüfen Sie [https://admin.microsoft.com/](https://admin.microsoft.com/Adminportal/Home).
+
+Wenn Sie einen Fehlercode `AADSTS50020` haben, bedeutet dies wahrscheinlich, dass Sie ein privates Microsoft-Konto verwenden. Dies wird derzeit nicht unterstützt. Weitere Informationen [hier](https://learn.microsoft.com/fr-fr/troubleshoot/entra/entra-id/app-integration/error-code-aadsts50020-user-account-identity-provider-does-not-exist)
+
+#### Während du `yarn` ausführst, erscheinen Warnungen in der Konsole
+
+Warnungen informieren über das Ziehen zusätzlicher Abhängigkeiten, die nicht explizit in `package.json` angegeben sind. Solange kein schwerwiegender Fehler auftritt, sollte alles wie erwartet funktionieren.
+
+#### Wenn ein Benutzer auf die Login-Seite zugreift, erscheint in den Logs ein Fehler über einen nicht autorisierten Benutzer, der versucht, auf einen Arbeitsbereich zuzugreifen
+
+Das wird erwartet, da der Benutzer nicht autorisiert ist, wenn er ausgeloggt ist, da seine Identität nicht verifiziert wurde.
+
+#### Wie überprüfen Sie, ob Ihr Worker läuft?
+
+* Gehen Sie zu [webhook-test.com](https://webhook-test.com/) und kopieren Sie **Ihre einzigartige Webhook-URL**.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/self-hosting/webhook-test.jpg" alt="Webhook-Test" />
+</div>
+
+* Öffnen Sie Ihre Twenty-App, navigieren Sie zu `/settings`, und aktivieren Sie den **Erweitert**-Schalter unten links auf dem Bildschirm.
+* Erstellen Sie einen neuen Webhook.
+* Fügen Sie **Ihre einzigartige Webhook-URL** in das Feld **Endpoint-Url** in Twenty ein. Stellen Sie die **Filter** auf `Companies` und `Created` ein.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/self-hosting/webhook-settings.jpg" alt="Webhook-Einstellungen" />
+</div>
+
+* Gehen Sie zu `/objects/companies` und erstellen Sie einen neuen Unternehmenseintrag.
+* Kehren Sie zu [webhook-test.com](https://webhook-test.com/) zurück und prüfen Sie, ob ein neuer **POST-Anfrage** empfangen wurde.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/self-hosting/webhook-test-result.jpg" alt="Webhook-Test-Ergebnis" />
+</div>
+
+* Wenn eine **POST-Anfrage** empfangen wird, läuft Ihr Worker erfolgreich. Andernfalls müssen Sie Ihren Worker beheben.
+
+#### Frontend startet nicht und gibt den Fehler TS5042 zurück: Option 'project' kann nicht mit Quelldateien auf der Befehlszeile gemischt werden
+
+Kommentieren Sie das Checker-Plugin in `packages/twenty-ui/vite-config.ts`, wie im folgenden Beispiel angezeigt:
+
+```
+plugins: [
+      react({ jsxImportSource: 'react' }),
+      tsconfigPaths(),
+      svgr(),
+      dts(dtsConfig),
+      // checker(checkersConfig),
+      wyw({
+        include: [
+          '**/OverflowingTextWithTooltip.tsx',
+          '**/Chip.tsx',
+          '**/Tag.tsx',
+          '**/Avatar.tsx',
+          '**/AvatarChip.tsx',
+        ],
+        babelOptions: {
+          presets: ['@babel/preset-typescript', '@babel/preset-react'],
+        },
+      }),
+    ],
+```
+
+#### Admin-Panel nicht zugänglich
+
+Führen Sie `UPDATE core."user" SET "canAccessFullAdminPanel" = TRUE WHERE email = 'you@yourdomain.com';` im Datenbank-Container aus, um Zugriff auf das Admin-Panel zu erhalten.
+
+#### Beim Ausführen eines Workflows schlägt die Workflow-Ausführung fehl mit "Logic function execution is disabled. Set LOGIC_FUNCTION_TYPE to LOCAL or LAMBDA to enable."
+
+In der Produktion sind Logikfunktionen standardmäßig deaktiviert. Setzen Sie die Umgebungsvariable `LOGIC_FUNCTION_TYPE` auf `LOCAL` oder `LAMBDA`, um sie zu aktivieren. Dies kann über Umgebungsvariablen oder über die Datenbankvariablen des Admin-Panels konfiguriert werden. Details finden Sie im [Leitfaden zur Einrichtung von Logikfunktionen](/l/de/developers/self-host/capabilities/setup#logic-functions-available-drivers).
+
+#### Wenn ich eine Nachricht im AI-Chat eingebe, antwortet sie nicht sofort und ich muss die Seite aktualisieren, um die Antwort zu sehen
+
+Das bedeutet, dass Ihrem Reverse Proxy die Konfiguration für Stream-basierte API-Antworten fehlt. Unten ist ein Beispiel Nginx Konfiguration:
+
+```
+location ~* ^/api/.*stream|\/graphql\/stream {
+proxy_pass http://twenty_backend;
+proxy_http_version 1.1;
+proxy_set_header Connection "";
+proxy_set_header Host $host;
+proxy_set_header X-Real-IP $remote_addr;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Forwarded-Proto $scheme;
+proxy_buffering off;
+proxy_request_buffering off;
+proxy_cache off;
+gzip off;
+#chunked_transfer_encoding off;
+add_header X-Accel-Buffering no always;
+}
+```
+
+### 1-Klick-Docker komponieren
+
+#### Kann mich nicht einloggen
+
+Wenn Sie sich nach der Einrichtung nicht anmelden können:
+
+1. Führen Sie die folgenden Befehle aus:
+   ```bash
+   docker exec -it twenty-server-1 yarn
+   docker exec -it twenty-server-1 npx nx database:reset  --configuration=no-seed
+   ```
+2. Starten Sie die Docker-Container neu:
+   ```bash
+   docker compose down
+   docker compose up -d
+   ```
+
+Beachte, dass der Befehl `database:reset` deine Datenbank komplett löschen und von Grund auf neu erstellen wird.
+
+#### Verbindungsprobleme hinter einem Reverse-Proxy
+
+Wenn Sie Twenty hinter einem Reverse-Proxy ausführen und Verbindungsprobleme haben:
+
+1. **SERVER_URL überprüfen:**
+
+   Stellen Sie sicher, dass `SERVER_URL` in Ihrer `.env`-Datei mit Ihrer externen Zugriffs-URL übereinstimmt, einschließlich `https`, falls SSL aktiviert ist.
+
+2. **Reverse-Proxy-Einstellungen prüfen:**
+
+   * Stellen Sie sicher, dass Ihr Reverse-Proxy Anfragen korrekt an den Twenty-Server weiterleitet.
+   * Stellen Sie sicher, dass Header wie `X-Forwarded-For` und `X-Forwarded-Proto` korrekt gesetzt sind.
+
+3. **Dienste neu starten:**
+
+   Starten Sie nach Änderungen sowohl den Reverse-Proxy als auch die Twenty-Container neu.
+
+#### Fehler beim Hochladen eines Bildes – Berechtigung verweigert
+
+Das Ändern des Datenordner-Eigentums auf dem Host von root zu einem anderen Benutzer und Gruppe löst dieses Problem.
+
+#### Fehler „Datei nicht gefunden“ beim Testen der Logic-Funktion im Workflow
+
+Führen Sie den Befehl `yarn command:prod application:rebuild-default-deps` in Ihrem twenty-server-Container aus, um das Problem mit fehlenden Abhängigkeiten zu beheben.
+
+## Hilfe erhalten
+
+Wenn Sie auf Probleme stoßen, die in diesem Leitfaden nicht behandelt werden:
+
+* Protokolle überprüfen:
+
+  Überprüfen Sie die Container-Logs auf Fehlermeldungen:
+
+  ```bash
+  docker compose logs
+  ```
+
+* Unterstützung aus der Community:
+
+  Wenden Sie sich an die [Twenty Community](https://github.com/twentyhq/twenty/issues) oder [Support-Kanäle](https://discord.gg/cx5n4Jzs57) für Unterstützung.

packages/twenty-docs/l/de/developers/self-host/capabilities/upgrade-guide.mdx

@@ -0,0 +1,106 @@
+---
+title: Upgrade-Anleitung
+icon: arrow-up-right-dots
+---
+
+## Allgemeine Richtlinien
+
+**Sichern Sie Ihre Datenbank immer, bevor Sie den Upgrade-Vorgang starten**, indem Sie Folgendes ausführen:
+
+```bash
+docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql
+```
+
+Aus Sicherung wiederherstellen:
+
+```bash
+cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}
+```
+
+Wenn Sie Docker Compose verwenden, befolgen Sie diese Schritte:
+
+1. Twenty stoppen: `docker compose down`
+2. Ändern Sie den Wert von `TAG` in der Datei `.env` neben Ihrer `docker-compose.yml`
+3. Twenty starten: `docker compose up -d`
+
+Der Server führt beim Start alle erforderlichen Upgrade-Migrationen automatisch aus. Kein manueller Befehl erforderlich.
+
+## Upgrade auf v2.34+ — mindestens PostgreSQL 15
+
+Twenty v2.34 erfordert PostgreSQL 15 oder neuer. Die offizielle Docker-Compose-Konfiguration verwendet PostgreSQL 16. Wenn Ihre Instanz eine Verbindung zu einer extern verwalteten Datenbank herstellt, führen Sie deren Upgrade durch, bevor Sie den v2.34-Server starten.
+
+## Versionsübergreifende Upgrades (v1.23+)
+
+Ab **v1.23** unterstützt Twenty versionsübergreifende Upgrades. Sie können direkt von jeder unterstützten Version auf die neueste Version wechseln, ohne jede Zwischenversion durchlaufen zu müssen.
+
+Zum Beispiel wird ein Upgrade direkt von v1.23 auf v2.0 vollständig unterstützt.
+
+## Upgrade auf v2.5+ – Verschlüsselungsumschlag für ruhende Daten
+
+Ab **v2.5** speichert Twenty Secrets im Ruhezustand (OAuth-Tokens, Anwendungsvariablen, private Signaturschlüssel, sensible Konfigurationswerte, TOTP-Secrets) in einem versionierten Umschlag `enc:v2:`, der mit `ENCRYPTION_KEY` (oder `APP_SECRET`, falls `ENCRYPTION_KEY` nicht gesetzt ist) verschlüsselt wird.
+
+Beim ersten Start mit v2.5 werden langsame Upgrade-Befehle ausgeführt, die den neuen Umschlag mit bestehenden Zeilen befüllen. Sie sind idempotent – ein Unterbrechen und Neustarten des Servers setzt an der Stelle fort, an der er aufgehört hat –, aber sie können bei großen Datenbanken eine Weile dauern. Sie können den Fortschritt mit `upgrade:status` überwachen.
+
+Sie sollten **vor** dem Upgrade auf v2.5 einen dedizierten `ENCRYPTION_KEY` setzen, damit beim Nachbefüllen die Zeilen von Anfang an unter diesem Schlüssel geschrieben werden. Ein Schlüsselwechsel nach der Nachbefüllung erfordert eine [Rotation](/l/de/developers/self-host/capabilities/key-rotation).
+
+## Rotation von Secrets und Signaturschlüsseln
+
+Für alltägliche operative Aufgaben wie das Rotieren von `ENCRYPTION_KEY`, das Rotieren des JWT-Signaturschlüssels oder das Widerrufen eines kompromittierten Signaturschlüssels siehe den dedizierten [Leitfaden zur Schlüsselrotation](/l/de/developers/self-host/capabilities/key-rotation).
+
+## Upgrade-Status prüfen
+
+Mit dem Befehl `upgrade:status` können Sie den aktuellen Status Ihrer Instanz und der Workspace-Migrationen prüfen. Er ist nützlich zum Debuggen von Upgrade-Problemen oder beim Erstellen einer Support-Anfrage.
+
+Führen Sie ihn im Server-Container aus:
+
+```bash
+docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status
+```
+
+Beispielausgabe:
+
+```sh
+APP_VERSION: v1.23.0
+
+Instance
+    Inferred version: 1.23.0
+    Latest command:   1.23.0_DropWorkspaceVersionColumnFastInstanceCommand_1785000000000
+    Status:           Up to date
+    Executed by:      v1.23.0
+    At:               2026-04-16T11:43:58.823Z
+
+Workspace
+  Apple (20202020-1c25-4d02-bf25-6aeccf7ea419)
+      Inferred version: 1.23.0
+      Latest command:   1.23.0_UpdateGlobalObjectContextCommandMenuItemsCommand_1780000005000
+      Status:           Up to date
+      Executed by:      v1.23.0
+      At:               2026-04-16T11:44:09.361Z
+
+Summary
+    Instance: Up to date
+    Workspaces: 1 up to date, 0 behind, 0 failed (1 total)
+```
+
+### Optionen
+
+| Flag                      | Beschreibung                                                                                              |
+| ------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `-w, --workspace-id <id>` | Auf einen bestimmten Workspace filtern. Kann mehrfach übergeben werden.                                   |
+| `-f, --failed-only`       | Workspaces auf dem neuesten Stand ausblenden, nur zurückliegende und fehlgeschlagene Workspaces anzeigen. |
+
+## Fehlerbehebung
+
+Wenn das Upgrade in einigen Workspaces fehlschlägt, wird der Server nicht über den fehlschlagenden Schritt hinaus fortfahren. Ein Neustart des Servers (`docker compose up -d`) führt das Upgrade ab der zuletzt erreichten Stelle erneut aus.
+
+Um Probleme schnell zu identifizieren, führen Sie Folgendes aus:
+
+```bash
+docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only
+```
+
+Dies zeigt nur Workspaces, die zurückliegen oder fehlgeschlagen sind, zusammen mit der Fehlermeldung für jeden Fehlschlag.
+
+## Vor v1.23
+
+Wenn Ihre Instanz älter als v1.23 ist, müssen Sie schrittweise über jede größere getaggte Version ein Upgrade durchführen (von v1.6 auf v1.7, dann von v1.7 auf v1.8 usw.), bis Sie v1.23 erreichen. Danach können Sie direkt auf die neueste Version wechseln.