Cómo instalar Logto en un VPS

Requisitos previos

Usa un VPS Ubuntu 22.04 o 24.04 limpio, con SSH, IP pública, al menos 2 GB de RAM y un dominio como auth.example.com. Puedes separar los hostnames de consola y endpoints para aplicar políticas de acceso distintas.

Se requiere PostgreSQL 14 o superior. Necesitas Docker Compose, un destino para backups PostgreSQL y un generador de secretos aleatorios. Los datos de identidad son sensibles, así que mantén el host actualizado y restringe la administración.

Paso 1, Conectarte a tu servidor

Prepara el host:

ssh root@SERVER_IP
apt update && apt upgrade -y
apt install -y ca-certificates curl
mkdir -p /opt/logto
cd /opt/logto
chmod 750 /opt/logto

Permite solo SSH, HTTP y HTTPS. Mantén PostgreSQL en la red privada de Docker y revisa que ningún servicio use los puertos del proxy.

Paso 2, Instalar Docker y Docker Compose

Instala Docker Engine y el plugin Compose siguiendo la documentación oficial para Ubuntu:

docker --version
docker compose version
systemctl enable --now docker

Usa las versiones de PostgreSQL y Logto soportadas por el release actual. No cambies una versión mayor sin leer las migraciones.

Paso 3, Ejecutar Logto con Docker Compose

Crea .env y sustituye cada placeholder:

POSTGRES_DB=logto
POSTGRES_USER=logto
POSTGRES_PASSWORD=REPLACE_WITH_A_RANDOM_VALUE
DB_URL=postgres://logto:REPLACE_WITH_A_RANDOM_VALUE@db:5432/logto
LOGTO_ENDPOINT=https://auth.example.com
LOGTO_ADMIN_ENDPOINT=https://admin.example.com

Los nombres y endpoints pueden cambiar por release. Usa los de la documentación oficial de Logto y mantén sincronizada la contraseña con DB_URL. LOGTO_ENDPOINT debe establecer tu URL pública final (ej. https://auth.example.com). Cambiarla tras la configuración inicial invalida los clientes OIDC y tokens existentes.

La estructura del despliegue es:

services:
  db:
    image: postgres:14
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - db_data:/var/lib/postgresql/data

  logto:
    image: svhd/logto:latest
    restart: unless-stopped
    depends_on:
      - db
    environment:
      DB_URL: ${DB_URL}
    ports:
      - "127.0.0.1:3001:3001"
      - "127.0.0.1:3002:3002"

volumes:
  db_data:

Usa el Compose oficial si el release añade servicios o comandos obligatorios. Valida, arranca y revisa:

docker compose config
docker compose pull
docker compose up -d
docker compose ps

Ejecuta el comando documentado de inicialización o migración antes de crear tenants reales. Para servidores aislados, pasa --disable-admin-pwned-password-check durante la siembra inicial de la base de datos, de lo contrario el primer registro de administrador se bloqueará en la comprobación de Have I Been Pwned.

Paso 4, Configurar el proxy inverso

Logto expone dos puertos: 3001 para el endpoint Core/Experience/auth y 3002 para la Admin Console. Dirige el endpoint de usuarios al puerto 3001 y el de administración al puerto 3002 según la versión instalada. Termina HTTPS con Caddy o Nginx, conserva host y protocolo y mantén privados ambos puertos. Da a la consola un hostname separado y otra restricción si puedes.

Prueba redirect URIs, seguridad de cookies y renovación de certificados. OAuth rechaza diferencias pequeñas de hostname o esquema, así que usa exactamente las URLs HTTPS definidas en Logto. Define TRUST_PROXY_HEADER=1 en el entorno cuando Logto esté detrás de un proxy inverso. Sin esto, la URL del issuer OIDC por defecto será http://127.0.0.1:3001.

Paso 5, Primer acceso y configuración inicial

Abre la consola protegida y crea el primer tenant u organización. Registra una aplicación de prueba, define su redirect URI y crea un usuario de test. Comprueba login, logout, refresh de tokens y callback desde un entorno desechable.

Deja los client IDs en la configuración de la aplicación y los client secrets en servidor. Activa solo los conectores y scopes necesarios. Revisa invitaciones y política de contraseñas antes de incorporar usuarios reales.

Mantenimiento

Haz backup de PostgreSQL y los secretos de Logto juntos. Prueba restaurar un tenant en otro host. Actualiza mediante el proceso soportado, vigila las migraciones y verifica un login completo tras cada cambio.

Controla logins fallidos, conexiones, disco y caducidad de certificados. Nunca soluciones un problema de login desactivando HTTPS o exponiendo PostgreSQL.