Zum Hauptinhalt springen

Bereitstellung und Konfiguration

Im vorherigen Artikel haben wir die Grundlagen zum schnellen Einstieg mit Logto behandelt. Dieser Artikel geht einen Schritt weiter und konzentriert sich auf Best Practices und detaillierte Konfigurationsschritte für die Bereitstellung von Logto in einer Produktionsumgebung.

Umgebungsvariablen​

Wir verwenden ein generiertes Preset von Umgebungsvariablen in unserem Demo-Setup (docker-compose.yml), das du durch deine eigenen ersetzen und über mehrere Logto-Instanzen hinweg konsistent halten solltest.

Du kannst Umgebungsvariablen direkt setzen oder eine .env-Datei im Logto-Projektstamm ablegen. Wenn du mit Docker testest, sieh dir die vom Image generierte .env unter /etc/logto an.

Wesentliches​

  • DB_URL Die Postgres DSN für die Logto-Datenbank.
  • DATABASE_STATEMENT_TIMEOUT (ab v1.36.0) PostgreSQL statement_timeout in Millisekunden. Verwende einen numerischen String (z. B. 5000) oder DISABLE_TIMEOUT für PgBouncer/RDS Proxy. Siehe Konfiguration für Details.
  • PORT Der Port, auf dem Logto lauscht. Standardmäßig 3001.
  • ENDPOINT Du kannst eine URL mit deiner eigenen Domain für die Produktion angeben (z. B. ENDPOINT=https://logto.domain.com). Dies beeinflusst auch den Wert des OIDC-Aussteller-Identifiers.

Admin-Konsole aktivieren

  • ADMIN_PORT Der Port, auf dem die Logto Admin-Konsole lauscht. Standardmäßig 3002.
  • ADMIN_ENDPOINT Du kannst eine URL mit deiner eigenen Domain für die Produktion angeben (z. B. ADMIN_ENDPOINT=https://admin.domain.com). Dies beeinflusst auch die Redirect-URIs der Admin-Konsole.

Admin-Konsole deaktivieren

  • ADMIN_DISABLE_LOCALHOST Setze dies auf 1 oder true, um den Port für die Admin-Konsole zu schließen. Wenn ADMIN_ENDPOINT nicht gesetzt ist, wird die Admin-Konsole vollständig deaktiviert.

Weitere Details zu Umgebungsvariablen findest du unter Konfiguration.

Secret Vault aktivieren

  • Um den Secret Vault zu verwenden, musst du SECRET_VAULT_KEK auf einen base64-codierten String deines Key Encryption Key (KEK) setzen. Dieser wird verwendet, um Data Encryption Keys (DEK) im Secret Vault zu verschlüsseln. AES-256 (32 Bytes) wird empfohlen. Beispiel: crypto.randomBytes(32).toString('base64').

Outbound HTTP-Proxy​

Wenn deine selbst gehostete Logto-Instanz einen HTTP-Proxy verwenden muss, um externe Dienste wie Social Connector APIs oder CAPTCHA-Anbieter zu erreichen, aktiviere den Umgebungs-Proxy-Support und konfiguriere die Standard-Proxy-Variablen.

Füge beispielsweise die folgenden Umgebungsvariablen zum Logto-Service in deiner Docker Compose-Konfiguration hinzu:

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 aktiviert den Umgebungs-Proxy-Support. Unter Node.js 22 ist Version 22.21.0 oder neuer erforderlich.
  • HTTP_PROXY gibt den Proxy für HTTP-Anfragen an.
  • HTTPS_PROXY gibt den Proxy für HTTPS-Anfragen an. Die Proxy-URL selbst kann HTTP oder HTTPS verwenden.
  • NO_PROXY ist eine durch Kommas getrennte Liste von Hosts, die direkt erreicht werden sollen. Füge alle internen HTTP-Endpunkte hinzu, die nicht über den Proxy laufen sollen.

Beachte, dass diese Proxy-Konfiguration möglicherweise nicht für alle ausgehenden Anfragen wirksam ist.

HTTPS​

Du kannst Node.js verwenden, um HTTPS direkt bereitzustellen, oder einen HTTPS-Proxy / Load Balancer vor Node.js einrichten. Siehe HTTPS aktivieren für Details.

Reverse Proxy​

Wenn du einen Reverse Proxy auf deinem Server verwenden möchtest, z. B. Nginx oder Apache, musst du die Ports 3001 und 3002 separat in deinen Proxy-Pass-Einstellungen abbilden. Angenommen, du verwendest Nginx, dein Logto-Auth-Endpunkt läuft auf Port 3001 und deine Logto-Admin-Konsole auf 3002, dann füge folgende Konfiguration in die nginx.conf ein:

Setze TRUST_PROXY_HEADER=1, damit Logto die weitergeleiteten Header vertraut. Verwende $http_host sowohl für Host als auch für X-Forwarded-Host, um nicht-standardisierte Ports in der öffentlichen URL zu erhalten.

server {
  listen 443 ssl;
  server_name <your_endpoint_url>; // z. B. 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>
  ...
}

Füge dann eine ähnliche Konfiguration für deine Admin-Konsole hinzu:

server {
  listen 443 ssl;
  server_name <your_admin_endpoint_url>; // z. B. 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>
  ...
}

Lade die Nginx-Konfiguration neu, um die neuesten Änderungen zu übernehmen:

nginx -s reload

Das war's. Öffne den Browser und besuche https://admin.your-domain.com, du solltest die Logto-Willkommensseite sehen.

Containerisierung​

Für die Produktion kannst du Docker verwenden, um Logto zu containerisieren. Die Dockerfile findest du im Stammverzeichnis des Projekts. Wenn du mehrere Instanzen von Logto ausführen möchtest, z. B. Logto in einem Kubernetes-Cluster bereitstellen, sind einige zusätzliche Schritte erforderlich.

Datenbankeinrichtung​

Bereite eine Postgres-Datenbank für Logto vor. Es wird dringend empfohlen, die Logto CLI zur Initialisierung der Datenbank zu verwenden.

npm run cli db seed -- --swe

Siehe Logto CLI für weitere Details.

Air-gapped- oder Offline-Installationen:

Wenn deine Bereitstellungsumgebung api.pwnedpasswords.com nicht erreichen kann, füge --disable-admin-pwned-password-check entweder zu logto init oder npm run cli db seed hinzu, damit die erste Admin-Registrierung nicht beim Have I Been Pwned-Breach-Check hängen bleibt. Siehe Seed für Air-gapped- oder Offline-Bereitstellungen für Details.

Gemeinsamer Connectors-Ordner​

Standardmäßig erstellt Logto einen connectors-Ordner im Stammverzeichnis des core-Ordners. Das offizielle Docker-Image enthält bereits die offiziellen Connectors in diesem Ordner, sodass du ihn nicht teilen musst, wenn du nur offizielle Connectors verwendest.

Wenn du Connectors benötigst, die nicht im Image enthalten sind, z. B. eigene Connectors, empfehlen wir, den Ordner zwischen mehreren Logto-Instanzen zu teilen. Binde den Ordner packages/core/connectors ins Container-Volume ein und führe npm run cli connector add -- --official aus, um die offiziellen Connectors bereitzustellen. Füge dann deine eigenen Connectors in denselben Ordner hinzu. Das Mounten eines Volumes auf diesen Ordner versteckt die im Image enthaltenen Connectors, daher müssen die offiziellen Connectors erneut hinzugefügt werden, was Zugriff auf das npm-Registry erfordert.

Hier ein minimales Beispiel für ein deployment für Kubernetes:

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

In diesem Beispiel erstellen wir ein leeres Verzeichnis als Volume und binden es in die Container ein. Dann führen wir npm run cli connector add -- --official im Init-Container aus, um die Connectors herunterzuladen. Schließlich teilen sich alle Container denselben Connectors-Ordner mit den offiziellen Connectors.

hinweis:

Dies ist ein Beispiel-yaml. Um Logto auszuführen, musst du die Umgebungsvariablen korrekt setzen.

Für die Produktion kannst du das "empty dir"-Volume durch ein persistentes Volume ersetzen und den "init"-Job auf deine eigene Weise erledigen – du weißt, was du tust!

Datenbankänderung​

Ähnlich wie bei den Connectors muss die Datenbankänderung in einer einzelnen Instanz ausgeführt werden. Du kannst einen Job verwenden, um das Änderungsskript auszuführen.

Die Umgebungsvariable CI=true ist erforderlich, wenn die Änderung nicht-interaktiv ausgeführt wird.

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

Siehe Datenbankänderung für Details zum Änderungskommando.