diff --git a/packages/twenty-website/public/images/user-guide/setup/admin-panel-config-variables.png b/packages/twenty-website/public/images/user-guide/setup/admin-panel-config-variables.png new file mode 100644 index 000000000..a40fb42ca Binary files /dev/null and b/packages/twenty-website/public/images/user-guide/setup/admin-panel-config-variables.png differ diff --git a/packages/twenty-website/src/content/developers/self-hosting/docker-compose.mdx b/packages/twenty-website/src/content/developers/self-hosting/docker-compose.mdx index 0f8a9fa65..3a0761b36 100644 --- a/packages/twenty-website/src/content/developers/self-hosting/docker-compose.mdx +++ b/packages/twenty-website/src/content/developers/self-hosting/docker-compose.mdx @@ -25,12 +25,12 @@ See docs [Setup Environment Variables](https://twenty.com/developers/section/sel Install the latest stable version of Twenty with a single command: ```bash -bash <(curl -sL https://git.new/20) +bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh) ``` To install a specific version or branch: ```bash -VERSION=vx.y.z BRANCH=branch-name bash <(curl -sL https://git.new/20) +VERSION=vx.y.z BRANCH=branch-name bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh) ``` - Replace x.y.z with the desired version number. - Replace branch-name with the name of the branch you want to install. diff --git a/packages/twenty-website/src/content/developers/self-hosting/setup.mdx b/packages/twenty-website/src/content/developers/self-hosting/setup.mdx index 1d6f05580..f3e79cd9b 100644 --- a/packages/twenty-website/src/content/developers/self-hosting/setup.mdx +++ b/packages/twenty-website/src/content/developers/self-hosting/setup.mdx @@ -6,47 +6,103 @@ image: /images/user-guide/table-views/table.png import OptionTable from '@site/src/theme/OptionTable' -# Setup Messaging & Calendar sync +# Configuration Management -Twenty offers integrations with Gmail and Google Calendar. + +**First time installing?** Follow the [Docker Compose installation guide](https://twenty.com/developers/section/self-hosting/docker-compose) to get Twenty running, then return here for configuration. + -## For Gmail and Google Calendar +Twenty offers **two configuration modes** to suit different deployment needs: -### Create a project in Google Cloud +**Admin panel access:** Only users with admin privileges (`canAccessFullAdminPanel: true`) can access the configuration interface. -You will need to create a project in Google Cloud and get the credentials. +## 1. Admin Panel Configuration (Default) -Then you can set the following environment variables: +```bash +IS_CONFIG_VARIABLES_IN_DB_ENABLED=true # default +``` -- `MESSAGING_PROVIDER_GMAIL_ENABLED=true` -- `CALENDAR_PROVIDER_GOOGLE_ENABLED=true` -- `MESSAGING_PROVIDER_MICROSOFT_ENABLED=false` -- `CALENDAR_PROVIDER_MICROSOFT_ENABLED=false` -- `AUTH_GOOGLE_CLIENT_ID=` -- `AUTH_GOOGLE_CLIENT_SECRET=` -- `AUTH_GOOGLE_CALLBACK_URL=https:///auth/google/redirect` if you want to use Google SSO -- `AUTH_GOOGLE_APIS_CALLBACK_URL=https:///auth/google-apis/get-access-token` +**Most configuration happens through the UI** after installation: -### Enable APIs +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) -On Google Cloud Console, go to [APIs & Services](https://console.cloud.google.com/apis/library/) and enable the following APIs: + +**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). + +**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) + + +**Some configuration requires setting in .env:** Infrastructure like database connections (`PG_DATABASE_URL`), server URLs (`SERVER_URL`), and app secrets (`APP_SECRET`) can only be configured via `.env` file. +Those configurations are marked as `isEnvOnly: true` in the source code. + +[See complete list of environment-only variables →](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts) + + +## 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 + +## 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) -### Authorized redirect URIs +### Configure OAuth -Under [Credentials](https://console.cloud.google.com/apis/credentials), in OAuth 2.0 Client IDs, you need to add the following redirect URIs to your project: +1. Go to [Credentials](https://console.cloud.google.com/apis/credentials) +2. Create OAuth 2.0 Client ID +3. Add these redirect URIs: + - `https:///auth/google/redirect` (for SSO) + - `https:///auth/google-apis/get-access-token` (for integrations) -- `https:///auth/google/redirect` if you want to use Google SSO -- `https:///auth/google-apis/get-access-token` +### Configure in Twenty -### Configure scopes +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=` + - `AUTH_GOOGLE_CLIENT_SECRET=` + - `AUTH_GOOGLE_CALLBACK_URL=https:///auth/google/redirect` + - `AUTH_GOOGLE_APIS_CALLBACK_URL=https:///auth/google-apis/get-access-token` + + +**Environment-only mode:** If you set `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`, add these variables to your `.env` file instead. + + +**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' +- `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 @@ -54,21 +110,7 @@ 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. -### Start the cron jobs - -Register the following recurring jobs: -``` -# 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 -``` - -## For Outlook and Outlook Calendar (Microsoft 365) +## Microsoft 365 Integration 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. @@ -78,16 +120,6 @@ Users must have a [Microsoft 365 Licence](https://admin.microsoft.com/Adminporta You will need to create a project in [Microsoft Azure](https://portal.azure.com/#view/Microsoft_AAD_IAM/AppGalleryBladeV2) and get the credentials. -Then you can set the following environment variables: - -- `MESSAGING_PROVIDER_MICROSOFT_ENABLED=true` -- `CALENDAR_PROVIDER_MICROSOFT_ENABLED=true` -- `AUTH_MICROSOFT_ENABLED=true` -- `AUTH_MICROSOFT_CLIENT_ID=` -- `AUTH_MICROSOFT_CLIENT_SECRET=` -- `AUTH_MICROSOFT_CALLBACK_URL=https:///auth/microsoft/redirect` if you want to use Microsoft SSO -- `AUTH_MICROSOFT_APIS_CALLBACK_URL=https:///auth/microsoft-apis/get-access-token` - ### Enable APIs On Microsoft Azure Console enable the following APIs in "Permissions": @@ -109,6 +141,23 @@ You need to add the following redirect URIs to your project: - `https:///auth/microsoft/redirect` if you want to use Microsoft SSO - `https:///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=` + - `AUTH_MICROSOFT_CLIENT_SECRET=` + - `AUTH_MICROSOFT_CALLBACK_URL=https:///auth/microsoft/redirect` + - `AUTH_MICROSOFT_APIS_CALLBACK_URL=https:///auth/microsoft-apis/get-access-token` + + +**Environment-only mode:** If you set `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`, add these variables to your `.env` file instead. + + ### 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' @@ -125,10 +174,12 @@ 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. -### Start the cron jobs +## Background Jobs for Calendar & Messaging -Register the following recurring jobs: -``` +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 @@ -139,86 +190,11 @@ yarn command:prod cron:calendar:ongoing-stale yarn command:prod cron:workflow:automated-cron-trigger ``` -# Setup Environment Variables +## Email Configuration -## Frontend - - - - -## Backend - -### Config - - - -### Security - - -### Tokens - -', 'Secret used for encryption across the app'], - ['ACCESS_TOKEN_EXPIRES_IN', '30m', 'Access token expiration time'], - ['LOGIN_TOKEN_EXPIRES_IN', '15m', 'Login token expiration time'], - ['REFRESH_TOKEN_EXPIRES_IN', '90d', 'Refresh token expiration time'], - ['REFRESH_TOKEN_COOL_DOWN', '1m', 'Refresh token cooldown'], - ['FILE_TOKEN_EXPIRES_IN', '1d', 'File token expiration time'], - ]}> - -### Auth - - - -### Email - - - -#### Email SMTP Server configuration examples +1. Go to **Settings → Admin Panel → Configuration Variables** +2. Find the **Email** section +3. Configure your SMTP settings: @@ -249,7 +225,7 @@ yarn command:prod cron:workflow:automated-cron-trigger **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 env variables: + - Set the following variables: - EMAIL_DRIVER=smtp - EMAIL_SMTP_HOST=localhost - EMAIL_SMTP_PORT=2525 @@ -258,101 +234,6 @@ yarn command:prod cron:workflow:automated-cron-trigger -### Storage - - - -### Custom Code Execution - - - -### Logging and Observability - - - - -### Data enrichment and AI - - - -### Serverless functions -This feature is WIP and is not yet useful for most users. - - - - - -### Support Chat - -', 'Support chat key'], - ['SUPPORT_FRONT_CHAT_ID', '', 'Support chat id'], - ]}> - -### Telemetry - - - -### Debug / Development - - - -### Workspace Cleaning - - - -### Captcha - - - - + +**Environment-only mode:** If you set `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`, add these variables to your `.env` file instead. + \ No newline at end of file