メインコンテンツまでスキップ

デプロイと構成

前回の記事では、Logto を素早く始める方法 の基本を解説しました。この記事ではさらに深く掘り下げ、本番環境で Logto をデプロイするためのベストプラクティスや詳細な構成手順に焦点を当てます。

環境変数​

デモ（docker-compose.yml）では生成された環境変数のプリセットを使用していますが、本番環境では独自の値に置き換え、複数の Logto インスタンス間で一貫性を保つ必要があります。

環境変数は直接設定するか、Logto プロジェクトのルートに .env ファイルを配置できます。Docker でテストする場合は、イメージの /etc/logto に生成される .env を確認してください。

必須項目​

  • DB_URL Logto データベース用の Postgres DSN。
  • DATABASE_STATEMENT_TIMEOUT (v1.36.0+) PostgreSQL の statement_timeout（ミリ秒単位）。数値文字列（例：5000）または PgBouncer/RDS Proxy 用に DISABLE_TIMEOUT を使用。詳細は 構成 を参照。
  • PORT Logto がリッスンするポート。デフォルトは 3001。
  • ENDPOINT 本番環境用にカスタムドメインの URL を指定可能（例：ENDPOINT=https://logto.domain.com）。これは OIDC 発行者 (Issuer) 識別子 の値にも影響します。

管理コンソールの有効化

  • ADMIN_PORT Logto 管理コンソールがリッスンするポート。デフォルトは 3002。
  • ADMIN_ENDPOINT 本番環境用にカスタムドメインの URL を指定可能（例：ADMIN_ENDPOINT=https://admin.domain.com）。これは管理コンソールのリダイレクト URI の値にも影響します。

管理コンソールの無効化

  • ADMIN_DISABLE_LOCALHOST 管理コンソール用ポートを閉じるには 1 または true を設定します。ADMIN_ENDPOINT が未設定の場合、管理コンソールが完全に無効化されます。

環境変数の詳細については 構成 を参照してください。

Secret Vault の有効化

  • Secret Vault を利用するには、SECRET_VAULT_KEK に Key Encryption Key (KEK) の base64 エンコード文字列を設定してください。これは Secret Vault 内の Data Encryption Key (DEK) を暗号化するために使用されます。AES-256（32 バイト）が推奨されます。例：crypto.randomBytes(32).toString('base64')。

アウトバウンド HTTP プロキシ​

セルフホスト型 Logto インスタンスが外部サービス（ソーシャルコネクター API や CAPTCHA プロバイダーなど）へアクセスする際に HTTP プロキシを利用する場合、環境変数によるプロキシサポートを有効化し、標準的なプロキシ変数を設定してください。

例えば、Docker Compose 構成の Logto サービスに以下の環境変数を追加します：

services:
  logto:
    image: ghcr.io/logto-io/logto:latest
    environment:
      NODE_USE_ENV_PROXY: '1'
      HTTP_PROXY: http://proxy.example.com:3128
      HTTPS_PROXY: http://proxy.example.com:3128
      NO_PROXY: localhost,127.0.0.1,::1,postgres,.internal.example.com
  • NODE_USE_ENV_PROXY=1 で環境変数によるプロキシサポートを有効化します。Node.js 22 ではバージョン 22.21.0 以降が必要です。
  • HTTP_PROXY は HTTP リクエスト用のプロキシを指定します。
  • HTTPS_PROXY は HTTPS リクエスト用のプロキシを指定します。プロキシ URL 自体は HTTP または HTTPS のいずれでも可。
  • NO_PROXY はプロキシを経由せず直接アクセスするホストのカンマ区切りリストです。プロキシを使いたくない内部 HTTP エンドポイントを含めてください。

このプロキシ設定は、すべてのアウトバウンドリクエストに必ずしも適用されるとは限らない点にご注意ください。

HTTPS​

Node.js で直接 HTTPS を提供するか、Node.js の前段に HTTPS プロキシ / バランサーを設置できます。詳細は HTTPS の有効化 を参照してください。

リバースプロキシ​

サーバーでリバースプロキシ（Nginx や Apache など）を利用する場合、3001 および 3002 ポートをプロキシパス設定で個別にマッピングする必要があります。Nginx を使用し、Logto 認証エンドポイントが 3001 ポート、管理コンソールが 3002 ポートで稼働している場合、nginx.conf に以下の設定を追加します：

Logto で転送ヘッダーを信頼するには TRUST_PROXY_HEADER=1 を設定してください。パブリック URL で非標準ポートを保持するため、Host および X-Forwarded-Host には $http_host を使用します。

server {
  listen 443 ssl;
  server_name <your_endpoint_url>; // 例：auth.your-domain.com
  ...

  location / {
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_pass http://127.0.0.1:3001;
  }

  ssl_certificate <path-to-your-certificate-for-auth-endpoint>;
  ssl_certificate_key <path-to-your-certificate-key-for-auth-endpoint>
  ...
}

管理コンソール用にも同様の設定を追加します：

server {
  listen 443 ssl;
  server_name <your_admin_endpoint_url>; // 例：admin.your-domain.com
  ...

  location / {
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_pass http://127.0.0.1:3002;
  }

  ssl_certificate <path-to-your-certificate-for-admin-endpoint>;
  ssl_certificate_key <path-to-your-certificate-key-for-admin-endpoint>
  ...
}

Nginx 設定をリロードして最新の変更を反映させます：

nginx -s reload

これで準備完了です。ブラウザで https://admin.your-domain.com にアクセスすると、Logto のウェルカムページが表示されます。

コンテナ化​

本番環境では、Docker を利用して Logto をコンテナ化できます。プロジェクトのルートディレクトリに Dockerfile が用意されています。Logto を複数インスタンスで実行したい場合（例：Kubernetes クラスターにデプロイする場合）、追加の手順が必要です。

データベースのセットアップ​

Logto 用の Postgres データベースを準備します。Logto CLI を使ってデータベースを初期化することを強く推奨します。

npm run cli db seed -- --swe

詳細は Logto CLI を参照してください。

エアギャップまたはオフラインインストール:

デプロイ環境が api.pwnedpasswords.com にアクセスできない場合、logto init または npm run cli db seed に --disable-admin-pwned-password-check を付与してください。これにより、最初の管理者サインアップ時に Have I Been Pwned の漏洩チェックで処理が停止するのを防げます。詳細は エアギャップまたはオフラインデプロイ用のシード を参照してください。

共有コネクターフォルダー​

デフォルトでは、Logto は core フォルダーのルートディレクトリに connectors フォルダーを作成します。公式 Docker イメージにはこのフォルダーに公式コネクターがすでに含まれているため、公式コネクターのみを使用する場合は共有の必要はありません。

イメージに含まれていないコネクター（独自コネクターなど）が必要な場合は、複数の Logto インスタンス間でこのフォルダーを共有することを推奨します。packages/core/connectors フォルダーをコンテナにマウントし、npm run cli connector add -- --official を実行して公式コネクターをデプロイし、その後同じフォルダーに独自コネクターを追加します。ボリュームをこのフォルダーにマウントするとイメージに含まれるコネクターが隠れるため、公式コネクターも再度追加する必要があり、npm レジストリへのアクセスが必要です。

Kubernetes 用の最小限の deployment 例を示します：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: logto
  namespace: default
spec:
  selector:
    matchLabels:
      app: logto
  template:
    metadata:
      labels:
        app: logto
    spec:
      volumes:
        - name: connectors
          emptyDir: {}
      initContainers:
        - image: ghcr.io/logto-io/logto
          command:
            - /bin/sh
          args:
            - '-c'
            - 'npm run cli connector add -- --official'
          name: init
          volumeMounts:
            - name: connectors
              mountPath: /etc/logto/packages/core/connectors
      containers:
        - image: ghcr.io/logto-io/logto
          name: logto
          volumeMounts:
            - name: connectors
              mountPath: /etc/logto/packages/core/connectors

この例では、空のディレクトリをボリュームとして作成し、コンテナにマウントしています。init コンテナで npm run cli connector add -- --official を実行してコネクターをダウンロードし、すべてのコンテナが同じコネクターフォルダー（公式コネクター入り）を共有します。

注記:

これはサンプル yaml です。Logto を動作させるには環境変数を適切に設定してください。

本番環境では "empty dir" ボリュームを永続ボリュームに置き換えたり、"init" ジョブを独自の方法で実行したりできます。ご自身の運用に合わせて調整してください。

データベースのオルタレーション​

コネクターと同様に、データベースのオルタレーション（スキーマ変更）は単一インスタンスで実行する必要があります。ジョブを使ってオルタレーションスクリプトを実行できます。

非対話型でオルタレーションを実行する場合は CI=true 環境変数が必要です。

apiVersion: batch/v1
kind: Job
metadata:
  name: alteration
spec:
  template:
    spec:
      containers:
        - name: alteration
          image: ghcr.io/logto-io/logto
          imagePullPolicy: Always
          env:
            - name: CI
              value: 'true'
            - name: DB_URL
              value: postgresql://user:password@localhost:5432/logto
          command:
            - /bin/sh
          args:
            - '-c'
            - 'npm run alteration deploy latest'
      restartPolicy: Never

オルタレーションコマンドの詳細は データベースのオルタレーション を参照してください。