배포 개요

이 페이지는 Chorus를 실행하고 셀프 호스팅하는 지원되는 방법들을 소개하고, 각 방법에 필요한 것을 나열하며, 하나를 고르도록 돕습니다. 고르고 나면 Docker, 로컬 셀프 호스팅, 프로덕션 배포, 운영 가이드가 나머지 길을 안내합니다.

배포 형태

Chorus는 같은 애플리케이션을 로컬과 프로덕션, 두 가지 형태로 실행합니다. 차이는 데이터가 어디에 있는지, 몇 명이 사용하는지에 있습니다.

로컬 단일 머신

단일 사용자를 위한, 한 대의 머신 위의 한 프로세스입니다. Chorus는 내장 PostgreSQL 데이터베이스(PGlite)를 함께 제공하므로 따로 설치할 외부 구성 요소가 없습니다. 명령이 스스로 데이터베이스를 만들고, 마이그레이션을 적용하며, 웹 애플리케이션을 8637 포트에서 제공합니다. 이것은 Chorus를 가장 빠르게 시험해 보는 방법이며, 개인적인 로컬 사용에 알맞은 선택입니다.

이것은 시작하기 가이드가 처음부터 끝까지 안내하는 경로입니다. 글로벌 패키지를 설치하고, 관리자 계정을 설정하고, 로그인합니다. 이 페이지에서는 그 단계를 되풀이하지 않습니다.

로컬 형태는 Docker의 스탠드얼론 컨테이너로도 실행할 수 있습니다. 같은 내장 데이터베이스를 쓰며, 데이터는 Docker 볼륨에 보관됩니다. 스탠드얼론(내장 데이터베이스)를 참고하세요.

단일 호스트 셀프 호스팅

내 Linux 또는 macOS 호스트에서 상시 운영하는 인스턴스로, 내장 데이터베이스 대신 Docker Compose 안의 실제 PostgreSQL 17 데이터베이스를 사용합니다. Chorus 0.22.2 이상에서는 bash install.sh --target local로 설정합니다. 설치 프로그램이 앱 이미지를 받거나 빌드하고, 보호된 계정 설정을 작성하며, 반복 가능한 재배포용 래퍼를 저장합니다. 앱은 LAN에서 HTTP로 접근할 수 있고, 선택적으로 자체 서명 LAN HTTPS나 Cloudflare Named Tunnel을 쓸 수 있습니다. Redis 없는 단일 인스턴스 구성입니다. 로컬 머신에 셀프 호스팅을 참고하세요.

프로덕션

팀을 위한 공유 설치로, 직접 관리하고 백업하는 외부 PostgreSQL 데이터베이스가 뒷받침하며(저장소의 Compose 파일은 기본으로 PostgreSQL 17을 사용), 하나 이상의 애플리케이션 인스턴스가 서비스합니다. Redis 7은 단일 인스턴스에서는 선택 사항이지만, 두 개 이상을 실행할 때는 필수입니다. 인스턴스들이 Redis를 통해 서로 실시간 업데이트(Server-Sent Events)를 전파하기 때문입니다. Redis가 없으면 Chorus는 메모리 내 이벤트 방식으로 폴백하는데, 이는 단일 인스턴스에서만 동작합니다.

Redis는 별도의 연결로 인스턴스 간 SSE와 공유 인증 카운터를 지원합니다. 비어 있지 않은 REDIS_URL이 우선하며 그렇지 않으면 REDIS_HOST로 TLS(rediss)를 사용합니다. 포트 기본값은 6379, 사용자 이름은 default이며 사용자 이름은 REDIS_PASSWORD를 지정할 때 사용됩니다. 비 TLS에는 명시적인 redis://를 사용하세요. URL과 host가 모두 없을 때만 이벤트와 제한이 프로세스 내부에 한정됩니다. Redis 장애 시 프로세스별 보조 제한을 사용하므로 공유 한도를 유지하지 못하지만 모든 로그인을 차단하지도 않습니다. 예상치 못한 제한 오류는 허용할 수 있습니다. 정확한 한도와 복구 동작은 공유 인증 요청 제한을 참고하세요.

프로덕션 형태는 컨테이너로 실행하거나(Docker로 배포 참고), 글로벌 npm 패키지에서 자체 PostgreSQL과 Redis에 연결해 실행하거나, 함께 제공되는 AWS CDK 스택 위에서 실행할 수 있습니다(프로덕션 배포 참고).

계정 관리는 별도로 선택하기

관리형 로컬 계정은 데이터베이스에 저장하며 DEFAULT_USER / DEFAULT_PASSWORD로 설정하지 않습니다. 앱에 SUPER_ADMIN_EMAIL과 SUPER_ADMIN_PASSWORD_HASH를 주입한 뒤 관리 패널에서 로컬 계정 워크스페이스를 만들고 첫 워크스페이스 관리자를 초대하세요. ID 제공자나 메일 서비스는 필요하지 않습니다. 같은 워크스페이스에서 OIDC와 혼용하거나 기존 워크스페이스를 전환할 수 없습니다. NEXTAUTH_SECRET을 영구 보관하고 모든 레플리카에 공유하며 공유 접근에는 HTTPS와 COOKIE_SECURE=true를 사용하세요. 설정과 기존 Default Auth만 비활성화하는 방법은 운영 가이드를 참고하세요.

전제 조건

• Node.js 22 이상: Chorus는 Node.js 22 런타임을 대상으로 합니다(Docker 이미지는 node:22-alpine 위에 빌드됩니다).
• 8637 포트: 애플리케이션은 여기서 수신 대기합니다. UI와 MCP 엔드포인트에 도달하려면 이 포트를 공개하거나 리버스 프록시하세요.
• 데이터베이스: 로컬 형태에서는 준비할 것이 없습니다(내장 PGlite). 프로덕션에서는 연결 문자열로 도달할 수 있는 외부 PostgreSQL 데이터베이스가 필요합니다. 저장소의 Compose 파일과 셀프 호스팅 스택은 기본으로 PostgreSQL 17을 사용하며, 기존 PostgreSQL 16 데이터 볼륨은 전환하기 전에 마이그레이션해야 합니다(로컬 머신에 셀프 호스팅 참고).
• 캐시: 단일 인스턴스에서는 필요 없습니다. 다중 인스턴스 프로덕션 배포에서는 인스턴스 간 이벤트 전파를 위한 Redis 7 엔드포인트가 필요합니다.

선택하는 방법

하고 싶은 것	선택	데이터베이스	캐시
Chorus를 시험하거나 한 대의 머신에서 혼자 작업하기	로컬 단일 머신	내장 PGlite	없음
가장 적은 구성 요소로 공유 인스턴스 실행하기	스탠드얼론 컨테이너의 로컬 형태	내장 PGlite(볼륨에 저장)	없음
내 호스트에서 상시 운영하고 LAN에서 접근하기	단일 호스트 셀프 호스팅(install.sh --target local)	PostgreSQL 17(Compose 안)	없음
공유, 고가용성 또는 다중 인스턴스 설치 운영하기	프로덕션(Docker, npm 또는 AWS CDK)	외부 PostgreSQL(기본 17)	Redis 7(2개 이상 인스턴스에서 필수)

계속 읽기

• Docker로 배포: 공개된 chorusaidlc/chorus-app 이미지. 스탠드얼론과 프로덕션 Compose 파일, docker run 예시, 전체 환경 변수 참고, 그리고 시작 시 동작.
• 로컬 머신에 셀프 호스팅: install.sh 로컬 설정, 재배포 래퍼, 선택적 자체 서명 LAN HTTPS 또는 Cloudflare Tunnel, 그리고 PostgreSQL 16 → 17 마이그레이션.
• 프로덕션 배포: 자체 PostgreSQL과 Redis에 연결해 실행하기, 다중 인스턴스 요구 사항, 그리고 전체 AWS CDK 안내.
• 셀프 호스팅 Chorus 운영하기: 첫 로그인 부트스트랩, 배포 측 인증, 자동 마이그레이션, 그리고 업그레이드 전 백업.