Saltar al contenido principal

Despliegue y configuración

En el artículo anterior, cubrimos lo básico sobre cómo empezar rápidamente con Logto. Este artículo profundiza más, enfocándose en las mejores prácticas y pasos detallados de configuración para desplegar Logto en un entorno de producción.

Variables de entorno​

Usamos un conjunto predefinido de variables de entorno generado en nuestra demo (docker-compose.yml), que deberías reemplazar por las tuyas propias y mantener la coherencia entre múltiples instancias de Logto.

Puedes establecer las variables de entorno directamente o poner un archivo .env dentro de la raíz del proyecto Logto. Si estás probando con Docker, revisa el archivo .env generado de la imagen en /etc/logto.

Esenciales​

  • DB_URL El DSN de Postgres para la base de datos de Logto.
  • DATABASE_STATEMENT_TIMEOUT (v1.36.0+) statement_timeout de PostgreSQL en milisegundos. Usa una cadena numérica (por ejemplo, 5000) o DISABLE_TIMEOUT para PgBouncer/RDS Proxy. Consulta Configuración para más detalles.
  • PORT El puerto en el que Logto escucha. Por defecto 3001.
  • ENDPOINT Puedes especificar una URL con tu dominio personalizado para producción (Ej. ENDPOINT=https://logto.domain.com). Esto también afectará el valor del identificador de emisor OIDC.

Habilitar Consola de Administración

  • ADMIN_PORT El puerto en el que la Consola de Administración de Logto escucha. Por defecto 3002.
  • ADMIN_ENDPOINT Puedes especificar una URL con tu dominio personalizado para producción (Ej. ADMIN_ENDPOINT=https://admin.domain.com). Esto también afectará el valor de los URI de redirección de la Consola de Administración.

Deshabilitar Consola de Administración

  • ADMIN_DISABLE_LOCALHOST Establécelo en 1 o true para cerrar el puerto de la Consola de Administración. Si ADMIN_ENDPOINT no está definido, deshabilitará completamente la Consola de Administración.

Para más detalles sobre las variables de entorno, consulta Configuración.

Habilitar Secret Vault

  • Para usar el Secret Vault, necesitas establecer SECRET_VAULT_KEK con una cadena codificada en base64 de tu Key Encryption Key (KEK). Esto se usa para cifrar las Data Encryption Keys (DEK) en el Secret Vault. Se recomienda AES-256 (32 bytes). Ejemplo: crypto.randomBytes(32).toString('base64').

Proxy HTTP saliente​

Si tu instancia de Logto autogestionada debe usar un proxy HTTP para acceder a servicios externos, como APIs de conectores sociales o proveedores de CAPTCHA, habilita el soporte de proxy por entorno y configura las variables estándar de proxy.

Por ejemplo, agrega las siguientes variables de entorno al servicio Logto en tu configuración de 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 habilita el soporte de proxy por entorno. En Node.js 22, requiere la versión 22.21.0 o superior.
  • HTTP_PROXY especifica el proxy para solicitudes HTTP.
  • HTTPS_PROXY especifica el proxy para solicitudes HTTPS. La URL del proxy puede usar HTTP o HTTPS.
  • NO_PROXY es una lista separada por comas de hosts que deben ser accedidos directamente. Incluye cualquier endpoint HTTP interno que no deba usar el proxy.

Ten en cuenta que esta configuración de proxy puede no aplicarse a todas las solicitudes salientes.

HTTPS​

Puedes usar Node.js para servir HTTPS directamente o configurar un proxy / balanceador HTTPS delante de Node.js. Consulta Habilitar HTTPS para más detalles.

Proxy inverso​

Si deseas usar un proxy inverso en tu servidor, por ejemplo Nginx o Apache, necesitas mapear los puertos 3001 y 3002 por separado en tu configuración de proxy pass. Suponiendo que usas Nginx, tu endpoint de autenticación de Logto corre en el puerto 3001 y tu consola de administración en el 3002, pon la siguiente configuración en nginx.conf:

Establece TRUST_PROXY_HEADER=1 para que Logto confíe en los encabezados reenviados. Usa $http_host tanto para Host como para X-Forwarded-Host para preservar los puertos no estándar en la URL pública.

server {
  listen 443 ssl;
  server_name <your_endpoint_url>; // ej. auth.tu-dominio.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 <ruta-a-tu-certificado-para-auth-endpoint>;
  ssl_certificate_key <ruta-a-tu-clave-para-auth-endpoint>
  ...
}

Luego agrega una configuración similar para tu consola de administración:

server {
  listen 443 ssl;
  server_name <your_admin_endpoint_url>; // ej. admin.tu-dominio.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 <ruta-a-tu-certificado-para-admin-endpoint>;
  ssl_certificate_key <ruta-a-tu-clave-para-admin-endpoint>
  ...
}

Recarga la configuración de Nginx para aplicar los últimos cambios:

nginx -s reload

¡Todo listo! Abre el navegador y visita https://admin.tu-dominio.com, deberías poder ver la página de bienvenida de Logto.

Contenerización​

Para producción, puedes usar Docker para contenerizar Logto. Puedes encontrar el Dockerfile en el directorio raíz del proyecto. Si deseas ejecutar múltiples instancias de Logto, por ejemplo, desplegar Logto en un clúster de Kubernetes, hay algunos pasos adicionales que debes seguir.

Configuración de la base de datos​

Prepara una base de datos Postgres para Logto. Se recomienda encarecidamente usar Logto CLI para inicializar la base de datos.

npm run cli db seed -- --swe

Consulta la Logto CLI para más detalles.

Instalaciones en entornos aislados o sin conexión:

Si tu entorno de despliegue no puede acceder a api.pwnedpasswords.com, añade --disable-admin-pwned-password-check tanto a logto init como a npm run cli db seed para que el primer registro de administrador no se quede esperando la comprobación de brechas de Have I Been Pwned. Consulta Seed para despliegues aislados o sin conexión para más detalles.

Carpeta compartida de conectores​

Por defecto, Logto creará una carpeta connectors en el directorio raíz de la carpeta core. La imagen oficial de Docker ya incluye los conectores oficiales en esta carpeta, así que no necesitas compartirla si solo usas conectores oficiales.

Si necesitas conectores que no están incluidos en la imagen, como tus propios conectores, recomendamos compartir la carpeta entre múltiples instancias de Logto. Monta la carpeta packages/core/connectors en el contenedor y ejecuta npm run cli connector add -- --official para desplegar los conectores oficiales, luego añade tus propios conectores en la misma carpeta. Montar un volumen en esta carpeta oculta los conectores incluidos en la imagen, por lo que los conectores oficiales deben añadirse de nuevo, lo que requiere acceso al registro de npm.

Hay un ejemplo mínimo de deployment para 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

En este ejemplo, creamos un directorio vacío como volumen y lo montamos en los contenedores. Luego ejecutamos npm run cli connector add -- --official en el contenedor de inicialización para descargar los conectores. Finalmente, cada contenedor compartirá la misma carpeta de conectores con nuestros conectores oficiales ya dentro.

nota:

Este es un ejemplo de yaml, para ejecutar Logto, necesitas establecer las variables de entorno correctamente.

Para producción, puedes reemplazar el volumen "empty dir" por un volumen persistente, y hacer el trabajo de "init" a tu manera, ¡tú sabes lo que haces!

Alteración de la base de datos​

Al igual que con los conectores, la alteración de la base de datos debe ejecutarse en una sola instancia. Puedes usar un job para ejecutar el script de alteración.

La variable de entorno CI=true es necesaria cuando la alteración se ejecuta de forma no interactiva.

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

Consulta Alteración de la base de datos para más detalles sobre el comando de alteración.