구성 관리

처음 설치하시나요? Docker Compose 설치 가이드를 따라 Twenty를 실행하고, 이곳으로 돌아와 구성을 진행하세요.

Twenty는 다른 배포 요구에 맞추기 위해 두 가지 구성 모드를 제공합니다: 관리자 패널 접근: 관리자 권한이 있는 사용자만 (canAccessFullAdminPanel: true) 구성 인터페이스에 접근할 수 있습니다.

1. 관리자 패널 구성 (기본값)

IS_CONFIG_VARIABLES_IN_DB_ENABLED=true  # default

설치 후 대부분의 구성은 UI를 통해 이루어집니다:

Twenty 인스턴스에 접근하십시오 (보통 http://localhost:3000)
설정 / 관리자 패널 / 구성 변수로 이동하세요
통합, 이메일, 저장소 등을 구성하세요
변경 사항은 즉시 적용됩니다 (멀티 컨테이너 배포의 경우 15초 이내)

멀티 컨테이너 배포: 데이터베이스 구성을 사용할 때 (IS_CONFIG_VARIABLES_IN_DB_ENABLED=true), 서버와 작업자 컨테이너 모두 동일한 데이터베이스에서 읽습니다. 관리자 패널의 변경은 둘 다 자동으로 영향을 미쳐 환경 변수를 컨테이너 간에 복제할 필요가 없습니다 (인프라 변수 제외).

관리자 패널에서 구성할 수 있는 내용:

인증 - Google/Microsoft OAuth, 비밀번호 설정
이메일 - SMTP 설정, 템플릿, 확인
저장소 - S3 구성, 로컬 저장 경로
통합 - Gmail, Google 캘린더, Microsoft 서비스
워크플로우 및 속도 제한 - 실행 제한, API 스로틀링
그리고 훨씬 더…

각 변수는 설정 → 관리자 패널 → 구성 변수의 관리자 패널에 설명과 함께 문서화되어 있습니다. 데이터베이스 연결 (PG_DATABASE_URL), 서버 URL (SERVER_URL), 앱 비밀 (APP_SECRET)과 같은 일부 인프라 설정은 .env 파일을 통해서만 구성할 수 있습니다.완전한 기술적 참조 →

2. 환경 전용 구성

IS_CONFIG_VARIABLES_IN_DB_ENABLED=false

모든 구성이 .env 파일을 통해 관리됩니다:

.env 파일에서 IS_CONFIG_VARIABLES_IN_DB_ENABLED=false로 설정하세요
모든 구성 변수를 .env 파일에 추가하세요
변경 사항이 적용되도록 컨테이너를 재시작하세요
관리자 패널에서는 현재 값을 표시하며 수정할 수 없습니다

멀티 워크스페이스 모드

기본적으로 Twenty는 단일 워크스페이스 모드로 실행됩니다 — 조직에 하나의 CRM 인스턴스가 필요한 대부분의 자가 호스팅 배포에 적합합니다.

단일 워크스페이스 모드(기본값)

IS_MULTIWORKSPACE_ENABLED=false  # default

Twenty 인스턴스당 하나의 워크스페이스
첫 번째 사용자는 자동으로 전체 권한(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 클라우드 프로젝트 생성

Google Cloud Console로 이동하세요
새 프로젝트를 생성하거나 기존 프로젝트를 선택하세요
이 API들을 활성화하세요:

OAuth 구성

자격 증명으로 이동하세요
OAuth 2.0 클라이언트 ID를 생성하세요
이러한 리디렉션 URI를 추가하세요:
- https://{your-domain}/auth/google/redirect (SSO용)
- https://{your-domain}/auth/google-apis/get-access-token (통합용)

Twenty에서 구성하기

설정 → 관리자 패널 → 구성 변수로 이동하세요
Google 인증 섹션을 찾으세요
다음 변수를 설정하세요:
- 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 라이선스를 보유해야 합니다. 없이는 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”를 사용하실 수 있습니다.

인가된 리디렉션 URI

프로젝트에 다음 리디렉션 URI를 추가해야 합니다:

Microsoft SSO를 사용하려면 https://{your-domain}/auth/microsoft/redirect
https://{your-domain}/auth/microsoft-apis/get-access-token

Twenty에서 구성하기

설정 → 관리자 패널 → 구성 변수로 이동하세요
Microsoft 인증 섹션을 찾으세요
다음 변수를 설정하세요:
- 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 파일에 이러한 변수를 추가하세요.

범위 구성

앱이 테스트 모드인 경우

앱이 테스트 모드인 경우, 프로젝트에 테스트 사용자를 추가해야 합니다. “사용자 및 그룹” 섹션에 테스트 사용자를 추가하세요.

캘린더 및 메시징을 위한 배경 작업

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

이메일 구성

설정 → 관리자 패널 → 구성 변수로 이동하세요
이메일 섹션을 찾으세요
SMTP 설정을 구성하세요:

환경 전용 모드: IS_CONFIG_VARIABLES_IN_DB_ENABLED=false로 설정한 경우, .env 파일에 이러한 변수를 추가하세요.

로직 함수

Twenty는 워크플로 및 사용자 지정 로직을 위해 로직 함수를 지원합니다. SERVERLESS_TYPE 환경 변수를 통해 실행 환경을 구성합니다.

보안 공지: 로컬 드라이버 (SERVERLESS_TYPE=LOCAL)는 샌드박싱 없이 호스트의 Node.js 프로세스에서 코드를 직접 실행합니다. 개발 환경에서 신뢰할 수 있는 코드에만 사용해야 합니다. 신뢰할 수 없는 코드를 처리하는 프로덕션 배포의 경우 SERVERLESS_TYPE=LAMBDA 또는 SERVERLESS_TYPE=DISABLED 사용을 강력히 권장합니다.

사용 가능한 드라이버

드라이버	환경 변수	사용 사례	보안 수준
비활성화	`SERVERLESS_TYPE=DISABLED`	로직 함수를 완전히 비활성화	해당 없음
로컬	`SERVERLESS_TYPE=LOCAL`	개발 및 신뢰할 수 있는 환경	낮음 (샌드박싱 없음)
Lambda	`SERVERLESS_TYPE=LAMBDA`	신뢰할 수 없는 코드를 처리하는 프로덕션 환경	높음 (하드웨어 수준 격리)

권장 구성

개발:

SERVERLESS_TYPE=LOCAL  # default

프로덕션(AWS):

SERVERLESS_TYPE=LAMBDA
SERVERLESS_LAMBDA_REGION=us-east-1
SERVERLESS_LAMBDA_ROLE=arn:aws:iam::123456789:role/your-lambda-role
SERVERLESS_LAMBDA_ACCESS_KEY_ID=your-access-key
SERVERLESS_LAMBDA_SECRET_ACCESS_KEY=your-secret-key

로직 함수를 비활성화하려면:

SERVERLESS_TYPE=DISABLED

SERVERLESS_TYPE=DISABLED를 사용하는 경우 로직 함수를 실행하려는 모든 시도는 오류를 반환합니다. 로직 함수 기능 없이 Twenty를 실행하려는 경우 유용합니다.

개발자

확장

셀프 호스팅

기여

설정

구성 관리

1. 관리자 패널 구성 (기본값)

2. 환경 전용 구성

멀티 워크스페이스 모드

단일 워크스페이스 모드(기본값)

멀티 워크스페이스 모드 활성화

멀티 워크스페이스를 위한 DNS 구성

워크스페이스 생성 제한

Gmail & Google 캘린더 통합

Google 클라우드 프로젝트 생성

OAuth 구성

Twenty에서 구성하기

앱이 테스트 모드인 경우

Microsoft 365 통합

Microsoft Azure에 프로젝트 생성

API 활성화

인가된 리디렉션 URI

Twenty에서 구성하기

범위 구성

앱이 테스트 모드인 경우

캘린더 및 메시징을 위한 배경 작업

이메일 구성

로직 함수

사용 가능한 드라이버

권장 구성

개발자

확장

셀프 호스팅

기여

​구성 관리

​1. 관리자 패널 구성 (기본값)

​2. 환경 전용 구성

​멀티 워크스페이스 모드

​단일 워크스페이스 모드(기본값)

​멀티 워크스페이스 모드 활성화

​멀티 워크스페이스를 위한 DNS 구성

​워크스페이스 생성 제한

​Gmail & Google 캘린더 통합

​Google 클라우드 프로젝트 생성

​OAuth 구성

​Twenty에서 구성하기

​앱이 테스트 모드인 경우

​Microsoft 365 통합

​Microsoft Azure에 프로젝트 생성

​API 활성화

​인가된 리디렉션 URI

​Twenty에서 구성하기

​범위 구성

​앱이 테스트 모드인 경우

​캘린더 및 메시징을 위한 배경 작업

​이메일 구성

​로직 함수

​사용 가능한 드라이버

​권장 구성

구성 관리

1. 관리자 패널 구성 (기본값)

2. 환경 전용 구성

멀티 워크스페이스 모드

단일 워크스페이스 모드(기본값)

멀티 워크스페이스 모드 활성화

멀티 워크스페이스를 위한 DNS 구성

워크스페이스 생성 제한

Gmail & Google 캘린더 통합

Google 클라우드 프로젝트 생성

OAuth 구성

Twenty에서 구성하기

앱이 테스트 모드인 경우

Microsoft 365 통합

Microsoft Azure에 프로젝트 생성

API 활성화

인가된 리디렉션 URI

Twenty에서 구성하기

범위 구성

앱이 테스트 모드인 경우

캘린더 및 메시징을 위한 배경 작업

이메일 구성

로직 함수

사용 가능한 드라이버

권장 구성