이 가이드는 배포를 마친 셀프 호스팅 Chorus의 운영을 다룹니다. 첫 사용자 로그인, 인증 구성, 안전한 업그레이드, 그리고 HTTPS 환경에서 중요한 쿠키와 리버스 프록시 설정을 설명합니다. 배포를 구축하는 방법은 [프로덕션 배포](/ko/guides/deploy-production/) 또는 [Docker로 배포](/ko/guides/deploy-docker/)를 참고하세요.
## 첫 접근을 부트스트랩하기
새 배포에는 아직 계정이 없습니다. `DEFAULT_USER`와 `DEFAULT_PASSWORD`를 설정해 싱글 사인온을 우회하는 내장 이메일/비밀번호 로그인을 활성화합니다.
```sh
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`로 전달합니다.
```sh
node -e "console.log(require('bcryptjs').hashSync('your-password', 10))"
```
:::caution[비밀번호가 아니라 해시를 저장하세요]
구성에 넣어도 되는 것은 bcrypt 해시뿐입니다. 평문 비밀번호는 환경 파일, 셸 히스토리, 소스 관리에 남기지 말고, 가능한 한 비밀 저장소를 통해 해시를 주입하세요.
:::
### 싱글 사인온(OIDC)
싱글 사인온은 환경 변수로 구성하지 **않습니다**. 슈퍼 관리자가 `/admin` 패널에서 워크스페이스별로 OIDC를 구성하며, 그 설정은 데이터베이스에 저장됩니다. 각 워크스페이스는 자체 발급자(issuer) URL과 클라이언트 ID를 가지며, 둘 다 설정하면 그 워크스페이스에서 SSO가 켜집니다. Chorus는 PKCE를 사용하며 클라이언트 시크릿(client secret)을 **요구하지 않습니다**. 배포 수준의 부트스트랩은 슈퍼 관리자가 로그인할 수 있게 하는 역할만 하며, 이후 슈퍼 관리자가 관리 패널에서 워크스페이스별로 SSO를 구성합니다. 배포 계층에서 시크릿을 따로 준비할 필요는 없습니다.
## 마이그레이션 실행과 안전한 업그레이드
Chorus는 시작 시 보류 중인 데이터베이스 마이그레이션을 자동으로 적용합니다(`prisma migrate deploy`). 마이그레이션을 직접 실행할 필요가 없습니다. 새 버전을 시작하면 웹 애플리케이션이 요청을 처리하기 전에 아직 적용되지 않은 마이그레이션이 모두 적용됩니다.
업그레이드하려면:
1. **먼저 데이터베이스를 백업하세요.** 외부 PostgreSQL이면 데이터베이스 백업을 만들고, 내장 또는 볼륨 기반 데이터베이스면 데이터 볼륨을 백업합니다.
2. 새 버전을 가져옵니다. npm 패키지는 `npm update -g @chorus-aidlc/chorus`, Docker 배포는 새 컨테이너 이미지를 가져옵니다(pull).
3. Chorus를 재시작합니다. 마이그레이션은 부팅 시 자동으로 적용되고, 그런 다음 앱이 시작됩니다.
:::caution[업그레이드 전에 백업하세요]
업그레이드 전에는 항상 데이터베이스(내장/볼륨 기반 스토리지면 데이터 볼륨)를 백업하세요. 마이그레이션은 자동으로 실행되며 스키마를 바꿀 수 있으므로, 안전하게 롤백할 수 있는 지점은 백업뿐입니다. 사용 중인 구성에 맞춰 표준 [PostgreSQL 백업 문서](https://www.postgresql.org/docs/current/backup.html)를 따르세요.
:::
### 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 배포 가이드의 세션 비밀 키](/ko/guides/deploy-docker/#세션-비밀-키nextauth_secret)를 참고하세요.
## 쿠키와 리버스 프록시
Chorus가 TLS 종료나 리버스 프록시 뒤에서 실행될 때 중요한 설정이 두 가지 있습니다.
| 변수 | 설정 값 | 경우 |
| --- | --- | --- |
| `COOKIE_SECURE` | `true` | 사이트가 HTTPS로 제공됩니다(TLS를 종료하는 프록시 뒤 포함). 보안 쿠키는 암호화된 연결에서만 전송됩니다. |
| `COOKIE_SECURE` | `false` | 신뢰할 수 있는 내부 HTTP 전용 네트워크에서만 사용합니다. 이 경우 쿠키가 암호화되지 않은 HTTP로 전송되므로, 공용 인터넷에서는 절대 사용하지 마세요. |
| `NEXTAUTH_URL` | 외부 공개 기본 URL | Chorus가 리버스 프록시 뒤에서 실행됩니다. 리디렉션과 링크가 올바르게 해석되도록 외부에서 보이는 주소(예: `https://chorus.example.com`)로 설정합니다. |