Skip to content

update setup docs - config variables #12370

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jun 3, 2025
Merged

update setup docs - config variables #12370

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f5a6353
update
ehconitin May 28, 2025
601446d
Merge branch 'main' into update-setup-docs
ehconitin Jun 2, 2025
b9e8f7c
improve
ehconitin Jun 2, 2025
a6b27b1
improve
ehconitin Jun 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added ...wenty-website/public/images/user-guide/setup/admin-panel-config-variables-1.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added ...wenty-website/public/images/user-guide/setup/admin-panel-config-variables-2.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
231 changes: 67 additions & 164 deletions packages/twenty-website/src/content/developers/self-hosting/setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,84 +139,86 @@ yarn command:prod cron:calendar:ongoing-stale
yarn command:prod cron:workflow:automated-cron-trigger
```

# Setup Environment Variables
# Configuration Management

## Frontend
Twenty uses a hybrid approach for configuration management, combining environment variables with an admin panel interface.

<ArticleTable options={[
['REACT_APP_SERVER_BASE_URL', 'http://localhost:3000', 'Url of backend server'],
['GENERATE_SOURCEMAP', 'false', 'Generate source maps for debugging'],
['CHROMATIC_PROJECT_TOKEN', '', 'Chromatic token used for CI'],
]}></ArticleTable>
## Admin Panel Configuration

**Most configuration can be managed through the Admin Panel** once your instance is running:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we have this run automatically so that users don't have to think about it during setup?

"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"

Maybe create one super command or integrate it as part of the upgrade... Never dug into this so not 100% sure what they do. But it would help us keep the docs focused on Env Var only

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can be in another PR of course


## Backend
1. Sign in to your Twenty instance
2. Go to **Settings → Admin Panel → Configuration Variables**
3. Configure authentication, email, storage, integrations, and more
4. Changes take effect immediately (within 15 seconds for multi-instance deployments)

### Config
<ArticleWarning>
**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).
</ArticleWarning>

<ArticleTable options={[
['PG_DATABASE_URL', 'postgres://user:pw@localhost:5432/default?connection_limit=1', 'Database connection'],
['PG_SSL_ALLOW_SELF_SIGNED', 'false', 'Allow self signed certificates'],
['REDIS_URL', 'redis://localhost:6379', 'Redis connection url'],
['FRONT_DOMAIN', 'localhost', 'Domain of the hosted frontend'],
['DEFAULT_SUBDOMAIN', 'app', 'The default subdomain name when multiworkspace mode is enabled'],
['SERVER_URL', 'http://localhost:3000', 'Url to the hosted server'],
['FRONTEND_URL', '$SERVER_URL', 'Url to the frontend server. Same as SERVER_URL by default'],
['PORT', '3000', 'Port of the backend server'],
['CACHE_STORAGE_TTL', '3600 * 24 * 7', 'Cache TTL in seconds'],
]}></ArticleTable>
### Who Can Access
Only users with admin privileges (`canAccessFullAdminPanel: true`) can access the admin panel configuration.

### Security
### What Can Be Configured
The admin panel allows you to configure:
- **Authentication:** Google/Microsoft OAuth, password settings
- **Email:** SMTP settings, email templates, verification
- **Storage:** Local/S3 configuration
- **Integrations:** Gmail, Google Calendar, Microsoft services
- **Workflow & Rate Limiting:** Execution limits, API throttling
- And much more...

<ArticleTable options={[
['API_RATE_LIMITING_TTL', '100', 'API rate limiting time window'],
['API_RATE_LIMITING_LIMIT', '200', 'API rate limiting max requests'],
]}></ArticleTable>
### Tokens
![Admin Panel Configuration Variables](/images/user-guide/setup/admin-panel-config-variables-1.png)

<ArticleTable options={[
['APP_SECRET', '<random>', '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'],
]}></ArticleTable>
## Essential Environment Variables

### Auth
Before starting Twenty, you **must** set these core infrastructure variables that cannot be changed through the admin panel:

<ArticleTable options={[
['MESSAGING_PROVIDER_GMAIL_ENABLED', 'false', 'Enable Gmail API connection'],
['CALENDAR_PROVIDER_GOOGLE_ENABLED', 'false', 'Enable Google Calendar API connection'],
['AUTH_GOOGLE_APIS_CALLBACK_URL', 'https://[YourDomain]/auth/google-apis/get-access-token', 'Google APIs auth callback'],
['AUTH_PASSWORD_ENABLED', 'false', 'Enable Email/Password login'],
['AUTH_GOOGLE_ENABLED', 'false', 'Enable Google SSO login'],
['AUTH_GOOGLE_CLIENT_ID', '123456789012-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com', 'Google client ID'],
['AUTH_GOOGLE_CLIENT_SECRET', '', 'Google client secret'],
['AUTH_GOOGLE_CALLBACK_URL', 'https://[YourDomain]/auth/google/redirect', 'Google auth callback'],
['AUTH_MICROSOFT_ENABLED', 'false', 'Enable Microsoft SSO login'],
['AUTH_MICROSOFT_CLIENT_ID', '', 'Microsoft client ID'],
['AUTH_MICROSOFT_CLIENT_SECRET', '', 'Microsoft client secret'],
['AUTH_MICROSOFT_CALLBACK_URL', 'https://[YourDomain]/auth/microsoft/redirect', 'Microsoft auth callback'],
['AUTH_MICROSOFT_APIS_CALLBACK_URL', 'http://[YourDomain]/auth/microsoft-apis/get-access-token', 'Microsoft APIs auth callback'],
['IS_MULTIWORKSPACE_ENABLED', 'false', 'Allows the use of multiple workspaces. Requires a web server that can manage wildcards for subdomains.'],
['PASSWORD_RESET_TOKEN_EXPIRES_IN', '5m', 'Password reset token expiration time'],
]}></ArticleTable>
### Required Infrastructure
```bash
# Database & Cache
PG_DATABASE_URL=postgres://user:password@localhost:5432/twenty
REDIS_URL=redis://localhost:6379

### Email
# Server Configuration
SERVER_URL=http://localhost:3000
APP_SECRET=your-secret-key-here

# Frontend URL (defaults to SERVER_URL if not set)
FRONTEND_URL=http://localhost:3001
```

### Environment-Only Variables
Some infrastructure and system-level variables cannot be changed through the admin panel and must remain in your `.env` file. These are marked as `isEnvOnly: true` in the codebase for security and infrastructure reasons.

**Key categories that remain environment-only:**
- **Database & Cache connections** (`PG_DATABASE_URL`, `REDIS_URL`)
- **Core server configuration** (`SERVER_URL`, `APP_SECRET`, `NODE_ENV`)
- **Infrastructure settings** (database pool, logging drivers, SSL certificates)


## Configuration Modes

### Default Mode (Database Configuration Enabled)
- `IS_CONFIG_VARIABLES_IN_DB_ENABLED=true` (default)
- Admin panel changes **override** .env values
- Most settings can be changed without touching .env files

![Config Variables](/images/user-guide/setup/admin-panel-config-variables-2.png)

### Environment-Only Mode
- Set `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`
- Admin panel shows current values and descriptions but can't be changed
- All configuration must be managed through .env files


## Frontend

<ArticleTable options={[
['IS_EMAIL_VERIFICATION_REQUIRED', 'false', 'If enabled, users must verify their email address before signing in. When true, users will receive a verification email after registration'],
['EMAIL_VERIFICATION_TOKEN_EXPIRES_IN', '1h', 'How long email verification tokens remain valid before requiring a new verification email'],
['EMAIL_FROM_ADDRESS', '[email protected]', 'Global email From: header used to send emails'],
['EMAIL_FROM_NAME', 'John from YourDomain', 'Global name From: header used to send emails'],
['EMAIL_SYSTEM_ADDRESS', '[email protected]', 'Email address used as a destination to send internal system notification'],
['EMAIL_DRIVER', 'logger', "Email driver: 'logger' (to log emails in console) or 'smtp'"],
['EMAIL_SMTP_HOST', '', 'Email SMTP Host'],
['EMAIL_SMTP_PORT', '', 'Email SMTP Port'],
['EMAIL_SMTP_USER', '', 'Email SMTP User'],
['EMAIL_SMTP_PASSWORD', '', 'Email SMTP Password'],
]}></ArticleTable>
['REACT_APP_SERVER_BASE_URL', 'http://localhost:3000', 'Url of backend server'],
['GENERATE_SOURCEMAP', 'false', 'Generate source maps for debugging'],
['CHROMATIC_PROJECT_TOKEN', '', 'Chromatic token used for CI'],
]}></ArticleTable>

#### Email SMTP Server configuration examples

Expand Down Expand Up @@ -256,103 +258,4 @@ yarn command:prod cron:workflow:automated-cron-trigger

</ArticleTab>

</ArticleTabs>

### Storage

<ArticleTable options={[
['STORAGE_TYPE', 'local', "Storage driver: 'local' or 's3'"],
['STORAGE_S3_REGION', '', 'Storage Region'],
['STORAGE_S3_NAME', '', 'Bucket Name'],
['STORAGE_S3_ENDPOINT', '', 'Use if a different Endpoint is needed (for example Google)'],
['STORAGE_S3_ACCESS_KEY_ID', '', 'Optional depending on the authentication method'],
['STORAGE_S3_SECRET_ACCESS_KEY', '', 'Optional depending on the authentication method'],
['STORAGE_LOCAL_PATH', '.local-storage', 'Data path (local storage)'],
]}></ArticleTable>

### Custom Code Execution

<ArticleTable options={[
['SERVERLESS_TYPE', 'local', "Serverless driver type: 'local' or 'lambda'"],
['SERVERLESS_LAMBDA_REGION', '', 'Lambda Region'],
['SERVERLESS_LAMBDA_ROLE', '', 'Lambda Role'],
['SERVERLESS_LAMBDA_SUBHOSTING_ROLE', '', 'Role to assume when hosting lambdas in dedicated AWS account'],
['SERVERLESS_LAMBDA_ACCESS_KEY_ID', '', 'Optional depending on the authentication method'],
['SERVERLESS_LAMBDA_SECRET_ACCESS_KEY', '', 'Optional depending on the authentication method'],
]}></ArticleTable>

### Logging and Observability

<ArticleTable options={[
['LOGGER_DRIVER', 'console', "Currently, only supports 'console'"],
['LOGGER_IS_BUFFER_ENABLED', 'true', 'Buffer the logs before sending them to the logging driver'],
['LOG_LEVELS', 'error,warn', "The loglevels which are logged to the logging driver. Can include: 'log', 'warn', 'error'"],
['EXCEPTION_HANDLER_DRIVER', 'sentry', "The exception handler driver can be: 'console' or 'sentry'"],
['SENTRY_ENVIRONMENT', 'main', 'The sentry environment used if sentry logging driver is selected'],
['SENTRY_DSN', 'https://[email protected]/xxx', 'The sentry logging endpoint used if sentry logging driver is selected'],
['SENTRY_FRONT_DSN', 'https://[email protected]/xxx', 'The sentry logging endpoint used by the frontend if sentry logging driver is selected'],
['METER_DRIVER', 'console', "The meter driver can be: 'console' and/or 'opentelemetry' "],
['OTLP_COLLECTOR_ENDPOINT_URL', '', 'The OpenTelemetry collector endpoint collects metrics if opentelemetry meter driver is selected. The collector has to be set separately.'],
]}></ArticleTable>


### Data enrichment and AI

<ArticleTable options={[
['OPENAI_API_KEY', 'sk-proj-abcdabcd...', "OpenAI API key"],
['LLM_CHAT_MODEL_DRIVER', 'openai', "LLM provider"],
['LLM_TRACING_DRIVER', 'langfuse', "Where to output LangChain logs. 'langfuse' or 'console'."],
['LANGFUSE_SECRET_KEY', 'sk-lf-abcdabcd-abcd...', "Langfuse secret key"],
['LANGFUSE_PUBLIC_KEY', 'pk-lf-abcdabcd-abcd...', "Langfuse public key"],
]}></ArticleTable>

### Serverless functions
This feature is WIP and is not yet useful for most users.
<ArticleTable options={[
['SERVERLESS_TYPE', 'local', "Functions can either be executed through Lambda or directly by the main node process"],
['SERVERLESS_LAMBDA_REGION', 'us-east-1', 'If you use the Lambda driver, region of the Lambda function'],
['SERVERLESS_LAMBDA_ROLE', 'arn:aws:iam::121334:role/lambda-execution-role', "If you use the Lambda driver, name of the IAM role with the right permissions"],
['SERVERLESS_LAMBDA_SUBHOSTING_ROLE', 'arn:aws:iam::121334:role/lambda-deployment-role', "If you host lambdas in a dedicated AWS account, name of the IAM role to assume in the dedicated account"],
]}></ArticleTable>




### Support Chat

<ArticleTable options={[
['SUPPORT_DRIVER', 'front', "Support driver ('front' or 'none')"],
['SUPPORT_FRONT_HMAC_KEY', '<secret>', 'Support chat key'],
['SUPPORT_FRONT_CHAT_ID', '<id>', 'Support chat id'],
]}></ArticleTable>

### Telemetry

<ArticleTable options={[
['TELEMETRY_ENABLED', 'true', 'Change this if you want to disable telemetry'],
['TELEMETRY_ANONYMIZATION_ENABLED', 'true', 'Telemetry is anonymized by default, you probably don\'t want to change this'],
]}></ArticleTable>

### Debug / Development

<ArticleTable options={[
['SIGN_IN_PREFILLED', 'true', 'Prefill the Sign in form for usage in a demo or dev environment'],
]}></ArticleTable>

### Workspace Cleaning

<ArticleTable options={[
['WORKSPACE_INACTIVE_DAYS_BEFORE_NOTIFICATION', '', 'Number of inactive days before sending workspace deleting warning email'],
['WORKSPACE_INACTIVE_DAYS_BEFORE_SOFT_DELETION', '', 'Number of inactive days before soft deleting workspace'],
['WORKSPACE_INACTIVE_DAYS_BEFORE_DELETION', '', 'Number of inactive days before destroying workspace'],
]}></ArticleTable>

### Captcha

<ArticleTable options={[
['CAPTCHA_DRIVER', '', "The captcha driver can be 'google-recaptcha' or 'turnstile'"],
['CAPTCHA_SITE_KEY', '', 'The captcha site key'],
['CAPTCHA_SECRET_KEY', '', 'The captcha secret key'],
]}></ArticleTable>

<ArticleEditContent></ArticleEditContent>
</ArticleTabs>