セルフホストの Chorus を運用する

このガイドでは、デプロイ後のセルフホスト Chorus の運用について説明します。最初のユーザーのサインイン、認証の設定、安全なアップグレード、HTTPS の背後で重要になる Cookie とリバースプロキシの設定を扱います。デプロイの構築方法については、本番環境でデプロイまたは 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))"

パスワードではなくハッシュを保存する

設定に入れてよいのは bcrypt ハッシュだけです。平文のパスワードは環境ファイル、シェルの履歴、ソース管理に残さず、可能であればシークレットストア経由でハッシュを渡してください。

シングルサインオン（OIDC）

シングルサインオンは環境変数では設定しません。スーパー管理者が /admin パネルからワークスペースごとに OIDC を設定し、その設定はデータベースに保存されます。各ワークスペースは独自の発行者（issuer）URL とクライアント ID を持ち、両方を設定するとそのワークスペースで SSO が有効になります。Chorus は PKCE を使い、クライアントシークレット（client secret）を必要としません。デプロイレベルのブートストラップが担うのはスーパー管理者がサインインできるようにすることだけで、その後はスーパー管理者が管理パネルから各ワークスペースの SSO を設定します。デプロイ層で別途シークレットをプロビジョニングする必要はありません。

マイグレーションの実行と安全なアップグレード

Chorus は起動時に、保留中のデータベースマイグレーションを自動的に適用します（prisma migrate deploy）。マイグレーションを手作業で実行することはありません。新しいバージョンを起動すると、Web アプリケーションがリクエストの受け付けを始める前に、未適用のマイグレーションがすべて適用されます。

アップグレードするには：

1. まずデータベースをバックアップします。 外部の PostgreSQL なら、バックアップを取ります。組み込みまたはボリューム管理のデータベースなら、データボリュームをバックアップします。
2. 新しいバージョンをプルします。npm パッケージなら npm update -g @chorus-aidlc/chorus、Docker デプロイなら新しいコンテナイメージをプルします。
3. Chorus を再起動します。マイグレーションは起動時に自動的に適用され、その後アプリが起動します。

アップグレード前にバックアップする

アップグレード前には、必ずデータベース（組み込み／ボリューム管理のストレージならデータボリューム）をバックアップしてください。マイグレーションは自動的に実行され、スキーマを変更することがあるため、バックアップが唯一の安全なロールバックポイントです。構成に合わせて、標準の PostgreSQL バックアップドキュメントに従ってください。

0.19.1 のアップグレード順序

0.19.1 には NULL 許容の列を追加するだけのマイグレーションが含まれるため、既存のデータは変更されません。エージェントデーモンを動かしている 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 でのセッション秘密鍵の扱いを参照してください。

Cookie とリバースプロキシ

Chorus が TLS 終端やリバースプロキシの背後で動作するとき、重要になる設定が二つあります。

変数	設定値	場合
COOKIE_SECURE	true	サイトが HTTPS で提供される（TLS を終端するプロキシの背後を含む）。セキュア Cookie は暗号化された接続でのみ送信されます。
COOKIE_SECURE	false	信頼できる内部の HTTP のみのネットワークに限る。この場合 Cookie は暗号化されていない HTTP で送信されるため、公衆インターネットでは決して使用しないでください。
NEXTAUTH_URL	対外的なベース URL	Chorus がリバースプロキシの背後で動作する。リダイレクトやリンクが正しく解決されるよう、外部から見えるアドレス（例：https://chorus.example.com）に設定します。