github-actions[bot]
1d367bbc57
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
408 lines
21 KiB
Plaintext
408 lines
21 KiB
Plaintext
---
|
||
title: セットアップ
|
||
icon: gear
|
||
---
|
||
|
||
# 構成管理
|
||
|
||
<Warning>
|
||
**初めてインストールしますか？** [Docker Compose インストールガイド](/l/ja/developers/self-host/capabilities/docker-compose)に従ってTwentyを起動し、その後はここに戻り構成してください。
|
||
</Warning>
|
||
|
||
Twentyは、異なる展開ニーズに合わせて**2つの構成モード**を提供します:
|
||
|
||
**管理パネルアクセス:** 管理者権限を持つユーザーだけが (`canAccessFullAdminPanel: true`) 構成インターフェースにアクセスできます。
|
||
|
||
## 1. 管理パネル構成（デフォルト）
|
||
|
||
```bash
|
||
IS_CONFIG_VARIABLES_IN_DB_ENABLED=true # default
|
||
```
|
||
|
||
**ほとんどの構成は、インストール後にUIを通じて行われます。**
|
||
|
||
1. Twentyインスタンスにアクセスしてください (通常は `http://localhost:3000`)
|
||
2. **設定 / 管理パネル / 構成変数**に移動
|
||
3. 統合、メール、ストレージなどを構成します
|
||
4. 変更はすぐに（マルチコンテナ展開の場合、15秒以内に）効果が出ます。
|
||
|
||
<Warning>
|
||
**マルチコンテナ展開:** データベース構成を使用する場合 (`IS_CONFIG_VARIABLES_IN_DB_ENABLED=true`)、サーバーとワーカーコンテナの両方が同じデータベースから読み込みます。 管理パネルの変更は両方に自動的に影響し、コンテナ間で環境変数を重複させる必要がなくなります（インフラストラクチャの変数を除く）。
|
||
管理パネルの変更は両方に自動的に影響し、コンテナ間で環境変数を重複させる必要がなくなります（インフラストラクチャの変数を除く）。
|
||
</Warning>
|
||
|
||
**管理パネルを通じて構成できること:**
|
||
|
||
* **認証** - Google/Microsoft OAuth、パスワード設定
|
||
* **メール** - SMTP設定、テンプレート、検証
|
||
* **ストレージ** - S3構成、ローカルストレージパス
|
||
* **統合** - Gmail、Googleカレンダー、Microsoftサービス
|
||
* **ワークフローとレート制限** - 実行制限、APIスロットリング
|
||
* **さらに多くのこと...**
|
||
|
||
|
||
|
||
<Warning>
|
||
各変数は、**設定 → 管理パネル → 構成変数** で説明付きでドキュメント化されています。
|
||
データベース接続 (`PG_DATABASE_URL`)、サーバーURL (`SERVER_URL`)、秘密情報 (`ENCRYPTION_KEY`, `FALLBACK_ENCRYPTION_KEY`) など、一部のインフラ設定は `.env` ファイルを介してのみ構成できます。
|
||
|
||
[ 完全な技術リファレンス →](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts)
|
||
</Warning>
|
||
|
||
## 暗号鍵
|
||
|
||
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` をローテーションする方法については、[キー ローテーション ガイド](/l/ja/developers/self-host/capabilities/key-rotation) を参照してください。
|
||
|
||
## 2. 環境のみの構成
|
||
|
||
```bash
|
||
IS_CONFIG_VARIABLES_IN_DB_ENABLED=false
|
||
```
|
||
|
||
**すべての構成が `.env` ファイルで管理されます:**
|
||
|
||
1. `.env` ファイル内で `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false` を設定
|
||
2. すべての構成変数を `.env` ファイルに追加
|
||
3. 変更を有効にするためにコンテナを再起動してください
|
||
4. 管理パネルは現在の値を表示しますが、修正はできません
|
||
|
||
## マルチワークスペースモード
|
||
|
||
デフォルトでは、Twenty は**シングルワークスペースモード**で動作します—組織向けに 1 つの CRM インスタンスが必要な多くのセルフホスト型デプロイメントに最適です。
|
||
|
||
### シングルワークスペースモード（デフォルト）
|
||
|
||
```bash
|
||
IS_MULTIWORKSPACE_ENABLED=false # default
|
||
```
|
||
|
||
* Twenty の各インスタンスにつき 1 つのワークスペース
|
||
* 最初のユーザーは自動的にフル権限の管理者になります（`canImpersonate` と `canAccessFullAdminPanel`）
|
||
* 最初のワークスペース作成後は新規サインアップが無効になります
|
||
* シンプルな URL 構造: `https://your-domain.com`
|
||
|
||
### マルチワークスペースモードの有効化
|
||
|
||
```bash
|
||
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`）
|
||
* 管理者権限は自動付与されません—各ワークスペースの最初のユーザーは一般ユーザーです
|
||
* サブドメインやカスタムドメインなどのワークスペース固有の設定がワークスペース設定で利用可能になります
|
||
|
||
<Warning>
|
||
**環境専用の設定:** `IS_MULTIWORKSPACE_ENABLED` は `.env` ファイルでのみ設定でき、再起動が必要です。 管理パネルからは変更できません。
|
||
</Warning>
|
||
|
||
### マルチワークスペース向けの DNS 構成
|
||
|
||
マルチワークスペースモードを使用する場合、動的なサブドメイン作成を可能にするために、ワイルドカードレコードで DNS を構成してください:
|
||
|
||
```
|
||
*.your-domain.com -> your-server-ip
|
||
```
|
||
|
||
これにより、手動の DNS 構成なしで新規ワークスペースへのサブドメインルーティングが自動化されます。
|
||
|
||
### ワークスペース作成の制限
|
||
|
||
マルチワークスペースモードでは、新しいワークスペースを作成できるユーザーを制限したい場合があります:
|
||
|
||
```bash
|
||
IS_WORKSPACE_CREATION_LIMITED_TO_SERVER_ADMINS=true
|
||
```
|
||
|
||
有効にすると、`canAccessFullAdminPanel` を持つユーザーのみが追加のワークスペースを作成できます。 初回サインアップ時には、ユーザーは引き続き最初のワークスペースを作成できます。
|
||
|
||
## Gmail & Googleカレンダー統合
|
||
|
||
### Google Cloudプロジェクトを作成
|
||
|
||
1. [Google Cloud Console](https://console.cloud.google.com/) にアクセス
|
||
2. 新しいプロジェクトを作成するか既存のプロジェクトを選択
|
||
3. 以下のAPIを有効にします:
|
||
|
||
* [Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com)
|
||
* [GoogleカレンダーAPI](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com)
|
||
* [People API](https://console.cloud.google.com/apis/library/people.googleapis.com)
|
||
|
||
### OAuthの構成
|
||
|
||
1. [資格情報](https://console.cloud.google.com/apis/credentials)にアクセス
|
||
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`
|
||
|
||
<Warning>
|
||
**環境専用モード:** `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false` を設定した場合、これらの変数を `.env` ファイルに追加してください。
|
||
</Warning>
|
||
|
||
**必要なスコープ** (自動的に構成される):
|
||
[関連ソースコードを見る](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`
|
||
|
||
### アプリがテストモードの場合
|
||
|
||
アプリがテストモードの場合、プロジェクトにテストユーザーを追加する必要があります。
|
||
|
||
[OAuth 同意画面](https://console.cloud.google.com/apis/credentials/consent)で、「テストユーザー」セクションにテストユーザーを追加してください。
|
||
|
||
## Microsoft 365 統合
|
||
|
||
<Warning>
|
||
カレンダーおよびメッセージングAPIを使用するためには、[Microsoft 365 ライセンス](https://admin.microsoft.com/Adminportal/Home)が必要です。 They will not be able to sync their account on Twenty without one. それがない場合、Twenty でアカウントを同期できません。
|
||
</Warning>
|
||
|
||
### Microsoft Azureでプロジェクトを作成
|
||
|
||
[Microsoft Azure](https://portal.azure.com/#view/Microsoft_AAD_IAM/AppGalleryBladeV2)でプロジェクトを作成し、資格情報を取得してください。
|
||
|
||
### 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
|
||
|
||
<Note>
|
||
"Mail.ReadWrite" と "Mail.Send" は、ワークフローアクションを使用してメールを送信する場合にのみ必須です。 メールを受信するだけの場合は、"Mail.Read"を使用できます。
|
||
</Note>
|
||
|
||
<Note>
|
||
ワークフローアクションを使用してカレンダーイベントを作成する場合は、"Calendars.ReadWrite" が必須です。 カレンダーイベントを同期するだけの場合は、"Calendars.Read" を使用してください。
|
||
</Note>
|
||
|
||
### 認証されたリダイレクト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`
|
||
|
||
<Warning>
|
||
**環境専用モード:** `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false` を設定した場合、これらの変数を `.env` ファイルに追加してください。
|
||
</Warning>
|
||
|
||
### スコープを構成
|
||
|
||
[関連ソースコードを見る](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'
|
||
* 'メール'
|
||
* 'プロフィール'
|
||
* 'offline_access'
|
||
* 'Mail.ReadWrite'
|
||
* 'Mail.Send'
|
||
* 'Calendars.Read'
|
||
|
||
### アプリがテストモードの場合
|
||
|
||
アプリがテストモードの場合、プロジェクトにテストユーザーを追加する必要があります。
|
||
|
||
「ユーザーとグループ」セクションにテストユーザーを追加してください。
|
||
|
||
## カレンダーとメッセージングのバックグラウンドジョブ
|
||
|
||
Gmail、Googleカレンダー、またはMicrosoft 365統合を構成した後、データを同期するバックグラウンドジョブを開始する必要があります。
|
||
|
||
次の定期ジョブをワーカーコンテナに登録してください:
|
||
|
||
```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
|
||
```
|
||
|
||
## メール設定
|
||
|
||
1. **設定 → 管理パネル → 構成変数** に移動
|
||
2. **メール** セクションを見つけます
|
||
3. SMTP設定を構成:
|
||
|
||
<Tabs>
|
||
|
||
<Tab title="Gmail">
|
||
|
||
[アプリパスワード](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">
|
||
|
||
2FAを有効にしている場合、[アプリパスワード](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** は開発とテストのためのフェイクSMTPメールサーバーです。
|
||
* smtp4devイメージを実行: `docker run --rm -it -p 8090:80 -p 2525:25 rnwood/smtp4dev`
|
||
* smtp4dev UIにアクセス: [http://localhost:8090](http://localhost:8090)
|
||
* 次の変数を設定:
|
||
* EMAIL_DRIVER=smtp
|
||
* EMAIL_SMTP_HOST=localhost
|
||
* EMAIL_SMTP_PORT=2525
|
||
|
||
</Tab>
|
||
|
||
</Tabs>
|
||
|
||
<Warning>
|
||
**環境専用モード:** `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false` を設定した場合、これらの変数を `.env` ファイルに追加してください。
|
||
</Warning>
|
||
|
||
## S3 ストレージ
|
||
|
||
<Warning>
|
||
デフォルトでは、Twenty はアップロードされたファイルをローカルのファイルシステムに保存します。 本番環境へのデプロイでは、S3 または S3 互換のサービス（MinIO、DigitalOcean Spaces など）を使用してください。 コンテナの再起動をまたいでファイルを永続化し、複数のサーバーインスタンスにまたがってスケールできるようにするため。
|
||
</Warning>
|
||
|
||
`STORAGE_TYPE=S_3` を設定し、管理パネルまたは `.env` から `STORAGE_S3_*` 変数を設定してください。 S3 変数の全一覧については、[config-variables.ts リファレンス](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts) を参照してください。
|
||
|
||
CORS に依存する機能（例: ブラウザ内でのファイルダウンロード）で S3 を使用する場合は、バケットの CORS 設定で Twenty フロントエンドのオリジンが許可されていることを確認してください。
|
||
|
||
## ロジック関数とコードインタープリター
|
||
|
||
Twenty は、ワークフロー向けのロジック関数と、AI データ分析用のコードインタープリターをサポートします。 どちらもユーザー提供のコードを実行し、セキュリティのために明示的な設定が必要です。
|
||
|
||
### セキュリティのデフォルト
|
||
|
||
**本番環境 (NODE_ENV=production):** ロジック関数とコードインタープリターはいずれもデフォルトで**無効**です。 これらの機能が必要な場合は、`LOGIC_FUNCTION_TYPE` と `CODE_INTERPRETER_TYPE` で明示的に有効化する必要があります。
|
||
|
||
**開発環境 (NODE_ENV=development):** ローカルでの実行を容易にするため、どちらもデフォルトでは**LOCAL**です。
|
||
|
||
<Warning>
|
||
**セキュリティに関する注意:** ローカルドライバー (`LOGIC_FUNCTION_TYPE=LOCAL` または `CODE_INTERPRETER_TYPE=LOCAL`) は、ホスト上の Node.js プロセス内でサンドボックスなしにコードを直接実行します。 開発では、信頼できるコードにのみ使用してください。 信頼できないコードを扱う本番デプロイでは、`LOGIC_FUNCTION_TYPE=LAMBDA` または `CODE_INTERPRETER_TYPE=E2B`（サンドボックス化あり）を使用するか、無効のままにしてください。
|
||
</Warning>
|
||
|
||
### ロジック関数 - 利用可能なドライバー
|
||
|
||
| ドライバー | 環境変数 | ユースケース | セキュリティレベル |
|
||
| ------ | ------------------------------ | ---------------- | --------------- |
|
||
| 無効 | `LOGIC_FUNCTION_TYPE=DISABLED` | ロジック関数を完全に無効化する | 該当なし |
|
||
| ローカル | `LOGIC_FUNCTION_TYPE=LOCAL` | 開発および信頼できる環境 | 低（サンドボックスなし） |
|
||
| Lambda | `LOGIC_FUNCTION_TYPE=LAMBDA` | 信頼できないコードを扱う本番環境 | 高（ハードウェアレベルの分離） |
|
||
|
||
### ロジック関数 - 推奨構成
|
||
|
||
**開発向け:**
|
||
|
||
```bash
|
||
LOGIC_FUNCTION_TYPE=LOCAL # default when NODE_ENV=development
|
||
```
|
||
|
||
**本番向け（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
|
||
```
|
||
|
||
**ロジック関数を無効化するには:**
|
||
|
||
```bash
|
||
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` | サンドボックス実行の本番環境 | 高（分離されたサンドボックス） |
|
||
|
||
<Note>
|
||
`LOGIC_FUNCTION_TYPE=DISABLED` または `CODE_INTERPRETER_TYPE=DISABLED` を使用している場合、実行しようとするとエラーが返されます。 これは、これらの機能なしで Twenty を実行したい場合に便利です。
|
||
</Note>
|
||
|
||
## API とフロントエンドが別ホスト上にある場合
|
||
|
||
バックエンドにフロントエンドを配信させない場合にのみ関連します。 同一オリジンでのデプロイの場合、ここで設定する必要はありません。
|
||
|
||
API と通信するすべてのブラウザーオリジンを、カンマ区切りで指定してください。 `SERVER_URL`
|
||
および `FRONTEND_URL` は既に信頼済みです。
|
||
|
||
```bash
|
||
AUTH_COOKIE_ALLOWED_ORIGINS=https://app.example.com
|
||
```
|
||
|
||
<Warning>
|
||
Cookie セッションを使用するバージョンにアップグレードすると、これが必須になります。 フロントエンドは
|
||
すべてのリクエストでクレデンシャルを送信し、ブラウザーは宣言されていないオリジンからのクレデンシャル付きレスポンスを拒否するため、この設定を行うまでアプリは読み込めません。
|
||
</Warning>
|
||
|
||
2 つのホストが異なる登録可能ドメイン（単なる異なるサブドメインではない）の場合は、`AUTH_COOKIE_SAME_SITE=none` も設定してください。これは HTTPS を必須とします。
|