구성 관리

처음 설치하시나요? 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), 비밀 값(ENCRYPTION_KEY, FALLBACK_ENCRYPTION_KEY)과 같은 일부 인프라 설정은 .env 파일을 통해서만 구성할 수 있습니다.완전한 기술적 참조 →

암호화 키

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를 회전하는 방법은 키 회전 가이드를 참고하세요.

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”를 사용하세요.

워크플로우 작업을 사용하여 캘린더 이벤트를 생성하려면 “Calendars.ReadWrite”가 필수입니다. 캘린더 이벤트만 동기화하려면 “Calendars.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 설정을 구성하세요:

Gmail
오피스365
smtp4dev

App Password를 프로비저닝해야 합니다.

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’

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

프런트엔드는 모든 요청에 자격 증명을 함께 보내고, 브라우저는 선언되지 않은 오리진에서 오는 자격 증명 포함 응답을 거부하므로, 이 값을 설정하기 전까지 앱이 로드되지 않습니다.

두 호스트가 서로 다른 등록 가능한 도메인(단순히 서로 다른 서브도메인이 아닌 경우)에 있다면, AUTH_COOKIE_SAME_SITE=none도 설정해야 하며, 이때는 HTTPS가 필요합니다. 멀티 워크스페이스가 활성화된 경우, 여기에는 모든 워크스페이스 서브도메인을 나열하지 마세요. 대신, 각 워크스페이스 호스트 이름에서 API 경로(/graphql, /metadata, /rest, /auth/, /client-config, /file)를 백엔드로 라우팅하여 모든 워크스페이스가 동일 오리진을 유지하도록 하세요. Twenty Cloud는 이렇게 동작합니다.

개요

앱

API

셀프 호스팅

기여

설정

구성 관리

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

암호화 키

2. 환경 전용 구성

멀티 워크스페이스 모드

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

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

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

워크스페이스 생성 제한

Gmail & Google 캘린더 통합

Google 클라우드 프로젝트 생성

OAuth 구성

Twenty에서 구성하기

앱이 테스트 모드인 경우

Microsoft 365 통합

Microsoft Azure에 프로젝트 생성

API 활성화

인가된 리디렉션 URI

Twenty에서 구성하기

범위 구성

앱이 테스트 모드인 경우

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

이메일 구성

S3 저장소

로직 함수 및 코드 인터프리터

보안 기본값

로직 함수 - 사용 가능한 드라이버

로직 함수 - 권장 구성

코드 인터프리터 - 사용 가능한 드라이버

별도 호스트에서 동작하는 API와 프런트엔드

​구성 관리

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

​암호화 키

​2. 환경 전용 구성

​멀티 워크스페이스 모드

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

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

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

​워크스페이스 생성 제한

​Gmail & Google 캘린더 통합

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

​OAuth 구성

​Twenty에서 구성하기

​앱이 테스트 모드인 경우

​Microsoft 365 통합

​Microsoft Azure에 프로젝트 생성

​API 활성화

​인가된 리디렉션 URI

​Twenty에서 구성하기

​범위 구성

​앱이 테스트 모드인 경우

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

​이메일 구성

​S3 저장소

​로직 함수 및 코드 인터프리터

​보안 기본값

​로직 함수 - 사용 가능한 드라이버

​로직 함수 - 권장 구성

​코드 인터프리터 - 사용 가능한 드라이버

​별도 호스트에서 동작하는 API와 프런트엔드

구성 관리

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

암호화 키

2. 환경 전용 구성

멀티 워크스페이스 모드

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

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

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

워크스페이스 생성 제한

Gmail & Google 캘린더 통합

Google 클라우드 프로젝트 생성

OAuth 구성

Twenty에서 구성하기

앱이 테스트 모드인 경우

Microsoft 365 통합

Microsoft Azure에 프로젝트 생성

API 활성화

인가된 리디렉션 URI

Twenty에서 구성하기

범위 구성

앱이 테스트 모드인 경우

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

이메일 구성

S3 저장소

로직 함수 및 코드 인터프리터

보안 기본값

로직 함수 - 사용 가능한 드라이버

로직 함수 - 권장 구성

코드 인터프리터 - 사용 가능한 드라이버

별도 호스트에서 동작하는 API와 프런트엔드