Zum Hauptinhalt springen

Bereitstellung und Konfiguration

Im vorherigen Artikel haben wir die Grundlagen zum schnellen Einstieg mit Logto behandelt. Dieser Artikel geht tiefer ins Detail 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 (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, schau dir die vom Image generierte .env in /etc/logto an.

Wesentliches​

  • DB_URL Die Postgres DSN für die Logto-Datenbank.
  • DATABASE_STATEMENT_TIMEOUT (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. Standard 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 issuer identifier.

Admin-Konsole aktivieren

  • ADMIN_PORT Der Port, auf dem die Logto Admin-Konsole lauscht. Standard 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').

HTTPS​

Du kannst Node.js direkt für HTTPS verwenden 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 läuft auf 3002, füge die folgende Konfiguration in 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, gibt es einige zusätzliche Schritte, die du beachten musst.

Datenbankeinrichtung​

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

npm run cli db seed -- --swe

Weitere Informationen findest du in der Logto CLI.

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. Wir empfehlen, den Ordner zwischen mehreren Instanzen von Logto zu teilen. Du musst den Ordner packages/core/connectors ins Container mounten und npm run cli connector add -- --official ausführen, um die Connectors bereitzustellen.

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

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: logto
  namespace: default
spec:
  template:
    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 mounten es in die Container. 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 unseren offiziellen Connectors darin.

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 notwendig, 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.