セルフホストの 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 プロバイダーを経由します。

デプロイ側の認証を設定する

デプロイのレベルで設定される認証は二種類あります。

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）。マイグレーションを手作業で実行することはありません。新しいバージョンを起動すると、Web アプリケーションが提供を始める前に、未処理のものが何であれ適用されます。

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

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

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

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

Cookie とリバースプロキシ

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

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