필사 모드: Langfuseのセルフホスト — 配備経路、シークレット、そして初回起動で引っかかるもの

• はじめに — 何を立てるのかを知ってから始める
• もっとも速い経路 — docker compose
• 必ず自分で作って入れる値
• データストアごとの接続設定
• オブジェクトストレージの設定
• Kubernetesの経路 — Helmチャート
• 初回起動で確認すること
• よくある失敗
• 本番へ移る前に
• おわりに — 順序がそのまま診断になる
• 試してみる
• シリーズ
• 参考資料

はじめに — 何を立てるのかを知ってから始める

第三回では構成要素を見ました。ウェブとワーカーのコンテナ、そしてPostgres、ClickHouse、Redis、オブジェクトストレージです。今回はそれらを実際に立てる側です。

セルフホストで最も時間を食うのは配備ツールではありません。値を間違えた環境変数一つです。しかも誤った値はたいてい静かに失敗します。コンテナは立ち上がり、ログインもできるのに、トレースだけが入ってきません。

構成と設定名は2026-08-15に公式ドキュメントで確認しました。Langfuseはバージョンによってアーキテクチャが変わるため、利用中のバージョンのドキュメントを再確認してください。以下の名前と既定値はv4のドキュメントに基づきます。ドキュメントで確認できなかった値は本記事に書いていません。

もっとも速い経路 — docker compose

docker compose のドキュメントが案内する手順は、リポジトリを取得してcomposeを立ち上げることです。

git clone https://github.com/langfuse/langfuse.git
cd langfuse

# シークレットを先に変えてから立ち上げる
docker compose up -d
docker compose ps

リポジトリ最上位のcomposeファイルを2026-08-15に確認した時点で、定義されているサービスとイメージは次のとおりです。

二つのLangfuseサービスは四つのデータストアすべてにヘルスチェック依存を張っているため、ストアが準備できるまで起動しません。ドキュメントは、インスタンスにセキュリティグループかファイアウォールを置き、3000番と9090番だけ受け付けるよう制限することを推奨しています。

composeファイル内で変更すべき行には# CHANGEMEのコメントが付いています。そのすべてを処理する前に本番へ出してはいけません。

必ず自分で作って入れる値

設定のドキュメントが必須と示すセキュリティ関連の変数は四つです。

ドキュメントはNEXTAUTH_SECRETとSALTに256ビット以上のエントロピーを、ENCRYPTION_KEYには16進形式の256ビット値を求めています。

# 例: 求められる形式に合う値を作る
openssl rand -base64 32   # NEXTAUTH_SECRET
openssl rand -base64 32   # SALT
openssl rand -hex 32      # ENCRYPTION_KEY (16進の256ビット)

SALTとENCRYPTION_KEYを後から変えると既存データが読めなくなります。配備の初日に決めてシークレット管理システムへ入れてください。NEXTAUTH_URLは実際に接続されるアドレスと厳密に一致させます。リバースプロキシの背後でこの値が内部アドレスのままだと、ログインのリダイレクトが壊れます。

データストアごとの接続設定

Postgres側でドキュメントが定義する変数は四つです。

• DATABASE_URL — Postgresの接続文字列です。必須です。
• DIRECT_URL — マイグレーションに使う接続文字列です。既定値はDATABASE_URLで、マイグレーション専用のアカウントやプーラを迂回した直結が必要なときに別途与えます。
• SHADOW_DATABASE_URL — データベースユーザーにデータベース作成権限がないときに必要です。
• LANGFUSE_AUTO_POSTGRES_MIGRATION_DISABLED — 既定値はfalseで、起動時の自動マイグレーションを止めます。

ClickHouse側は接続文字列が二つある点が最初は分かりにくいところです。プロトコルが異なるからです。

# 例: プロトコルが異なる二つのエンドポイント
CLICKHOUSE_MIGRATION_URL="clickhouse://clickhouse-host:9000"   # TCP、9000 または 9440
CLICKHOUSE_URL="http://clickhouse-host:8123"                   # HTTP(S)、8123 または 8443
CLICKHOUSE_USER="langfuse"
CLICKHOUSE_PASSWORD="changeme"
CLICKHOUSE_DB="langfuse"
CLICKHOUSE_CLUSTER_ENABLED="false"

ClickHouseのドキュメントが示すパターンがこれです。マイグレーションはTCPプロトコルで、通常の問い合わせはHTTPで出ます。CLICKHOUSE_DBの既定値はdefault、CLICKHOUSE_CLUSTER_ENABLEDの既定値はtrueです。単一コンテナで立てたならこの値をfalseに下げます。クラスタ名はCLICKHOUSE_CLUSTER_NAMEで変え、既定値はdefaultです。SSLが必要ならCLICKHOUSE_MIGRATION_SSLを有効にします。

ユーザー権限は第三回で見たとおりです。INSERT、SELECT、ALTER UPDATE、ALTER DELETE、ALTER DROP INDEX、CREATE、DROP TABLEが必要です。いずれか一つでも欠けるとマイグレーションの段階で止まります。

RedisはREDIS_CONNECTION_STRING一つで指定するか、REDIS_HOST、REDIS_PORT、REDIS_AUTHに分けて与えます。クラスタとセンチネルのモードには、それぞれREDIS_CLUSTER_ENABLEDとREDIS_SENTINEL_ENABLEDの系統の変数が別にあります。そして第三回で強調したmaxmemory-policyをnoevictionにする設定を忘れないでください。

オブジェクトストレージの設定

オブジェクトストレージのドキュメントが必須と示すのはイベントアップロード用のバケットです。メディアアップロード用のバケットも設定ドキュメントでは必須と示されています。

# 例: MinIO を使う場合
LANGFUSE_S3_EVENT_UPLOAD_BUCKET="langfuse"
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT="http://minio:9000"
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID="minio"
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY="changeme"
LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE="true"
LANGFUSE_S3_EVENT_UPLOAD_PREFIX="events/"

LANGFUSE_S3_MEDIA_UPLOAD_BUCKET="langfuse"
LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT="http://minio:9000"
LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE="true"

覚えるのは二つです。接頭辞を与えるときは必ずスラッシュで終える必要があります。そしてMinIOではパス方式を強制するオプションが必要だとドキュメントが明示しています。これがないとバケット名がホスト名として解釈され、名前解決に失敗します。

バッチエクスポートは既定で無効です。LANGFUSE_S3_BATCH_EXPORT_ENABLEDを有効にすると、それ専用のバケット設定が必要になります。AWS S3なら必要な最小権限は、バケットとオブジェクトの双方に対するs3:PutObject、s3:ListBucket、s3:GetObjectです。

Kubernetesの経路 — Helmチャート

Helmのドキュメントが案内するチャートリポジトリとインストールコマンドは次のとおりです。

helm repo add langfuse https://langfuse.github.io/langfuse-k8s
helm repo update
helm install langfuse langfuse/langfuse -n langfuse --create-namespace

既定のインストールはアプリケーションコンテナとデータストアをまとめて立てます。すでに運用中のPostgres、ClickHouse、Redisを指すよう変えることもできます。チャートリポジトリのREADMEが示す値の構造は、最上位キーがlangfuse、postgresql、clickhouse、redis、そしてs3またはminioに分かれる形です。

# 例: シークレットを値ファイルに直接書かない形
langfuse:
  salt:
    secretKeyRef:
      name: langfuse-secrets
      key: salt
  nextauth:
    secret:
      secretKeyRef:
        name: langfuse-secrets
        key: nextauth-secret
  encryptionKey:
    secretKeyRef:
      name: langfuse-secrets
      key: encryption-key

postgresql:
  auth:
    username: langfuse
    existingSecret: langfuse-postgres

clickhouse:
  auth:
    existingSecret: langfuse-clickhouse

redis:
  auth:
    existingSecret: langfuse-redis

s3:
  storageProvider: s3

値の正確な入れ子はチャートのバージョンによって変わるため、実際のキー名と既定値は利用中のバージョンのドキュメントとチャートのREADMEで確認してください。READMEが示す原則は二つです。パスワードは値として直接書くか、existingSecretとexistingSecretKeyで既存のシークレットを指せます。そして外部のデータストアを使えば、チャートのリリースとストアの寿命を切り離せます。

注意点が一つあります。リリース名をlangfuse以外にしてインストールした場合、Redisのホスト名をそれに合わせて調整する必要があるとドキュメントが述べています。Helmの命名規則から生じる問題です。

初回起動で確認すること

Helmのドキュメントは、配備に最大5分かかること、その間にlangfuse-webとlangfuse-workerのコンテナがデータベース準備の過程で再起動することを述べています。つまり初期に見える再起動は正常な挙動です。5分を過ぎても繰り返すなら、そこからが本当の問題です。

# コンテナの状態とログ
docker compose ps
docker compose logs -f langfuse-web
docker compose logs -f langfuse-worker

# ウェブが応答するか確認
curl -sS -o /dev/null -w "%{http_code}\n" http://localhost:3000

確認の順序はこう組むとよいでしょう。

1. 四つのデータストアがすべてhealthyかを見ます。ここで詰まっているならアプリケーションのログを見る必要はありません。
2. ウェブのログでマイグレーションが終わったかを確認します。PostgresとClickHouseの両方です。
3. ウェブにアクセスしてアカウントを作り、プロジェクトを作ります。ここまではPostgresだけで動きます。
4. SDKでトレースを一件送ります。画面に出れば、ClickHouse、Redis、オブジェクトストレージがすべて生きているという意味です。

四番目が第三回で見た取り込み経路をまるごと検証します。ですから初回起動の確認はここまでやって終わりです。

よくある失敗

ドキュメントに根拠のある失敗の型を集めると次のようになります。

最後から二番目の項目はコンテナのドキュメントが明示している事項です。コンテナに割り当てたメモリがNodeの既定上限である約1.7GiBを超えるとき、NODE_OPTIONSでヒープの大きさを明示しないと問題が起きます。両方のコンテナに設定する必要があります。

起動時の問題を追うにはログ設定も助けになります。LANGFUSE_LOG_LEVELの既定値はinfoで、traceからfatalまで調整できます。LANGFUSE_LOG_FORMATは既定がtextで、jsonに変えるとログ収集のパイプラインへ載せやすくなります。

本番へ移る前に

コンテナのドキュメントが推奨する資源配分は、すべてのコンテナに最低CPU2コアとメモリ4GBです。可用性のためにウェブコンテナは最低二つ立て、いずれかのCPU使用率が50パーセントを超えたらインスタンスを増やすとしています。

データストア側の推奨は第三回で整理したとおりです。ClickHouseはシャード1にレプリカ3以上、Postgresはv4で最低15かつ16推奨、Redisは7.2推奨です。

マイグレーションの方針も本番では考え直す必要があります。既定は起動時の自動マイグレーションです。複数のインスタンスが同時に立ち上がる環境や、スキーマ変更を配備と分けたい場合は、LANGFUSE_AUTO_POSTGRES_MIGRATION_DISABLEDとLANGFUSE_AUTO_CLICKHOUSE_MIGRATION_DISABLEDを有効にして別の段階として実行します。ClickHouseのドキュメントは手動の手順として、リポジトリを取得し./packages/shared/clickhouse/migrations/clustered/配下のSQLでクラスタ名を調整してから実行するよう案内しています。

おわりに — 順序がそのまま診断になる

配備の順序をデータストアからアプリケーションへと組めば、問題が起きても範囲が狭く済みます。四つのストアを先に立ててhealthyを確認し、四つのシークレットを作って入れ、接続文字列を埋め、それからアプリケーションを立てます。最後にトレースを一件送って経路全体を検証します。

今できる点検はシークレット管理です。SALTとENCRYPTION_KEYがcomposeファイルや値ファイルに平文で残っているなら、それをシークレットストアへ移すことが次の配備より先です。次回は、こうして立てたシステムがトラフィックを受け始めたとき、費用がどこで増えるのかを見ます。

試してみる

• HTTPリクエストビルダー（cURL生成） — 初回起動確認用のヘルスチェック要求を作っておけば、配備スクリプトにそのまま入れられます。
• PostgreSQLプレイグラウンド — マイグレーション用のアカウントとアプリケーション用のアカウントで権限を分ける練習をしてみてください。

シリーズ

• 前の記事: LangfuseがトレースをClickHouseに置く理由
• 次の記事: トレースが費用になるとき — 保持、サンプリング、マスキング

参考資料

• Langfuse docker compose 配備: https://langfuse.com/self-hosting/deployment/docker-compose
• Langfuse Kubernetes Helm 配備: https://langfuse.com/self-hosting/deployment/kubernetes-helm
• Langfuse 設定変数: https://langfuse.com/self-hosting/configuration
• Langfuse ClickHouse: https://langfuse.com/self-hosting/infrastructure/clickhouse
• Langfuse オブジェクトストレージ: https://langfuse.com/self-hosting/infrastructure/blobstorage
• Langfuse コンテナ: https://langfuse.com/self-hosting/infrastructure/containers
• langfuse-k8s チャートリポジトリ: https://github.com/langfuse/langfuse-k8s