Aller au contenu principal

Déploiement et configuration

Dans l'article précédent, nous avons couvert les bases de démarrer rapidement avec Logto. Cet article va plus loin, en se concentrant sur les bonnes pratiques et les étapes de configuration détaillées pour déployer Logto dans un environnement de production.

Variables d'environnement​

Nous utilisons un ensemble généré de variables d'environnement dans notre démo (docker-compose.yml), que vous devez remplacer par les vôtres et maintenir la cohérence entre plusieurs instances Logto.

Vous pouvez définir les variables d'environnement directement ou placer un fichier .env à la racine du projet Logto. Si vous testez avec Docker, consultez le fichier .env généré de l'image dans /etc/logto.

Essentiels​

  • DB_URL Le DSN Postgres pour la base de données Logto.
  • DATABASE_STATEMENT_TIMEOUT (v1.36.0+) statement_timeout PostgreSQL en millisecondes. Utilisez une chaîne numérique (ex : 5000) ou DISABLE_TIMEOUT pour PgBouncer/RDS Proxy. Voir Configuration pour plus de détails.
  • PORT Le port sur lequel Logto écoute. Par défaut 3001.
  • ENDPOINT Vous pouvez spécifier une URL avec votre domaine personnalisé pour la production (ex : ENDPOINT=https://logto.domain.com). Cela affectera également la valeur de l'identifiant d'émetteur OIDC.

Activer la console d'administration

  • ADMIN_PORT Le port sur lequel la console d'administration Logto écoute. Par défaut 3002.
  • ADMIN_ENDPOINT Vous pouvez spécifier une URL avec votre domaine personnalisé pour la production (ex : ADMIN_ENDPOINT=https://admin.domain.com). Cela affectera également la valeur des URI de redirection de la console d'administration.

Désactiver la console d'administration

  • ADMIN_DISABLE_LOCALHOST Mettez à 1 ou true pour fermer le port de la console d'administration. Si ADMIN_ENDPOINT n'est pas défini, cela désactivera complètement la console d'administration.

Pour plus de détails sur les variables d'environnement, voir Configuration.

Activer le Secret Vault

  • Pour utiliser le Secret Vault, vous devez définir SECRET_VAULT_KEK sur une chaîne encodée en base64 de votre Key Encryption Key (KEK). Ceci est utilisé pour chiffrer les Data Encryption Keys (DEK) dans le Secret Vault. AES-256 (32 octets) est recommandé. Exemple : crypto.randomBytes(32).toString('base64').

Proxy HTTP sortant​

Si votre instance Logto auto-hébergée doit utiliser un proxy HTTP pour accéder à des services externes, tels que les API de connecteurs sociaux ou les fournisseurs de CAPTCHA, activez la prise en charge du proxy d'environnement et configurez les variables de proxy standard.

Par exemple, ajoutez les variables d'environnement suivantes au service Logto dans votre configuration Docker Compose :

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 active la prise en charge du proxy d'environnement. Sur Node.js 22, cela nécessite la version 22.21.0 ou supérieure.
  • HTTP_PROXY spécifie le proxy pour les requêtes HTTP.
  • HTTPS_PROXY spécifie le proxy pour les requêtes HTTPS. L'URL du proxy peut elle-même utiliser HTTP ou HTTPS.
  • NO_PROXY est une liste séparée par des virgules des hôtes à atteindre directement. Incluez tous les points de terminaison HTTP internes qui ne doivent pas utiliser le proxy.

Notez que cette configuration de proxy peut ne pas s'appliquer à toutes les requêtes sortantes.

HTTPS​

Vous pouvez utiliser Node.js pour servir HTTPS directement ou mettre en place un proxy / répartiteur HTTPS devant Node.js. Voir Activer HTTPS pour plus de détails.

Proxy inverse​

Si vous souhaitez utiliser un proxy inverse sur votre serveur, par exemple Nginx ou Apache, vous devez mapper séparément les ports 3001 et 3002 dans vos paramètres de proxy pass. En supposant que vous utilisez Nginx, que votre point de terminaison d'authentification Logto fonctionne sur le port 3001, et que votre console d'administration Logto fonctionne sur le port 3002, placez la configuration suivante dans nginx.conf :

Définissez TRUST_PROXY_HEADER=1 pour que Logto fasse confiance aux en-têtes transmis. Utilisez $http_host pour Host et X-Forwarded-Host afin de préserver les ports non standards dans l'URL publique.

server {
  listen 443 ssl;
  server_name <your_endpoint_url>; // ex : auth.votre-domaine.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>
  ...
}

Ajoutez ensuite une configuration similaire pour votre console d'administration :

server {
  listen 443 ssl;
  server_name <your_admin_endpoint_url>; // ex : admin.votre-domaine.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>
  ...
}

Rechargez la configuration Nginx pour prendre en compte les dernières modifications :

nginx -s reload

Tout est prêt. Ouvrez le navigateur et visitez https://admin.votre-domaine.com, vous devriez voir la page d'accueil Logto.

Conteneurisation​

Pour la production, vous pouvez utiliser Docker pour conteneuriser Logto. Vous trouverez le Dockerfile à la racine du projet. Si vous souhaitez exécuter plusieurs instances de Logto, par exemple, déployer Logto dans un cluster Kubernetes, il y a quelques étapes supplémentaires à suivre.

Configuration de la base de données​

Préparez une base de données Postgres pour Logto. Il est fortement recommandé d'utiliser Logto CLI pour initialiser la base de données.

npm run cli db seed -- --swe

Consultez la Logto CLI pour plus de détails.

Installations en environnement isolé ou hors ligne:

Si votre environnement de déploiement ne peut pas atteindre api.pwnedpasswords.com, ajoutez --disable-admin-pwned-password-check à logto init ou npm run cli db seed afin que la première inscription administrateur ne soit pas bloquée sur la vérification Have I Been Pwned. Voir Seed pour les déploiements isolés ou hors ligne pour plus de détails.

Dossier partagé des connecteurs​

Par défaut, Logto créera un dossier connectors dans le répertoire racine du dossier core. L'image Docker officielle inclut déjà les connecteurs officiels dans ce dossier, donc vous n'avez pas besoin de le partager si vous n'utilisez que les connecteurs officiels.

Si vous avez besoin de connecteurs qui ne sont pas inclus dans l'image, comme vos propres connecteurs, nous recommandons de partager le dossier entre plusieurs instances Logto. Montez le dossier packages/core/connectors dans le conteneur et exécutez npm run cli connector add -- --official pour déployer les connecteurs officiels, puis ajoutez vos propres connecteurs dans le même dossier. Monter un volume sur ce dossier masque les connecteurs inclus dans l'image, donc les connecteurs officiels doivent être ajoutés à nouveau, ce qui nécessite un accès au registre npm.

Voici un exemple minimal de deployment pour 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

Dans cet exemple, nous créons un dossier vide comme volume et le montons dans les conteneurs. Ensuite, nous exécutons npm run cli connector add -- --official dans le conteneur d'initialisation pour télécharger les connecteurs. Enfin, chaque conteneur partagera le même dossier de connecteurs avec nos connecteurs officiels déjà présents.

remarque:

Ceci est un exemple de yaml, pour exécuter Logto, vous devez correctement définir les variables d'environnement.

Pour la production, vous pouvez remplacer le volume "empty dir" par un volume persistant, et effectuer le travail "init" à votre façon, vous savez ce que vous faites !

Modification de la base de données​

Comme pour les connecteurs, la modification de la base de données doit être exécutée sur une seule instance. Vous pouvez utiliser un job pour exécuter le script de modification.

La variable d'environnement CI=true est nécessaire lorsque la modification est exécutée de manière non interactive.

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

Voir Modification de la base de données pour plus de détails sur la commande de modification.