> ## Documentation Index > Fetch the complete documentation index at: https://docs.twenty.com/llms.txt > Use this file to discover all available pages before exploring further. # 설정 # 구성 관리 **처음 설치하시나요?** [Docker Compose 설치 가이드](/l/ko/developers/self-host/capabilities/docker-compose)를 따라 Twenty를 실행하고, 이곳으로 돌아와 구성을 진행하세요. Twenty는 다른 배포 요구에 맞추기 위해 **두 가지 구성 모드**를 제공합니다: **관리자 패널 접근:** 관리자 권한이 있는 사용자만 (`canAccessFullAdminPanel: true`) 구성 인터페이스에 접근할 수 있습니다. ## 1. 관리자 패널 구성 (기본값) ```bash theme={null} 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` 파일을 통해서만 구성할 수 있습니다. [완전한 기술적 참조 →](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts) ## 암호화 키 Twenty는 환경 변수로만 설정할 수 있는 암호화 키를 두 개 사용합니다: | 변수 | 목적 | 필수 | | ------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------- | | `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/ko/developers/self-host/capabilities/key-rotation)를 참고하세요. ## 2. 환경 전용 구성 ```bash theme={null} IS_CONFIG_VARIABLES_IN_DB_ENABLED=false ``` **모든 구성이 `.env` 파일을 통해 관리됩니다:** 1. `.env` 파일에서 `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`로 설정하세요 2. 모든 구성 변수를 `.env` 파일에 추가하세요 3. 변경 사항이 적용되도록 컨테이너를 재시작하세요 4. 관리자 패널에서는 현재 값을 표시하며 수정할 수 없습니다 ## 멀티 워크스페이스 모드 기본적으로 Twenty는 **단일 워크스페이스 모드**로 실행됩니다 — 조직에 하나의 CRM 인스턴스가 필요한 대부분의 자가 호스팅 배포에 적합합니다. ### 단일 워크스페이스 모드(기본값) ```bash theme={null} IS_MULTIWORKSPACE_ENABLED=false # default ``` * Twenty 인스턴스당 하나의 워크스페이스 * 첫 번째 사용자는 자동으로 전체 권한(`canImpersonate` 및 `canAccessFullAdminPanel`)을 가진 관리자가 됩니다 * 첫 번째 워크스페이스가 생성된 후에는 신규 가입이 비활성화됩니다 * 간단한 URL 구조: `https://your-domain.com` ### 멀티 워크스페이스 모드 활성화 ```bash theme={null} 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 구성 없이 새 워크스페이스에 대한 서브도메인 라우팅이 자동으로 활성화됩니다. ### 워크스페이스 생성 제한 멀티 워크스페이스 모드에서, 누가 새 워크스페이스를 생성할 수 있는지 제한하고 싶을 수 있습니다: ```bash theme={null} IS_WORKSPACE_CREATION_LIMITED_TO_SERVER_ADMINS=true ``` 활성화되면 `canAccessFullAdminPanel` 권한이 있는 사용자만 추가 워크스페이스를 생성할 수 있습니다. 사용자는 초기 가입 과정에서 첫 번째 워크스페이스를 여전히 생성할 수 있습니다. ## Gmail & Google 캘린더 통합 ### Google 클라우드 프로젝트 생성 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 인증** 섹션을 찾으세요 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://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 통합 사용자는 캘린더 및 메시징 API를 사용하려면 [Microsoft 365 라이선스](https://admin.microsoft.com/Adminportal/Home)를 보유해야 합니다. 없이는 Twenty에서 계정을 동기화할 수 없습니다. ### 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 참고: "Mail.ReadWrite"와 "Mail.Send"는 워크플로우 작업을 통해 이메일을 보내려면 필수입니다. 수신 이메일만 원하시면 "Mail.Read"를 사용하실 수 있습니다. ### 인가된 리디렉션 URI 프로젝트에 다음 리디렉션 URI를 추가해야 합니다: * Microsoft SSO를 사용하려면 `https://{your-domain}/auth/microsoft/redirect` * `https://{your-domain}/auth/microsoft-apis/get-access-token` ### Twenty에서 구성하기 1. **설정 → 관리자 패널 → 구성 변수**로 이동하세요 2. **Microsoft 인증** 섹션을 찾으세요 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` 파일에 이러한 변수를 추가하세요. ### 범위 구성 [관련 소스 코드 보기](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 theme={null} # 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 설정을 구성하세요: [App Password](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' 2단계 인증을 사용 중인 경우, [앱 비밀번호](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' **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 **환경 전용 모드:** `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 참조](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**입니다. **보안 공지:** 로컬 드라이버 (`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` | 신뢰할 수 없는 코드를 처리하는 프로덕션 환경 | 높음 (하드웨어 수준 격리) | ### 로직 함수 - 권장 구성 **개발:** ```bash theme={null} LOGIC_FUNCTION_TYPE=LOCAL # default when NODE_ENV=development ``` **프로덕션(AWS):** ```bash theme={null} 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 theme={null} 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를 실행하려는 경우 유용합니다.