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

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

@@ -0,0 +1,255 @@
+---
+title: Docker Compose
+icon: "docker"
+---
+
+
+<Warning>
+Docker containers are for production hosting or self-hosting. For contributing, please check the [Local Setup](/developers/contribute/capabilities/local-setup).
+</Warning>
+
+## Overview
+
+This guide provides step-by-step instructions to install and configure the Twenty application using Docker Compose. The aim is to make the process straightforward and prevent common pitfalls that could break your setup.
+
+**Important:** Only modify settings explicitly mentioned in this guide. Altering other configurations may lead to issues.
+
+See [Setup Environment Variables](/developers/self-host/capabilities/setup) for advanced configuration. All environment variables must be declared in the `docker-compose.yml` file at the server and/or worker level, depending on the variable.
+
+## System Requirements
+
+- RAM: Ensure your environment has at least 2GB of RAM. Insufficient memory can cause processes to crash.
+- Docker & Docker Compose: Make sure both are installed and up-to-date.
+
+## Option 1: One-line script
+
+Install the latest stable version of Twenty with a single command:
+```bash
+bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)
+```
+
+To install a specific version:
+```bash
+VERSION=v2.38.1 bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)
+```
+- `VERSION` must be a full release tag published on [Docker Hub](https://hub.docker.com/r/twentycrm/twenty/tags), such as `v2.38.1`. Aliases such as `v2` or `latest` are not accepted.
+- The matching `docker-compose.yml` is fetched from the `twenty/<version>` git tag, so releases that predate these tags (v2.9.0 and older) can't be installed with the script.
+
+To fetch the configuration files from a branch instead, for example to test unreleased changes:
+```bash
+BRANCH=branch-name bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)
+```
+- Replace branch-name with the branch to fetch `docker-compose.yml` and `.env.example` from. The image still defaults to the latest release unless `VERSION` is also set.
+
+## Option 2: Manual steps
+Follow these steps for a manual setup.
+
+### Step 1: Set Up the Environment File
+
+1. **Create the .env File**
+
+    Copy the example environment file to a new .env file in your working directory:
+    ```bash
+    curl -o .env https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/.env.example
+    ```
+
+2. **Generate an Encryption Key**
+
+    Run the following command to generate a unique random string:
+
+    ```bash
+    openssl rand -base64 32
+    ```
+    **Important:** Keep this value secret / do not share it. Losing `ENCRYPTION_KEY` means losing access to every secret stored in the database (OAuth tokens, application variables, TOTP secrets, etc.).
+
+3. **Update the `.env`**
+
+    Replace the placeholder value in your .env file with the generated token:
+
+    ```ini
+    ENCRYPTION_KEY=random_string
+    ```
+
+    See the [Key rotation guide](/developers/self-host/capabilities/key-rotation) for instructions on rotating it without downtime.
+
+4. **Set the Postgres Password**
+
+    Update the `PG_DATABASE_PASSWORD` value in the .env file with a strong password without special characters.
+
+    ```ini
+    PG_DATABASE_PASSWORD=my_strong_password
+    ```
+
+### Step 2: Obtain the Docker Compose File
+
+Download the `docker-compose.yml` file to your working directory:
+
+```bash
+curl -o docker-compose.yml https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/docker-compose.yml
+```
+
+### Step 3: Launch the Application
+
+Start the Docker containers:
+```bash
+docker compose up -d
+```
+
+### Step 4: Access the Application
+
+If you host twentyCRM on your own computer, open your browser and navigate to [http://localhost:3000](http://localhost:3000).
+
+If you host it on a server, check that the server is running and that everything is ok with
+```bash
+curl http://localhost:3000
+```
+
+## Configuration
+
+### Expose Twenty to External Access
+
+By default, Twenty runs on `localhost` at port `3000`. The UI resolves the API from the browser's own origin, so it loads from any hostname that reaches the container — but still set `SERVER_URL` to your public URL: the server uses it for generated links (emails, OAuth callbacks) and to detect HTTPS for secure cookies.
+
+#### Understanding `SERVER_URL`
+
+- **Protocol:** Use `http` or `https` depending on your setup.
+    - Use `http` if you haven't set up SSL.
+    - Use `https` if you have SSL configured.
+- **Domain/IP:** This is the domain name or IP address where your application is accessible.
+- **Port:** Include the port number if you're not using the default ports (`80` for `http`, `443` for `https`).
+
+### SSL Requirements
+
+SSL (HTTPS) is required for certain browser features to work properly. While these features might work during local development (as browsers treat localhost differently), a proper SSL setup is needed when hosting Twenty on a regular domain.
+
+For example, the clipboard API might require a secure context - some features like copy buttons throughout the application might not work without HTTPS enabled.
+
+We strongly recommend setting up Twenty behind a reverse proxy with SSL termination for optimal security and functionality.
+
+#### Configuring `SERVER_URL`
+
+1. **Determine Your Access URL**
+    - **Without Reverse Proxy (Direct Access):**
+
+        If you're accessing the application directly without a reverse proxy:
+        ```ini
+        SERVER_URL=http://your-domain-or-ip:3000
+        ```
+
+    - **With Reverse Proxy (Standard Ports):**
+
+        If you're using a reverse proxy like Nginx or Traefik and have SSL configured:
+        ```ini
+        SERVER_URL=https://your-domain-or-ip
+        ```
+
+    - **With Reverse Proxy (Custom Ports):**
+
+        If you're using non-standard ports:
+        ```ini
+        SERVER_URL=https://your-domain-or-ip:custom-port
+        ````
+
+2. **Update the `.env` File**
+
+    Open your `.env` file and update the `SERVER_URL`:
+
+    ```ini
+    SERVER_URL=http(s)://your-domain-or-ip:your-port
+    ```
+
+    **Examples:**
+    - Direct access without SSL:
+        ```ini
+        SERVER_URL=http://123.45.67.89:3000
+        ```
+    - Access via domain with SSL:
+        ```ini
+        SERVER_URL=https://mytwentyapp.com
+        ```
+
+3. **Restart the Application**
+
+    For changes to take effect, restart the Docker containers:
+    ```bash
+    docker compose down
+    docker compose up -d
+    ```
+
+#### Considerations
+
+- **Reverse Proxy Configuration:**
+
+    Ensure your reverse proxy forwards requests to the correct internal port (`3000` by default). Configure SSL termination and any necessary headers.
+
+- **Firewall Settings:**
+
+    Open necessary ports in your firewall to allow external access.
+
+- **Consistency:**
+
+    The `SERVER_URL` must match how users access your application in their browsers.
+
+#### Persistence
+
+- **Data Volumes:**
+
+    The Docker Compose configuration uses volumes to persist data for the database and server storage.
+
+- **Stateless Environments:**
+
+    If deploying to a stateless environment (e.g., certain cloud services), configure external storage to persist data.
+
+
+## Backup and Restore
+
+Regular backups protect your CRM data from loss.
+
+### Create a Database Backup
+
+```bash
+docker exec twenty-postgres pg_dump -U postgres twenty > backup_$(date +%Y%m%d).sql
+```
+
+### Automate Daily Backups
+
+Add to your crontab (`crontab -e`):
+
+```bash
+0 2 * * * docker exec twenty-postgres pg_dump -U postgres twenty > /backups/twenty_$(date +\%Y\%m\%d).sql
+```
+
+### Restore from Backup
+
+1. Stop the application:
+```bash
+docker compose stop server worker
+```
+
+2. Restore the database:
+```bash
+docker exec -i twenty-postgres psql -U postgres twenty < backup_20240115.sql
+```
+
+3. Restart services:
+```bash
+docker compose up -d
+```
+
+### Backup Best Practices
+
+- **Test restores regularly** — verify backups actually work
+- **Store backups off-site** — use cloud storage (S3, GCS, etc.)
+- **Encrypt sensitive data** — protect backups with encryption
+- **Retain multiple copies** — keep daily, weekly, and monthly backups
+
+## Troubleshooting
+
+If you encounter any problem, check [Troubleshooting](/developers/self-host/capabilities/troubleshooting) for solutions.
+
+## Managed Hosting
+
+<Tip>
+  Prefer not to run and maintain Twenty yourself? [Find a certified Twenty hosting partner](https://twenty.com/partners/list?categories=HOSTING&ref=docs-docker-compose) to deploy, host, and manage your instance end-to-end. *(Or reach our team: [contact@twenty.com](mailto:contact@twenty.com).)*
+</Tip>
+

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

@@ -0,0 +1,56 @@
+---
+title: Key rotation
+icon: "rotate"
+---
+
+Twenty has two independent key families:
+
+- **JWT signing keys** — asymmetric ES256 keypairs (`kid`-tagged) stored in `core."signingKey"`, used to sign and verify access / refresh tokens.
+- **At-rest encryption key** — `ENCRYPTION_KEY`, used to encrypt OAuth tokens, application variables, signing-key private keys, sensitive config values and TOTP secrets inside an `enc:v2:` envelope.
+
+`APP_SECRET` is a legacy secret kept for backward compatibility: when `ENCRYPTION_KEY` is unset it acts as the at-rest encryption / session cookie fallback, and it still verifies pre-existing HS256 access tokens. It will be deprecated.
+
+## JWT signing keys
+
+Each key carries a `publicKey` (kept indefinitely so it can verify previously issued tokens), an encrypted `privateKey` (used only while the key is current), an `isCurrent` flag (exactly one row at a time) and an optional `revokedAt`.
+
+### Rotate the current key
+
+Set `SIGNING_KEY_ROTATION_DAYS` to opt in: a daily cron then issues a new current key once the existing one is older than that threshold. Previous keys are *not* revoked, so tokens signed under them keep verifying. Leave the variable unset to disable auto-rotation.
+
+<Note>Auto-rotation ships in v2.6+.</Note>
+
+### Revoke a key (leak / emergency only)
+
+**Settings → Admin Panel → Signing keys → Revoke** on a non-current row. Wipes the encrypted private material, sets `revokedAt`, and rejects every existing token signed under that `kid`.
+
+## Rotate `ENCRYPTION_KEY`
+
+<Note>The `secret-encryption:rotate` command described below ships in v2.6+.</Note>
+
+Every encrypted value is wrapped as `enc:v2:<keyId>:<payload>`, where `<keyId>` is an 8-hex prefix derived from the raw key. Rotation is online and resumable.
+
+1. **Generate a new key**: `openssl rand -base64 32`.
+2. **Configure both keys side-by-side** in `.env`, then restart:
+   ```ini
+   ENCRYPTION_KEY=NEW_VALUE
+   FALLBACK_ENCRYPTION_KEY=OLD_VALUE
+   ```
+   New writes use the new key, existing rows still decrypt via the fallback.
+3. **Re-encrypt existing rows**:
+   ```bash
+   docker exec -it {server_container} yarn command:prod secret-encryption:rotate
+   ```
+   The command walks six sites (`connected-account-tokens`, `application-variable`, `application-registration-variable`, `signing-key-private-keys`, `sensitive-config-storage`, `totp-secrets`). A SQL filter skips rows already on the new `<keyId>`, so the command is idempotent: interrupt and re-run as needed. Exits non-zero if any row fails — re-run to retry.
+
+   | Flag | Description |
+   | --- | --- |
+   | `-s, --site <site>` | Limit to a single site. |
+   | `-b, --batch-size <n>` | Rows per batch (default `200`, max `5000`). |
+   | `-d, --dry-run` | Decrypt + re-encrypt in memory, skip the `UPDATE`. |
+
+4. **Drop the fallback** once `--dry-run` shows zero remaining rows: remove `FALLBACK_ENCRYPTION_KEY` and restart.
+
+## Legacy `APP_SECRET` support
+
+Older instances that never set `ENCRYPTION_KEY` use `APP_SECRET` as the at-rest encryption key (and as the session-cookie secret, derived from it). This path is preserved for backward compatibility but is **deprecated** — set a dedicated `ENCRYPTION_KEY` and follow the rotation procedure above to migrate off it. `APP_SECRET` itself stays in use to verify legacy HS256 access tokens.

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

@@ -0,0 +1,416 @@
+---
+title: Setup
+icon: "gear"
+---
+
+# Configuration Management
+
+<Warning>
+**First time installing?** Follow the [Docker Compose installation guide](/developers/self-host/capabilities/docker-compose) to get Twenty running, then return here for configuration.
+</Warning>
+
+Twenty offers **two configuration modes** to suit different deployment needs:
+
+**Admin panel access:** Only users with admin privileges (`canAccessFullAdminPanel: true`) can access the configuration interface.
+
+## 1. Admin Panel Configuration (Default)
+
+```bash
+IS_CONFIG_VARIABLES_IN_DB_ENABLED=true  # default
+```
+
+**Most configuration happens through the UI** after installation:
+
+1. Access your Twenty instance (usually `http://localhost:3000`)
+2. Go to **Settings / Admin Panel / Configuration Variables**
+3. Configure integrations, email, storage, and more
+4. Changes take effect immediately (within 15 seconds for multi-container deployments)
+
+<Warning>
+**Multi-Container Deployments:** When using database configuration (`IS_CONFIG_VARIABLES_IN_DB_ENABLED=true`), both server and worker containers read from the same database. Admin panel changes affect both automatically, eliminating the need to duplicate environment variables between containers (except for infrastructure variables).
+</Warning>
+
+**What you can configure through the admin panel:**
+- **Authentication** - Google/Microsoft OAuth, password settings
+- **Email** - SMTP settings, templates, verification
+- **Storage** - S3 configuration, local storage paths
+- **Integrations** - Gmail, Google Calendar, Microsoft services
+- **Workflow & Rate Limiting** - Execution limits, API throttling
+- **And much more...**
+
+![Admin Panel Configuration Variables](/images/user-guide/setup/admin-panel-config-variables.png)
+
+<Warning>
+Each variable is documented with descriptions in your admin panel at **Settings → Admin Panel → Configuration Variables**.
+Some infrastructure settings like database connections (`PG_DATABASE_URL`), server URLs (`SERVER_URL`), and secrets (`ENCRYPTION_KEY`, `FALLBACK_ENCRYPTION_KEY`) can only be configured via `.env` file.
+
+[Complete technical reference →](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts)
+</Warning>
+
+## Encryption keys
+
+Twenty uses two env-only encryption keys:
+
+| Variable | Purpose | Required |
+| --- | --- | --- |
+| `ENCRYPTION_KEY` | Primary key used to encrypt secrets at rest (OAuth tokens, application variables, signing-key private keys, TOTP secrets, sensitive config values). | Yes for new installs (legacy installs may instead rely on `APP_SECRET` — see below) |
+| `FALLBACK_ENCRYPTION_KEY` | Verification-only key. Set during a rotation to the *previous* `ENCRYPTION_KEY` so existing rows remain decryptable. | Only during rotation |
+
+For backward compatibility, if `ENCRYPTION_KEY` is unset, Twenty falls back to `APP_SECRET` for at-rest encryption — matching the legacy behaviour for older deployments. New installs should always set a dedicated `ENCRYPTION_KEY`.
+
+Generate values with `openssl rand -base64 32` and store them somewhere safe (a secrets manager, sealed config, etc.). Losing `ENCRYPTION_KEY` means losing access to every secret stored in the database.
+
+To rotate `ENCRYPTION_KEY` without downtime, see the [Key rotation guide](/developers/self-host/capabilities/key-rotation).
+
+## 2. Environment-Only Configuration
+
+```bash
+IS_CONFIG_VARIABLES_IN_DB_ENABLED=false
+```
+
+**All configuration managed through `.env` files:**
+
+1. Set `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false` in your `.env` file
+2. Add all configuration variables to your `.env` file
+3. Restart containers for changes to take effect
+4. Admin panel will show current values but cannot modify them
+
+## Multi-Workspace Mode
+
+By default, Twenty runs in **single-workspace mode** — ideal for most self-hosted deployments where you need one CRM instance for your organization.
+
+### Single-Workspace Mode (Default)
+
+```bash
+IS_MULTIWORKSPACE_ENABLED=false  # default
+```
+
+- One workspace per Twenty instance
+- First user automatically becomes admin with full privileges (`canImpersonate` and `canAccessFullAdminPanel`)
+- New signups are disabled after the first workspace is created
+- Simple URL structure: `https://your-domain.com`
+
+### Enabling Multi-Workspace Mode
+
+```bash
+IS_MULTIWORKSPACE_ENABLED=true
+DEFAULT_SUBDOMAIN=app  # default value
+```
+
+Enable multi-workspace mode for SaaS-like deployments where multiple independent teams need their own workspaces on the same Twenty instance.
+
+**Key differences from single-workspace mode:**
+- Multiple workspaces can be created on the same instance
+- Each workspace gets its own subdomain (e.g., `sales.your-domain.com`, `marketing.your-domain.com`)
+- Users sign up and log in at `{DEFAULT_SUBDOMAIN}.your-domain.com` (e.g., `app.your-domain.com`)
+- No automatic admin privileges — first user in each workspace is a regular user
+- Workspace-specific settings like subdomain and custom domain become available in workspace settings
+
+<Warning>
+**Environment-only setting:** `IS_MULTIWORKSPACE_ENABLED` can only be configured via `.env` file and requires a restart. It cannot be changed through the admin panel.
+</Warning>
+
+### DNS Configuration for Multi-Workspace
+
+When using multi-workspace mode, configure your DNS with a wildcard record to allow dynamic subdomain creation:
+
+```
+*.your-domain.com -> your-server-ip
+```
+
+This enables automatic subdomain routing for new workspaces without manual DNS configuration.
+
+### Restricting Workspace Creation
+
+In multi-workspace mode, you may want to limit who can create new workspaces:
+
+```bash
+IS_WORKSPACE_CREATION_LIMITED_TO_SERVER_ADMINS=true
+```
+
+When enabled, only users with `canAccessFullAdminPanel` can create additional workspaces. Users can still create their first workspace during initial signup.
+
+## Gmail & Google Calendar Integration
+
+### Create Google Cloud Project
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select existing one
+3. Enable these APIs:
+- [Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com)
+- [Google Calendar API](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com)
+- [People API](https://console.cloud.google.com/apis/library/people.googleapis.com)
+
+### Configure OAuth
+
+1. Go to [Credentials](https://console.cloud.google.com/apis/credentials)
+2. Create OAuth 2.0 Client ID
+3. Add these redirect URIs:
+   - `https://{your-domain}/auth/google/redirect` (for SSO)
+   - `https://{your-domain}/auth/google-apis/get-access-token` (for integrations)
+
+### Configure in Twenty
+
+1. Go to **Settings → Admin Panel → Configuration Variables**
+2. Find the **Google Auth** section
+3. Set these variables:
+   - `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>
+**Environment-only mode:** If you set `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`, add these variables to your `.env` file instead.
+</Warning>
+
+**Required scopes** (automatically configured):
+[See relevant source code](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`
+
+### If your app is in test mode
+
+If your app is in test mode, you will need to add test users to your project.
+
+Under [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent), add your test users to the "Test users" section.
+
+## Microsoft 365 Integration
+
+<Warning>
+Users must have a [Microsoft 365 Licence](https://admin.microsoft.com/Adminportal/Home) to be able to use the Calendar and Messaging API. They will not be able to sync their account on Twenty without one.
+</Warning>
+
+### Create a project in Microsoft Azure
+
+You will need to create a project in [Microsoft Azure](https://portal.azure.com/#view/Microsoft_AAD_IAM/AppGalleryBladeV2) and get the credentials.
+
+### Enable APIs
+
+On Microsoft Azure Console enable the following APIs in "Permissions":
+
+- 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
+
+<Note>
+"Mail.ReadWrite" and "Mail.Send" are only mandatory if you want to send emails using our workflow actions. You can use "Mail.Read" instead if you only want to receive emails.
+</Note>
+
+<Note>
+"Calendars.ReadWrite" is mandatory if you want to create calendar events using our workflow actions. If you want to only sync calendar events, use "Calendars.Read".
+</Note>
+
+### Authorized redirect URIs
+
+You need to add the following redirect URIs to your project:
+- `https://{your-domain}/auth/microsoft/redirect` if you want to use Microsoft SSO
+- `https://{your-domain}/auth/microsoft-apis/get-access-token`
+
+### Configure in Twenty
+
+1. Go to **Settings → Admin Panel → Configuration Variables**
+2. Find the **Microsoft Auth** section
+3. Set these variables:
+   - `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>
+**Environment-only mode:** If you set `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`, add these variables to your `.env` file instead.
+</Warning>
+
+### Configure scopes
+[See relevant source code](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'
+- 'email'
+- 'profile'
+- 'offline_access'
+- 'Mail.ReadWrite'
+- 'Mail.Send'
+- 'Calendars.Read'
+
+### If your app is in test mode
+
+If your app is in test mode, you will need to add test users to your project.
+
+Add your test users to the "Users and groups" section.
+
+## Background Jobs for Calendar & Messaging
+
+After configuring Gmail, Google Calendar, or Microsoft 365 integrations, you need to start the background jobs that sync data.
+
+Register the following recurring jobs in your 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
+```
+
+## Outbound Connections to Internal Hosts
+
+By default, Twenty refuses outbound connections to private/internal IP addresses (SSRF protection). This covers HTTP workflow actions, webhooks, SSO identity providers and IMAP/SMTP/CalDAV connections. If your identity provider, mail or calendar server runs on a private network, list its hostname or IP literal:
+
+```bash
+OUTBOUND_HTTP_ALLOWED_INTERNAL_HOSTS=keycloak,mail.internal,192.168.1.10
+```
+
+Entries are matched on the hostname only, without wildcards: for an OIDC issuer such as `http://keycloak:8080/realms/twenty`, list `keycloak`. Every other private address stays blocked, and even an allowed host can never reach the cloud metadata address range. Set the variable to `*` to disable the protection entirely, which is only appropriate on trusted, isolated networks.
+
+`OUTBOUND_HTTP_SAFE_MODE_ENABLED` is deprecated. While it is set to `false`, the protection stays fully off and `OUTBOUND_HTTP_ALLOWED_INTERNAL_HOSTS` is ignored, so remove it when you migrate to the list.
+
+## Email Configuration
+
+1. Go to **Settings → Admin Panel → Configuration Variables**
+2. Find the **Email** section
+3. Configure your SMTP settings:
+
+<Tabs>
+
+  <Tab title="Gmail">
+
+  You will need to provision an [App Password](https://support.google.com/accounts/answer/185833).
+  - 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">
+
+  Keep in mind that if you have 2FA enabled, you will need to provision an [App Password](https://support.microsoft.com/en-us/account-billing/manage-app-passwords-for-two-step-verification-d6dc8c6d-4bf7-4851-ad95-6d07799387e9).
+  - 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** is a fake SMTP email server for development and testing.
+  - Run the smtp4dev image: `docker run --rm -it -p 8090:80 -p 2525:25 rnwood/smtp4dev`
+  - Access the smtp4dev ui here: [http://localhost:8090](http://localhost:8090)
+  - Set the following variables:
+    - EMAIL_DRIVER=smtp
+    - EMAIL_SMTP_HOST=localhost
+    - EMAIL_SMTP_PORT=2525
+
+  </Tab>
+
+</Tabs>
+
+<Warning>
+**Environment-only mode:** If you set `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`, add these variables to your `.env` file instead.
+</Warning>
+
+## S3 Storage
+
+<Warning>
+By default, Twenty stores uploaded files on the local filesystem. For production deployments, use S3 or an S3-compatible service (MinIO, DigitalOcean Spaces, etc.) to ensure files persist across container restarts and scale across multiple server instances.
+</Warning>
+
+Set `STORAGE_TYPE=S_3` and configure the `STORAGE_S3_*` variables through the admin panel or `.env`. See the [config-variables.ts reference](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts) for the full list of S3 variables.
+
+When using S3 with CORS-dependent features (e.g. in-browser file downloads), make sure your bucket allows your Twenty frontend origin in its CORS configuration.
+
+## Logic Functions & Code Interpreter
+
+Twenty supports logic functions for workflows and the code interpreter for AI data analysis. Both run user-provided code and require explicit configuration for security.
+
+### Security Defaults
+
+**In production (NODE_ENV=production):** Both logic functions and code interpreter default to **Disabled**. You must explicitly enable them with `LOGIC_FUNCTION_TYPE` and `CODE_INTERPRETER_TYPE` if you need these features.
+
+**In development (NODE_ENV=development):** Both default to **LOCAL** for convenience when running locally.
+
+<Warning>
+**Security Notice:** The local driver (`LOGIC_FUNCTION_TYPE=LOCAL` or `CODE_INTERPRETER_TYPE=LOCAL`) runs code directly on the host in a Node.js process with no sandboxing. It should only be used for trusted code in development. For production deployments handling untrusted code, use `LOGIC_FUNCTION_TYPE=LAMBDA` or `CODE_INTERPRETER_TYPE=E2B` (with sandboxing), or keep them disabled.
+</Warning>
+
+### Logic Functions - Available Drivers
+
+| Driver | Environment Variable | Use Case | Security Level |
+|--------|---------------------|----------|----------------|
+| Disabled | `LOGIC_FUNCTION_TYPE=DISABLED` | Disable logic functions entirely | N/A |
+| Local | `LOGIC_FUNCTION_TYPE=LOCAL` | Development and trusted environments | Low (no sandboxing) |
+| Lambda | `LOGIC_FUNCTION_TYPE=LAMBDA` | Production with untrusted code | High (hardware-level isolation) |
+
+### Logic Functions - Recommended Configuration
+
+**For development:**
+```bash
+LOGIC_FUNCTION_TYPE=LOCAL  # default when NODE_ENV=development
+```
+
+**For production (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
+```
+
+**To disable logic functions:**
+```bash
+LOGIC_FUNCTION_TYPE=DISABLED  # default when NODE_ENV=production
+```
+
+### Code Interpreter - Available Drivers
+
+| Driver | Environment Variable | Use Case | Security Level |
+|--------|---------------------|----------|----------------|
+| Disabled | `CODE_INTERPRETER_TYPE=DISABLED` | Disable AI code execution | N/A |
+| Local | `CODE_INTERPRETER_TYPE=LOCAL` | Development only | Low (no sandboxing) |
+| E2B | `CODE_INTERPRETER_TYPE=E_2_B` | Production with sandboxed execution | High (isolated sandbox) |
+
+<Note>
+When using `LOGIC_FUNCTION_TYPE=DISABLED` or `CODE_INTERPRETER_TYPE=DISABLED`, any attempt to execute will return an error. This is useful if you want to run Twenty without these capabilities.
+</Note>
+
+## API and front-end on separate hosts
+
+Only relevant if you do not let the back-end serve the front-end. Same-origin
+deployments need nothing here.
+
+Declare every browser origin that talks to the API, comma separated. `SERVER_URL`
+and `FRONTEND_URL` are already trusted. The server logs a warning when a browser
+calls it from an undeclared origin.
+
+```bash
+AUTH_COOKIE_ALLOWED_ORIGINS=https://app.example.com
+```
+
+<Warning>
+The front-end sends credentials on every request, and browsers reject a
+credentialed response from an undeclared origin, so the app fails to load until
+you set this.
+</Warning>
+
+If the two hosts are on different registrable domains (not just different
+subdomains), also set `AUTH_COOKIE_SAME_SITE=none`, which requires HTTPS.
+
+With multi-workspace enabled, do not list every workspace subdomain here.
+Instead, route API paths (`/graphql`, `/metadata`, `/rest`, `/auth/`,
+`/client-config`, `/file`) to the back-end on each workspace hostname, so every
+workspace stays same-origin — this is how Twenty Cloud runs.

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

@@ -0,0 +1,242 @@
+---
+title: Troubleshooting
+icon: "wrench"
+---
+
+
+## Troubleshooting
+
+If you encounter any problem while setting up environment for development, upgrading your instance or self-hosting,
+here are some solutions for common problems.
+
+### Self-hosting
+
+#### First install results in `password authentication failed for user "postgres"`
+
+🚨 **IMPORTANT: This solution is ONLY for fresh installations** 🚨
+If you have an existing Twenty instance with production data, **DO NOT** follow these steps as they will permanently delete your database!
+
+While installing Twenty for the first time, you might want to change the default database password.
+The password you set during the first installation becomes permanently stored in the database volume. If you later try to change this password in your configuration without removing the old volume, you'll get authentication errors because the database is still using the original password.
+
+⚠️ WARNING: Following steps will PERMANENTLY DELETE all database data! ⚠️
+Only proceed if this is a fresh installation with no important data.
+
+To update the `PG_DATABASE_PASSWORD`, you need to:
+```sh
+# Update the PG_DATABASE_PASSWORD in .env
+docker compose down --volumes
+docker compose up -d
+```
+
+#### CR line breaks found [Windows]
+
+This happens because of Windows line-ending characters combined with your Git configuration. Try running:
+
+```
+git config --global core.autocrlf false
+```
+
+Then delete the repository and clone it again.
+
+#### Missing metadata schema
+
+During Twenty installation, you need to provision your postgres database with the right schemas, extensions, and users.
+If you're successful in running this provisioning, you should have `default` and `metadata` schemas in your database.
+If you don't, make sure you don't have more than one PostgreSQL instance running on your computer.
+
+#### Cannot find module 'twenty-emails' or its corresponding type declarations.
+
+You have to build the `twenty-emails` package (`npx nx run twenty-emails:build`) before running the database initialization.
+
+#### Missing twenty-x package
+
+Make sure to run yarn in the root directory and then run `npx nx server:dev twenty-server`. If this still doesn't work try building the missing package manually.
+
+#### Lint on Save not working
+
+This should work out of the box with the Oxc extension (`oxc.oxc-vscode`) installed. If this doesn't work, try adding this to your VS Code settings (dev container scope):
+
+```
+"editor.codeActionsOnSave": {
+
+  "source.fixAll.oxc": "explicit"
+
+}
+```
+
+#### While running `npx nx start` or `npx nx start twenty-front`, an out-of-memory error is thrown
+
+Run only the services you need, instead of `npx nx start`. For instance, if you work on the server, run only `npx nx worker twenty-server`
+
+**If it does not work:**
+If you tried to run only `npx nx run twenty-server:start` on WSL and it's failing with the below memory error:
+
+`FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory`
+
+A workaround is to run the following command in your terminal, or add it to your `.bashrc` profile so it's applied automatically:
+
+`export NODE_OPTIONS="--max-old-space-size=8192"`
+
+The --max-old-space-size=8192 flag sets an upper limit of 8GB for the Node.js heap; usage scales with application demand.
+Reference: https://stackoverflow.com/questions/56982005/where-do-i-set-node-options-max-old-space-size-2048
+
+**If it does not work:**
+Investigate which processes are taking up most of your machine's RAM. At Twenty, we noticed some VS Code extensions were taking up a lot of RAM, so we temporarily disabled them.
+
+**If it does not work:**
+Restarting your machine helps clean up ghost processes.
+
+#### While running `npx nx start` there are weird [0] and [1] in logs
+
+That's expected as command `npx nx start` is running more commands under the hood
+
+#### No emails are sent
+Most of the time, it's because the `worker` is not running in the background. Try to run
+```
+npx nx worker twenty-server
+```
+
+#### Cannot connect my Microsoft 365 account to Twenty
+
+Most of the time, it's because your admin has not enabled the Microsoft 365 Licence for your account. Check [https://admin.microsoft.com/](https://admin.microsoft.com/Adminportal/Home).
+
+If you have an error code `AADSTS50020`, it probably means that you are using a personal Microsoft account. This is not supported yet. More info [here](https://learn.microsoft.com/fr-fr/troubleshoot/entra/entra-id/app-integration/error-code-aadsts50020-user-account-identity-provider-does-not-exist)
+
+#### While running `yarn`, warnings appear in the console
+
+Warnings are informing about pulling additional dependencies which aren't explicitly stated in `package.json`, so as long as no breaking error appears, everything should work as expected.
+
+#### When a user accesses the login page, an error about an unauthorized user trying to access a workspace appears in the logs
+
+That's expected as the user is unauthorized when logged out, since their identity has not been verified.
+
+#### How to check if your worker is running?
+- Go to [webhook-test.com](https://webhook-test.com/) and copy **Your Unique Webhook URL**.
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/self-hosting/webhook-test.jpg" alt="Webhook test" />
+</div>
+- Open your Twenty app, navigate to `/settings`, and enable the **Advanced** toggle at the bottom left of the screen.
+- Create a new webhook.
+- Paste **Your Unique Webhook URL** in the **Endpoint Url** field in Twenty. Set the **Filters** to `Companies` and `Created`.
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/self-hosting/webhook-settings.jpg" alt="Webhook settings" />
+</div>
+- Go to `/objects/companies` and create a new company record.
+- Return to [webhook-test.com](https://webhook-test.com/) and check if a new **POST request** has been received.
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/self-hosting/webhook-test-result.jpg" alt="Webhook test result" />
+</div>
+- If a **POST request** is received, your worker is running successfully. Otherwise, you need to troubleshoot your worker.
+
+#### Front-end fails to start and returns error TS5042: Option 'project' cannot be mixed with source files on the command line
+
+Comment out the checker plugin in `packages/twenty-ui/vite-config.ts`, as shown in the example below:
+```
+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 not accessible
+
+Run `UPDATE core."user" SET "canAccessFullAdminPanel" = TRUE WHERE email = 'you@yourdomain.com';` in the database container to get access to the admin panel.
+
+#### When running workflow, workflow run fails with "Logic function execution is disabled. Set LOGIC_FUNCTION_TYPE to LOCAL or LAMBDA to enable."
+
+In production, logic functions are disabled by default. Set the `LOGIC_FUNCTION_TYPE` environment variable to `LOCAL` or `LAMBDA` to enable them. This can be configured via environment variables or through the admin panel database variables. See the [Logic Functions setup guide](/developers/self-host/capabilities/setup#logic-functions-available-drivers) for details.
+
+#### When I type a message in AI chat, it doesn't answer immediately and I must refresh the page to see the answer
+
+That means your reverse proxy is missing the configuration for stream-based API responses. Below is an example Nginx configuration:
+```
+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-click Docker Compose
+
+#### Unable to Log In
+
+If you can't log in after setup:
+1. Run the following commands:
+    ```bash
+    docker exec -it twenty-server-1 yarn
+    docker exec -it twenty-server-1 npx nx database:reset  --configuration=no-seed
+    ```
+2. Restart the Docker containers:
+    ```bash
+    docker compose down
+    docker compose up -d
+    ```
+
+Note that the `database:reset` command will completely erase your database and recreate it from scratch.
+
+#### Connection Issues Behind a Reverse Proxy
+
+If you're running Twenty behind a reverse proxy and experiencing connection issues:
+
+1. **Verify SERVER_URL:**
+
+    Ensure `SERVER_URL` in your `.env` file matches your external access URL, including `https` if SSL is enabled.
+
+2. **Check Reverse Proxy Settings:**
+
+    - Confirm that your reverse proxy is correctly forwarding requests to the Twenty server.
+    - Ensure headers like `X-Forwarded-For` and `X-Forwarded-Proto` are properly set.
+
+3. **Restart Services:**
+
+    After making changes, restart both the reverse proxy and Twenty containers.
+
+#### Error when uploading an image - permission denied
+
+Switching the data folder ownership on the host from root to another user and group resolves this problem.
+
+#### 'File Not Found' error while testing Logic function in workflow
+
+Run `yarn command:prod application:rebuild-default-deps` command in your twenty-server container to fix missing dependencies issue.
+
+## Getting Help
+
+If you encounter issues not covered in this guide:
+
+- Check Logs:
+
+    View container logs for error messages:
+    ```bash
+    docker compose logs
+    ```
+
+- Community Support:
+
+    Reach out to the [Twenty community](https://github.com/twentyhq/twenty/issues) or [support channels](https://discord.gg/cx5n4Jzs57) for assistance.

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

@@ -0,0 +1,106 @@
+---
+title: Upgrade guide
+icon: "arrow-up-right-dots"
+---
+
+## General guidelines
+
+**Always back up your database before starting the upgrade process** by running:
+
+```bash
+docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql
+```
+
+To restore from backup:
+
+```bash
+cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}
+```
+
+If you use Docker Compose, follow these steps:
+
+1. Stop Twenty: `docker compose down`
+2. Change the `TAG` value in the `.env` file next to your `docker-compose.yml`
+3. Start Twenty: `docker compose up -d`
+
+The server runs all required upgrade migrations automatically on startup. No manual command is needed.
+
+## Upgrading to v2.34+ — PostgreSQL 15 minimum
+
+Twenty v2.34 requires PostgreSQL 15 or newer. The official Docker Compose configuration uses PostgreSQL 16. If your instance connects to an externally managed database, upgrade it before starting the v2.34 server.
+
+## Cross-version upgrades (v1.23+)
+
+Starting from **v1.23**, Twenty supports cross-version upgrades. You can jump directly from any supported version to the latest release without stepping through each intermediate version.
+
+For example, upgrading from v1.23 straight to v2.0 is fully supported.
+
+## Upgrading to v2.5+ — at-rest encryption envelope
+
+Starting in **v2.5**, Twenty stores at-rest secrets (OAuth tokens, application variables, signing-key private keys, sensitive config values, TOTP secrets) inside a versioned `enc:v2:` envelope encrypted with `ENCRYPTION_KEY` (or `APP_SECRET` if `ENCRYPTION_KEY` is unset).
+
+The first boot on v2.5 runs slow upgrade commands that **backfill** existing rows into the new envelope. They are idempotent — interrupting and restarting the server resumes from where it left off — but they can take a while on large databases. You can monitor progress with `upgrade:status`.
+
+You should set a dedicated `ENCRYPTION_KEY` **before** the v2.5 upgrade so the backfill writes rows under it from the start. Switching keys after the backfill requires a [rotation](/developers/self-host/capabilities/key-rotation).
+
+## Rotating secrets and signing keys
+
+For day-to-day operational tasks like rotating `ENCRYPTION_KEY`, rotating the JWT signing key, or revoking a leaked signing key, see the dedicated [Key rotation guide](/developers/self-host/capabilities/key-rotation).
+
+## Checking upgrade status
+
+The `upgrade:status` command lets you inspect the current state of your instance and workspace migrations. It is useful for debugging upgrade issues or when filing a support request.
+
+Run it from the server container:
+
+```bash
+docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status
+```
+
+Example output:
+
+```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)
+```
+
+### Options
+
+| Flag | Description |
+| --- | --- |
+| `-w, --workspace-id <id>` | Filter to a specific workspace. Can be passed multiple times. |
+| `-f, --failed-only` | Hide up-to-date workspaces, only show behind and failed entries. |
+
+## Troubleshooting
+
+If the upgrade fails on some workspaces, the server will not advance past the failing step. Restarting the server (`docker compose up -d`) will retry the upgrade from where it left off.
+
+To quickly identify problems, run:
+
+```bash
+docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only
+```
+
+This shows only workspaces that are behind or have failed, along with the error message for each failure.
+
+## Before v1.23
+
+If your instance is older than v1.23, you must upgrade incrementally through each major tagged version (v1.6 to v1.7, then v1.7 to v1.8, and so on) until you reach v1.23. From there, you can jump directly to the latest version.