프로덕션 배포

이 가이드는 두 가지 프로덕션 경로를 다룹니다. 글로벌 npm 패키지를 자체 PostgreSQL과 Redis에 연결해 실행하는 방법, 그리고 저장소의 설치 프로그램으로 함께 제공되는 AWS 스택을 프로비저닝하는 방법입니다. 단일 머신에서 시험해 보려면 시작하기를 따르고, 컨테이너 배포는 Docker로 배포를 참고하세요. 부트스트랩 인증 정보, 싱글 사인온, 안전한 업그레이드는 셀프 호스팅 Chorus 운영하기에서 다룹니다.

외부 PostgreSQL에 연결해 글로벌 패키지 실행하기

웹 애플리케이션을 실행할 호스트에 Chorus 명령을 글로벌로 설치합니다.

npm install --global @chorus-aidlc/chorus

DATABASE_URL로 Chorus가 기존 PostgreSQL 데이터베이스를 사용하도록 지정하고, 필요한 인증 및 비밀 변수를 설정한 다음 시작합니다.

DATABASE_URL='postgresql://chorus:password@db.internal:5432/chorus' \
NEXTAUTH_SECRET="${NEXTAUTH_SECRET:?Set a persistent random secret first}" \
SUPER_ADMIN_EMAIL='admin@example.com' \
SUPER_ADMIN_PASSWORD_HASH='$2b$10$...' \
chorus

시작 시 Chorus는 보류 중인 데이터베이스 마이그레이션을 자동으로 적용하고(prisma migrate deploy), 그런 다음 웹 애플리케이션을 8637 포트에서 제공합니다. 데이터베이스는 미리 만들어져 있고 접속할 수 있어야 합니다. 이 경로에서는 Chorus가 데이터베이스를 만들어 주지 않습니다.

프로덕션 실행에서 Chorus가 읽는 변수는 다음과 같습니다.

변수	필수	설명
`DATABASE_URL`	예	PostgreSQL 연결 문자열, `postgresql://user:password@host:port/dbname`.
`NEXTAUTH_SECRET`	여러 인스턴스에서 필수	모든 레플리카가 공유하는 서명 비밀 키. 단일 npm 인스턴스에서는 생략할 수 있으며, 이 경우 `chorus`가 기본적으로 `~/.chorus-data/.secret`에 키를 생성해 저장합니다. 환경 변수에 알려진 자리 표시자가 있으면 경고를 남기고 무시합니다. 저장된 키가 비어 있거나 공개 자리 표시자이면 시작을 중단합니다.
`SUPER_ADMIN_EMAIL`	예	`/admin` 슈퍼 관리자 패널을 부트스트랩하는 이메일.
`SUPER_ADMIN_PASSWORD_HASH`	예	슈퍼 관리자 비밀번호의 bcrypt 해시.
`DEFAULT_USER`	선택	선택적인 기존 Default Auth 이메일. `DEFAULT_PASSWORD`도 필요합니다. 필요한 사용자와 워크스페이스를 만들지만 관리형 로컬 계정이나 로컬 관리자 역할은 아닙니다.
`DEFAULT_PASSWORD`	선택	내장 로그인의 비밀번호.
`REDIS_URL`	선택	SSE와 인증 카운터용 공유 Redis. 다중 인스턴스 일관성에 필요하며 `REDIS_HOST`와 개별 Redis 변수로도 설정할 수 있습니다.

이 부트스트랩 인증 정보의 작동 방식, bcrypt 해시 생성 방법, 그리고 내장 로그인을 끄는 방법은 셀프 호스팅 Chorus 운영하기를 참고하세요.

인스턴스를 두 개 이상 실행하기

Chorus는 Redis를 통해 인스턴스 간에 실시간 업데이트(SSE 이벤트 스트림)를 전파합니다. REDIS_URL을 공유 Redis로 설정해 모든 인스턴스가 같은 이벤트를 게시하고 수신하도록 하세요.

REDIS_URL='redis://default:password@redis.internal:6379'

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

AUTH_TRUST_PROXY는 기본적으로 꺼져 있으며 정확히 true일 때만 켜집니다. AUTH_TRUST_PROXY_HOPS는 기본 1, 범위는 1~16의 정수이며 X-Forwarded-For 오른쪽부터 셉니다. 강제 적용되고 우회할 수 없는 프록시 체인만 신뢰하세요. HTTPS만으로는 충분하지 않습니다. 번들 CDK의 ALB 모드는 true / 1, CloudFront 모드는 false / 2입니다. VPC 트래픽이 CloudFront를 우회하여 비공개 오리진에 도달할 수 있기 때문입니다.

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

또한 모든 인스턴스에 같은 안전한 NEXTAUTH_SECRET을 설정해, 어느 인스턴스가 요청을 받더라도 Chorus가 서명한 세션이 유효하도록 하세요.

AWS CDK 스택 배포하기

Chorus에는 packages/chorus-cdk 아래의 AWS CDK 스택과, 이 스택을 대화형으로 배포하는 저장소 루트의 install.sh가 포함되어 있습니다. 이 스택은 관리형 PostgreSQL과 Redis를 갖추고 HTTPS로 접근하는 완전한 배포를 구축합니다.

전제 조건

install.sh는 aws, node, pnpm과 유효한 AWS 인증 정보가 있는지 확인합니다. 먼저 aws configure 또는 AWS_PROFILE을 설정하세요. 인증서 요구 사항은 아래 모드에 따라 다릅니다.

배포 모드 선택

alb(기본값): 공개 ALB의 HTTPS 포트 443을 사용합니다. 배포 리전의 ACM 인증서는 필수이며 커스텀 도메인은 선택 사항입니다.
cloudfront: CloudFront가 공개 HTTPS를 제공하고 VPC origin을 통해 프라이빗 ALB의 HTTP 포트 80으로 전달합니다. 기본 *.cloudfront.net 도메인은 인증서를 준비할 필요가 없습니다. 커스텀 도메인에는 도메인과 us-east-1 ACM 인증서를 함께 제공하세요. 캐시는 비활성화되어 인증된 페이지와 API 응답을 캐시하지 않습니다.

./install.sh에서 선택하거나 CDK에 -c deployMode=cloudfront를 전달하세요. 선택한 모드는 default_deploy.sh에도 저장됩니다. 비대화형 설치에는 CHORUS_INSTALL_NONINTERACTIVE=1, DEPLOY_MODE=alb|cloudfront와 그 밖의 필수 설치 변수를 사용합니다. 어느 모드도 DNS 레코드를 만들지 않으므로, 커스텀 도메인이 AlbDnsName 또는 CloudFrontDomainName 스택 출력을 가리키도록 설정하고 OIDC 콜백 URL도 갱신하세요.

설치 프로그램 실행하기

저장소 루트에서:

./install.sh

설치 프로그램은 배포 구성을 묻습니다.

프롬프트	필수	참고
Deployment mode	아니요	`alb`(기본값) 또는 `cloudfront`.
Stack name	아니요	기본값 `Chorus`.
ACM Certificate ARN	모드에 따라 다름	`alb`는 배포 리전의 인증서가 필수. `cloudfront`는 커스텀 도메인을 사용할 때만 `us-east-1` 인증서가 필수.
Custom domain	아니요	`cloudfront`에서는 `us-east-1` 인증서와 함께 제공. 생략하면 CloudFront 배포(distribution) 도메인을 사용.
Super admin email	예	`/admin` 슈퍼 관리자 계정을 부트스트랩합니다.
Super admin password	예	최소 8자. synth 시점에 bcrypt로 해시되며, 평문은 템플릿에 저장되지 않습니다.
NextAuth secret	아니요	비워 두면 synth마다 생성됩니다. 재배포 후에도 세션을 유지하려면 같은 영구 값을 제공하세요.

스택은 Secrets Manager로 NEXTAUTH_SECRET을 공유하지만 synth 시 기존 값을 다시 읽지 않습니다. 배포할 때마다 설치 프로그램이나 CDK의 nextAuthSecret context에 같은 값을 사용하세요. 이전에 비워 두었다면 재배포하기 전에 Secrets Manager에 있는 기존 값을 그대로 유지해 키가 교체되지 않도록 하세요.

답변을 모두 받으면 install.sh는 CDK 패키지를 설치·빌드하고, CDK 환경을 부트스트랩한 뒤 스택을 배포합니다. 또한 답변을 담아 다시 실행할 수 있는 default_deploy.sh를 작성하므로, 이후 배포에서는 다시 묻지 않습니다.

스택이 프로비저닝하는 것

이 스택은 다음을 만듭니다.

구성 요소	무엇인가	주요 구성
Application Load Balancer	`alb`는 공개 HTTPS:443, `cloudfront`는 프라이빗 HTTP:80 오리진.	ECS로 전달. 유휴 타임아웃 60분.
CloudFront	`cloudfront` 모드에서만 생성되는 공개 HTTPS 진입점.	프라이빗 VPC origin, 캐시 비활성화, 선택적 커스텀 도메인.
ECS Fargate 서비스	프라이빗 서브넷에서 Chorus 컨테이너를 실행합니다.	희망 태스크 수 2, 1024 CPU 단위 / 2048 MiB, 자동 롤백을 갖춘 배포 서킷 브레이커.
Aurora Serverless v2(PostgreSQL)	관리형 PostgreSQL 클러스터.	암호화 스토리지. 인증 정보는 자동 생성되어 Secrets Manager에 저장. 백업 보존 1일.
ElastiCache Serverless(Redis)	인스턴스 간 이벤트와 공유 인증 카운터를 위한 관리형 Redis.	RBAC 사용자. 비밀번호는 Secrets Manager에 저장.
Secrets Manager	생성된 데이터베이스와 Redis 인증 정보, 그리고 앱 비밀 정보를 보관합니다.	런타임에 ECS 작업에 주입됩니다.

배포, 업데이트, 파기

작업	명령
첫 배포	`./install.sh`
재배포 또는 업데이트	`./default_deploy.sh`(또는 `pnpm cdk:deploy`)
파기	`pnpm cdk:destroy`

이 스택의 기준이 되는 원본은 packages/chorus-cdk입니다. 정확한 리소스 정의가 필요하거나 용량, 보존, 네트워킹을 조정하고 싶을 때는 그곳을 참고하세요.