셀프 호스팅 Chorus 운영하기

이 가이드는 배포를 마친 셀프 호스팅 Chorus의 운영을 다룹니다. 첫 사용자 로그인, 인증 구성, 안전한 업그레이드, 그리고 HTTPS 환경에서 중요한 쿠키와 리버스 프록시 설정을 설명합니다. 배포를 구축하는 방법은 프로덕션 배포 또는 Docker로 배포를 참고하세요.

첫 접근을 부트스트랩하기

새 배포에는 아직 계정이 없습니다. DEFAULT_USER와 DEFAULT_PASSWORD를 설정해 싱글 사인온을 우회하는 내장 이메일/비밀번호 로그인을 활성화합니다.

DEFAULT_USER='admin@example.com' \
DEFAULT_PASSWORD='choose-a-strong-password'

두 변수가 모두 설정되면 로그인 페이지에 이메일/비밀번호 폼이 나타납니다. 첫 로그인에 성공하면 Chorus가 그 이메일로 사용자와 해당 워크스페이스를 자동으로 생성하므로, 로그인하기 위해 따로 설정할 것이 없습니다.

내장 로그인 끄기

내장 로그인은 부트스트랩 메커니즘이지 영구적인 계정 시스템이 아닙니다. 실제 계정이 생기면(또는 싱글 사인온을 구성하면) DEFAULT_USER와 DEFAULT_PASSWORD를 모두 해제하고 Chorus를 재시작해 내장 로그인을 끄세요. 두 변수를 제거하면 내장 이메일/비밀번호 폼이 더 이상 나타나지 않고, 대신 구성한 ID 제공자를 통해 로그인합니다.

배포 측 인증 구성하기

배포 수준에서 구성되는 인증에는 두 종류가 있습니다.

슈퍼 관리자 부트스트랩

/admin 슈퍼 관리자 패널은 데이터베이스 계정이 아니라 환경 변수에서 부트스트랩됩니다.

변수	설명
`SUPER_ADMIN_EMAIL`	`/admin` 패널에 접근할 수 있는 슈퍼 관리자 계정의 이메일.
`SUPER_ADMIN_PASSWORD_HASH`	슈퍼 관리자 비밀번호의 bcrypt 해시(평문이 아님).

해시를 생성해 SUPER_ADMIN_PASSWORD_HASH로 전달합니다.

node -e "console.log(require('bcryptjs').hashSync('your-password', 10))"

싱글 사인온(OIDC)

싱글 사인온은 환경 변수로 구성하지 않습니다. 슈퍼 관리자가 /admin 패널에서 워크스페이스별로 OIDC를 구성하며, 그 설정은 데이터베이스에 저장됩니다. 각 워크스페이스는 자체 발급자(issuer) URL과 클라이언트 ID를 가지며, 둘 다 설정하면 그 워크스페이스에서 SSO가 켜집니다. Chorus는 PKCE를 사용하며 클라이언트 시크릿(client secret)을 요구하지 않습니다. 배포 수준의 부트스트랩은 슈퍼 관리자가 로그인할 수 있게 하는 역할만 하며, 이후 슈퍼 관리자가 관리 패널에서 워크스페이스별로 SSO를 구성합니다. 배포 계층에서 시크릿을 따로 준비할 필요는 없습니다.

마이그레이션 실행과 안전한 업그레이드

Chorus는 시작 시 보류 중인 데이터베이스 마이그레이션을 자동으로 적용합니다(prisma migrate deploy). 마이그레이션을 직접 실행할 필요가 없습니다. 새 버전을 시작하면 웹 애플리케이션이 요청을 처리하기 전에 아직 적용되지 않은 마이그레이션이 모두 적용됩니다.

업그레이드하려면:

먼저 데이터베이스를 백업하세요. 외부 PostgreSQL이면 데이터베이스 백업을 만들고, 내장 또는 볼륨 기반 데이터베이스면 데이터 볼륨을 백업합니다.
새 버전을 가져옵니다. npm 패키지는 npm update -g @chorus-aidlc/chorus, Docker 배포는 새 컨테이너 이미지를 가져옵니다(pull).
Chorus를 재시작합니다. 마이그레이션은 부팅 시 자동으로 적용되고, 그런 다음 앱이 시작됩니다.

0.19.1 업그레이드 순서

0.19.1에는 nullable 컬럼 하나만 추가하는 마이그레이션이 포함되어 있으므로 기존 데이터는 변경되지 않습니다. 에이전트 데몬을 실행하는 chorus CLI를 업그레이드하기 전에 Chorus 서버를 먼저 업그레이드하세요. 이전 버전의 데몬도 새 서버에서 계속 동작하며, 아이디어 생성 요청과 리서치 요청을 기존에 처리할 수 있는 형식으로 받습니다. 새 요청 형식을 긴급히 되돌려야 한다면 CHORUS_DEDICATED_OPERATION_WRITES=false를 설정하고 서버를 재시작하세요. 새 요청은 이전 형식을 사용하고, 이미 대기열에 있는 요청도 그대로 전달됩니다. CLI는 필요하면 따로 롤백하세요. 0.19.1이 만든 요청이 아직 대기 중이거나 실행 중인 동안에는 서버를 0.19.1보다 오래된 버전으로 롤백하지 말고, 새 컬럼도 제거하지 마세요.

0.18.1 업그레이드 시 세션 비밀 키

데이터베이스와 함께 서명 비밀 키도 백업하고, 키를 바꾸지 말고 유지하세요. 자동 생성된 키를 유지하려면 외부 PostgreSQL을 사용하더라도 Docker에 영구적인 /app/data 볼륨이 필요합니다. npm 런처는 기본적으로 ~/.chorus-data/.secret을 사용합니다. 이전에 공개 자리 표시자를 사용했다면 키가 새 값으로 바뀌므로 내장 이메일/비밀번호 로그인 사용자와 슈퍼 관리자가 다시 로그인해야 합니다. 명시적으로 설정한 안전한 키는 그대로 유지됩니다. CDK 재배포에서는 같은 nextAuthSecret을 지정하세요. 생략하면 synth마다 새 값이 생성됩니다. API 키와 OIDC 토큰은 이 교체의 영향을 받지 않습니다. Docker 배포 가이드의 세션 비밀 키를 참고하세요.

쿠키와 리버스 프록시

Chorus가 TLS 종료나 리버스 프록시 뒤에서 실행될 때 중요한 설정이 두 가지 있습니다.

변수	설정 값	경우
`COOKIE_SECURE`	`true`	사이트가 HTTPS로 제공됩니다(TLS를 종료하는 프록시 뒤 포함). 보안 쿠키는 암호화된 연결에서만 전송됩니다.
`COOKIE_SECURE`	`false`	신뢰할 수 있는 내부 HTTP 전용 네트워크에서만 사용합니다. 이 경우 쿠키가 암호화되지 않은 HTTP로 전송되므로, 공용 인터넷에서는 절대 사용하지 마세요.
`NEXTAUTH_URL`	외부 공개 기본 URL	Chorus가 리버스 프록시 뒤에서 실행됩니다. 리디렉션과 링크가 올바르게 해석되도록 외부에서 보이는 주소(예: `https://chorus.example.com`)로 설정합니다.