셀프 호스팅 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 제공자를 거칩니다.

배포 측 인증 구성하기

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

SuperAdmin 부트스트랩

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

변수	설명
SUPER_ADMIN_EMAIL	/admin 패널에 도달할 수 있는 SuperAdmin 계정의 이메일.
SUPER_ADMIN_PASSWORD_HASH	SuperAdmin 비밀번호의 bcrypt 해시(결코 평문이 아닙니다).

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

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

비밀번호가 아니라 해시를 저장하세요

구성에 넣어도 되는 것은 bcrypt 해시뿐입니다. 평문 비밀번호는 환경 파일, 셸 히스토리, 소스 관리에서 멀리 두고, 가능한 한 비밀 저장소를 통해 해시를 주입하세요.

싱글 사인온(OIDC)

싱글 사인온은 환경 변수로 구성하지 않습니다. SuperAdmin이 /admin 패널에서 회사별로 OIDC를 구성하며, 그 설정은 데이터베이스에 저장됩니다. 각 회사는 자체 발급자(issuer), 클라이언트 ID, 활성화 토글을 가집니다. Chorus는 PKCE를 사용하며 클라이언트 시크릿(client secret)을 요구하지 않습니다. 따라서 배포 수준의 부트스트랩은 SuperAdmin을 들여보내는 일만 담당하고, 그다음 SuperAdmin이 관리 패널에서 각 회사의 SSO를 켭니다. 배포 계층에서 별도의 시크릿 프로비저닝은 필요 없습니다.

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

Chorus는 시작 시 보류 중인 데이터베이스 마이그레이션을 자동으로 적용합니다(prisma migrate deploy). 마이그레이션을 손으로 실행하지 않습니다. 새 버전을 시작하면, 웹 애플리케이션이 서비스를 시작하기 전에 미처리된 것이 무엇이든 적용됩니다.

업그레이드하려면:

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

업그레이드 전에 백업하세요

업그레이드 전에는 항상 데이터베이스(내장/볼륨 기반 스토리지면 데이터 볼륨)를 백업하세요. 마이그레이션은 자동으로 실행되며 스키마를 바꿀 수 있으므로, 백업이 유일하게 안전한 롤백 지점입니다. 엔진별 절차를 즉석에서 지어내는 대신, 당신의 구성에 맞춰 표준 PostgreSQL 백업 문서를 따르세요.

쿠키와 리버스 프록시

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

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