セットアップ

​

構成管理

初めてインストールしますか？ Docker Compose インストールガイドに従ってTwentyを起動し、その後はここに戻り構成してください。

Twentyは、異なる展開ニーズに合わせて2つの構成モードを提供します:

管理パネルアクセス: 管理者権限を持つユーザーだけが (canAccessFullAdminPanel: true) 構成インターフェースにアクセスできます。

​

1. 管理パネル構成（デフォルト）

IS_CONFIG_VARIABLES_IN_DB_ENABLED=true  # default

ほとんどの構成は、インストール後にUIを通じて行われます。

1. Twentyインスタンスにアクセスしてください (通常は http://localhost:3000)
2. 設定 / 管理パネル / 構成変数に移動
3. 統合、メール、ストレージなどを構成します
4. 変更はすぐに（マルチコンテナ展開の場合、15秒以内に）効果が出ます。

マルチコンテナ展開: データベース構成を使用する場合 (IS_CONFIG_VARIABLES_IN_DB_ENABLED=true)、サーバーとワーカーコンテナの両方が同じデータベースから読み込みます。 管理パネルの変更は両方に自動的に影響し、コンテナ間で環境変数を重複させる必要がなくなります（インフラストラクチャの変数を除く）。 管理パネルの変更は両方に自動的に影響し、コンテナ間で環境変数を重複させる必要がなくなります（インフラストラクチャの変数を除く）。

管理パネルを通じて構成できること:

• 認証 - Google/Microsoft OAuth、パスワード設定
• メール - SMTP設定、テンプレート、検証
• ストレージ - S3構成、ローカルストレージパス
• 統合 - Gmail、Googleカレンダー、Microsoftサービス
• ワークフローとレート制限 - 実行制限、APIスロットリング
• さらに多くのこと…

各変数は、設定 → 管理パネル → 構成変数 で説明付きでドキュメント化されています。 データベース接続 (PG_DATABASE_URL)、サーバーURL (SERVER_URL)、秘密情報 (ENCRYPTION_KEY, FALLBACK_ENCRYPTION_KEY) など、一部のインフラ設定は .env ファイルを介してのみ構成できます。

完全な技術リファレンス →

​

暗号鍵

Twenty は、環境変数でのみ設定可能な暗号鍵を 2 つ使用します:

変数	目的	必須
ENCRYPTION_KEY	保存時の秘密情報（OAuth トークン、アプリケーション変数、署名鍵の秘密鍵、TOTP シークレット、機密性の高い構成値）を暗号化するために使用されるプライマリキー。	新規インストールでは必須（レガシーインストールでは代わりに APP_SECRET に依存している場合があります — 下記参照）
FALLBACK_ENCRYPTION_KEY	検証専用のキー。 ローテーション時に、既存の行を復号可能なままにするため、以前の ENCRYPTION_KEY を設定します。	ローテーション中のみ

後方互換性のため、ENCRYPTION_KEY が未設定の場合、Twenty は保存時の暗号化に APP_SECRET をフォールバックとして使用します。これは、旧来のデプロイメントにおける従来の動作と一致します。 新規インストールでは、必ず専用の ENCRYPTION_KEY を設定してください。

openssl rand -base64 32 で値を生成し、シークレットマネージャーやシールドされた構成など、安全な場所に保管してください。 ENCRYPTION_KEY を失うことは、データベースに保存されているすべての秘密情報へのアクセスを失うことを意味します。

ダウンタイムなしで ENCRYPTION_KEY をローテーションする方法については、キー ローテーション ガイド を参照してください。

​

2. 環境のみの構成

IS_CONFIG_VARIABLES_IN_DB_ENABLED=false

すべての構成が .env ファイルで管理されます:

1. .env ファイル内で IS_CONFIG_VARIABLES_IN_DB_ENABLED=false を設定
2. すべての構成変数を .env ファイルに追加
3. 変更を有効にするためにコンテナを再起動してください
4. 管理パネルは現在の値を表示しますが、修正はできません

​

マルチワークスペースモード

デフォルトでは、Twenty はシングルワークスペースモードで動作します—組織向けに 1 つの CRM インスタンスが必要な多くのセルフホスト型デプロイメントに最適です。

​

シングルワークスペースモード（デフォルト）

IS_MULTIWORKSPACE_ENABLED=false  # default

• Twenty の各インスタンスにつき 1 つのワークスペース
• 最初のユーザーは自動的にフル権限の管理者になります（canImpersonate と canAccessFullAdminPanel）
• 最初のワークスペース作成後は新規サインアップが無効になります
• シンプルな URL 構造: https://your-domain.com

​

マルチワークスペースモードの有効化

IS_MULTIWORKSPACE_ENABLED=true
DEFAULT_SUBDOMAIN=app  # default value

同一の Twenty インスタンス上で複数の独立したチームがそれぞれのワークスペースを必要とする、SaaS のようなデプロイメント向けにマルチワークスペースモードを有効にします。

シングルワークスペースモードとの主な違い:

• 同一インスタンス上に複数のワークスペースを作成できます
• 各ワークスペースに専用のサブドメインが割り当てられます（例: sales.your-domain.com、marketing.your-domain.com）
• ユーザーは {DEFAULT_SUBDOMAIN}.your-domain.com でサインアップおよびログインします（例: app.your-domain.com）
• 管理者権限は自動付与されません—各ワークスペースの最初のユーザーは一般ユーザーです
• サブドメインやカスタムドメインなどのワークスペース固有の設定がワークスペース設定で利用可能になります

環境専用の設定: IS_MULTIWORKSPACE_ENABLED は .env ファイルでのみ設定でき、再起動が必要です。 管理パネルからは変更できません。

​

マルチワークスペース向けの DNS 構成

マルチワークスペースモードを使用する場合、動的なサブドメイン作成を可能にするために、ワイルドカードレコードで DNS を構成してください:

*.your-domain.com -> your-server-ip

これにより、手動の DNS 構成なしで新規ワークスペースへのサブドメインルーティングが自動化されます。

​

ワークスペース作成の制限

マルチワークスペースモードでは、新しいワークスペースを作成できるユーザーを制限したい場合があります:

IS_WORKSPACE_CREATION_LIMITED_TO_SERVER_ADMINS=true

有効にすると、canAccessFullAdminPanel を持つユーザーのみが追加のワークスペースを作成できます。 初回サインアップ時には、ユーザーは引き続き最初のワークスペースを作成できます。

​

Gmail & Googleカレンダー統合

​

Google Cloudプロジェクトを作成

1. Google Cloud Console にアクセス
2. 新しいプロジェクトを作成するか既存のプロジェクトを選択
3. 以下のAPIを有効にします:

• Gmail API
• GoogleカレンダーAPI
• People API

​

OAuthの構成

1. 資格情報にアクセス
2. OAuth 2.0 クライアントIDを作成
3. 次のリダイレクトURIを追加:
   • https://{your-domain}/auth/google/redirect (SSO用)
   • https://{your-domain}/auth/google-apis/get-access-token (統合用)

​

Twentyで構成

1. 設定 → 管理パネル → 構成変数 に移動
2. Google Auth セクションを見つけます
3. 次の変数を設定:
   • 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

環境専用モード: IS_CONFIG_VARIABLES_IN_DB_ENABLED=false を設定した場合、これらの変数を .env ファイルに追加してください。

必要なスコープ (自動的に構成される): 関連ソースコードを見る

• https://www.googleapis.com/auth/calendar.events
• https://www.googleapis.com/auth/gmail.readonly
• https://www.googleapis.com/auth/profile.emails.read

​

アプリがテストモードの場合

アプリがテストモードの場合、プロジェクトにテストユーザーを追加する必要があります。

OAuth 同意画面で、「テストユーザー」セクションにテストユーザーを追加してください。

​

Microsoft 365 統合

カレンダーおよびメッセージングAPIを使用するためには、Microsoft 365 ライセンスが必要です。 They will not be able to sync their account on Twenty without one. それがない場合、Twenty でアカウントを同期できません。

​

Microsoft Azureでプロジェクトを作成

Microsoft Azureでプロジェクトを作成し、資格情報を取得してください。

​

APIを有効にする

Microsoft Azureコンソールで”権限”の欄で以下のAPIを有効にします:

• 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

“Mail.ReadWrite” と “Mail.Send” は、ワークフローアクションを使用してメールを送信する場合にのみ必須です。 メールを受信するだけの場合は、“Mail.Read”を使用できます。

ワークフローアクションを使用してカレンダーイベントを作成する場合は、“Calendars.ReadWrite” が必須です。 カレンダーイベントを同期するだけの場合は、“Calendars.Read” を使用してください。

​

認証されたリダイレクトURI

プロジェクトに次のリダイレクトURIを追加する必要があります:

• https://{your-domain}/auth/microsoft/redirect マイクロソフトSSO を使用する場合
• https://{your-domain}/auth/microsoft-apis/get-access-token

​

Twentyで構成

1. 設定 → 管理パネル → 構成変数 に移動
2. Microsoft Auth セクションを見つけます
3. 次の変数を設定:
   • 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

環境専用モード: IS_CONFIG_VARIABLES_IN_DB_ENABLED=false を設定した場合、これらの変数を .env ファイルに追加してください。

​

スコープを構成

関連ソースコードを見る

• ‘openid’
• ‘メール’
• ‘プロフィール’
• ‘offline_access’
• ‘Mail.ReadWrite’
• ‘Mail.Send’
• ‘Calendars.Read’

​

アプリがテストモードの場合

アプリがテストモードの場合、プロジェクトにテストユーザーを追加する必要があります。

「ユーザーとグループ」セクションにテストユーザーを追加してください。

​

カレンダーとメッセージングのバックグラウンドジョブ

Gmail、Googleカレンダー、またはMicrosoft 365統合を構成した後、データを同期するバックグラウンドジョブを開始する必要があります。

次の定期ジョブをワーカーコンテナに登録してください:

# 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

​

メール設定

1. 設定 → 管理パネル → 構成変数 に移動
2. メール セクションを見つけます
3. SMTP設定を構成:

Gmail

アプリパスワードを準備する必要があります。

• 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’

Office365

2FAを有効にしている場合、アプリパスワードを準備する必要があります。

• EMAIL_DRIVER=smtp
• EMAIL_SMTP_HOST=smtp.office365.com
• EMAIL_SMTP_PORT=587
• EMAIL_SMTP_USER=office365_email_address
• EMAIL_SMTP_PASSWORD=‘office365_password’

smtp4dev

smtp4dev は開発とテストのためのフェイクSMTPメールサーバーです。

• smtp4devイメージを実行: docker run --rm -it -p 8090:80 -p 2525:25 rnwood/smtp4dev
• smtp4dev UIにアクセス: http://localhost:8090
• 次の変数を設定:
  • EMAIL_DRIVER=smtp
  • EMAIL_SMTP_HOST=localhost
  • EMAIL_SMTP_PORT=2525

環境専用モード: IS_CONFIG_VARIABLES_IN_DB_ENABLED=false を設定した場合、これらの変数を .env ファイルに追加してください。

​

S3 ストレージ

デフォルトでは、Twenty はアップロードされたファイルをローカルのファイルシステムに保存します。 本番環境へのデプロイでは、S3 または S3 互換のサービス（MinIO、DigitalOcean Spaces など）を使用してください。 コンテナの再起動をまたいでファイルを永続化し、複数のサーバーインスタンスにまたがってスケールできるようにするため。

STORAGE_TYPE=S_3 を設定し、管理パネルまたは .env から STORAGE_S3_* 変数を設定してください。 S3 変数の全一覧については、config-variables.ts リファレンス を参照してください。

CORS に依存する機能（例: ブラウザ内でのファイルダウンロード）で S3 を使用する場合は、バケットの CORS 設定で Twenty フロントエンドのオリジンが許可されていることを確認してください。

​

ロジック関数とコードインタープリター

Twenty は、ワークフロー向けのロジック関数と、AI データ分析用のコードインタープリターをサポートします。 どちらもユーザー提供のコードを実行し、セキュリティのために明示的な設定が必要です。

​

セキュリティのデフォルト

本番環境 (NODE_ENV=production): ロジック関数とコードインタープリターはいずれもデフォルトで無効です。 これらの機能が必要な場合は、LOGIC_FUNCTION_TYPE と CODE_INTERPRETER_TYPE で明示的に有効化する必要があります。

開発環境 (NODE_ENV=development): ローカルでの実行を容易にするため、どちらもデフォルトではLOCALです。

セキュリティに関する注意: ローカルドライバー (LOGIC_FUNCTION_TYPE=LOCAL または CODE_INTERPRETER_TYPE=LOCAL) は、ホスト上の Node.js プロセス内でサンドボックスなしにコードを直接実行します。 開発では、信頼できるコードにのみ使用してください。 信頼できないコードを扱う本番デプロイでは、LOGIC_FUNCTION_TYPE=LAMBDA または CODE_INTERPRETER_TYPE=E2B（サンドボックス化あり）を使用するか、無効のままにしてください。

​

ロジック関数 - 利用可能なドライバー

ドライバー	環境変数	ユースケース	セキュリティレベル
無効	LOGIC_FUNCTION_TYPE=DISABLED	ロジック関数を完全に無効化する	該当なし
ローカル	LOGIC_FUNCTION_TYPE=LOCAL	開発および信頼できる環境	低（サンドボックスなし）
Lambda	LOGIC_FUNCTION_TYPE=LAMBDA	信頼できないコードを扱う本番環境	高（ハードウェアレベルの分離）

​

ロジック関数 - 推奨構成

開発向け:

LOGIC_FUNCTION_TYPE=LOCAL  # default when NODE_ENV=development

本番向け（AWS）:

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

ロジック関数を無効化するには:

LOGIC_FUNCTION_TYPE=DISABLED  # default when NODE_ENV=production

​

コードインタープリター - 利用可能なドライバー

ドライバー	環境変数	ユースケース	セキュリティレベル
無効	CODE_INTERPRETER_TYPE=DISABLED	AIコード実行を無効化	該当なし
ローカル	CODE_INTERPRETER_TYPE=LOCAL	開発専用	低（サンドボックスなし）
E2B	CODE_INTERPRETER_TYPE=E_2_B	サンドボックス実行の本番環境	高（分離されたサンドボックス）

LOGIC_FUNCTION_TYPE=DISABLED または CODE_INTERPRETER_TYPE=DISABLED を使用している場合、実行しようとするとエラーが返されます。 これは、これらの機能なしで Twenty を実行したい場合に便利です。

​

API とフロントエンドが別ホスト上にある場合

バックエンドにフロントエンドを配信させない場合にのみ関連します。 同一オリジンでのデプロイの場合、ここで設定する必要はありません。

API と通信するすべてのブラウザーオリジンを、カンマ区切りで指定してください。 SERVER_URL および FRONTEND_URL は既に信頼済みです。 ブラウザーが宣言されていないオリジンからサーバーを呼び出すと、サーバーは警告をログに記録します。

AUTH_COOKIE_ALLOWED_ORIGINS=https://app.example.com

フロントエンドはすべてのリクエストでクレデンシャルを送信し、ブラウザーは宣言されていないオリジンからのクレデンシャル付きレスポンスを拒否するため、この設定を行うまでアプリは読み込めません。

2 つのホストが異なる登録可能ドメイン（単なる異なるサブドメインではない）の場合は、AUTH_COOKIE_SAME_SITE=none も設定してください。これは HTTPS を必須とします。

マルチワークスペースが有効な場合、ここにすべてのワークスペースのサブドメインを列挙しないでください。 代わりに、各ワークスペースのホスト名ごとに API パス（/graphql、/metadata、/rest、/auth/、/client-config、/file）をバックエンドにルーティングし、すべてのワークスペースが同一オリジンを維持するようにします。Twenty Cloud はこの方式で稼働しています。