From 0dec4b9b673e8f51e5a01f8e4013e36e2d23dbb2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A9lix=20Malfait?= Date: Mon, 22 Dec 2025 18:10:41 +0100 Subject: [PATCH] docs: add IS_MULTIWORKSPACE_ENABLED documentation (#16758) ## Summary Adds comprehensive documentation for the `IS_MULTIWORKSPACE_ENABLED` configuration variable, which was previously undocumented despite being a fundamental configuration option that significantly changes how Twenty behaves. ## Changes ### Self-Host Setup Guide (`setup.mdx`) Added a new **Multi-Workspace Mode** section that explains: - **Single-workspace mode (default)**: Only one workspace allowed, first user gets admin privileges, signups disabled after first workspace - **Multi-workspace mode**: Multiple workspaces with subdomain-based URLs (e.g., `sales.your-domain.com`) - **Related config variables**: `DEFAULT_SUBDOMAIN` and `IS_WORKSPACE_CREATION_LIMITED_TO_SERVER_ADMINS` - **DNS configuration**: Wildcard DNS setup for dynamic subdomains - **Workspace creation restrictions**: How to limit workspace creation to server admins ### Local Setup Guide (`local-setup.mdx`) Added an info callout in the environment variables section to make contributors aware of multi-workspace mode, useful when testing subdomain-based features. ## Why This Matters The `IS_MULTIWORKSPACE_ENABLED` variable controls: - Whether multiple workspaces can exist on a single instance - URL structure (plain domain vs subdomains) - First user privileges - Sign-up behavior after initial setup - SSO workspace resolution logic This is critical knowledge for self-hosters who want to run Twenty as a multi-tenant SaaS. --- .../contribute/capabilities/local-setup.mdx | 4 ++ .../self-host/capabilities/setup.mdx | 55 +++++++++++++++++++ 2 files changed, 59 insertions(+) diff --git a/packages/twenty-docs/developers/contribute/capabilities/local-setup.mdx b/packages/twenty-docs/developers/contribute/capabilities/local-setup.mdx index d68f78fce6..54be4aef33 100644 --- a/packages/twenty-docs/developers/contribute/capabilities/local-setup.mdx +++ b/packages/twenty-docs/developers/contribute/capabilities/local-setup.mdx @@ -235,6 +235,10 @@ cp ./packages/twenty-front/.env.example ./packages/twenty-front/.env cp ./packages/twenty-server/.env.example ./packages/twenty-server/.env ``` + +**Multi-Workspace Mode:** By default, Twenty runs in single-workspace mode where only one workspace can be created. To enable multi-workspace support (useful for testing subdomain-based features), set `IS_MULTIWORKSPACE_ENABLED=true` in your server `.env` file. See [Multi-Workspace Mode](/developers/self-host/capabilities/setup#multi-workspace-mode) for details. + + ## Step 6: Installing dependencies To build Twenty server and seed some data into your database, run the following command: ```bash diff --git a/packages/twenty-docs/developers/self-host/capabilities/setup.mdx b/packages/twenty-docs/developers/self-host/capabilities/setup.mdx index b8b0106f1a..56deccd33a 100644 --- a/packages/twenty-docs/developers/self-host/capabilities/setup.mdx +++ b/packages/twenty-docs/developers/self-host/capabilities/setup.mdx @@ -59,6 +59,61 @@ IS_CONFIG_VARIABLES_IN_DB_ENABLED=false 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 + + +**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. + + +### 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