Como instalar o Logto em um VPS

Pré-requisitos

Use um VPS Ubuntu 22.04 ou 24.04 limpo, com SSH, IP público, pelo menos 2 GB de RAM e um domínio como auth.example.com. Planeje nomes de host separados caso queira políticas de acesso distintas para o console de gerenciamento e as URLs voltadas aos usuários.

É necessário usar PostgreSQL 14 ou superior. Você precisa do Docker Compose, de um destino para backups do PostgreSQL e de uma forma de gerar segredos aleatórios. Os dados de identidade são sensíveis do ponto de vista da segurança, então mantenha o servidor atualizado e restrinja o acesso administrativo.

Etapa 1, Conectar ao servidor

Prepare o servidor:

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

Permita apenas SSH, HTTP e HTTPS. Mantenha o PostgreSQL na rede privada do Docker e confirme que nenhum serviço não relacionado está usando as portas do proxy.

Etapa 2, Instalar o Docker e o Docker Compose

Instale o Docker Engine e o plugin Compose seguindo a documentação oficial do Docker para Ubuntu:

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

Use as versões do PostgreSQL e do Logto compatíveis com a versão oficial atual. Não atualize a versão principal de nenhum dos dois sem ler as notas de migração.

Etapa 3, Executar o Logto com Docker Compose

Crie .env e substitua todos os valores indicados como exemplos:

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

Os nomes exatos das variáveis de ambiente e o modelo de URLs podem variar conforme a versão. Use os nomes da documentação oficial de implantação do Logto e mantenha a senha do banco de dados sincronizada com DB_URL. LOGTO_ENDPOINT deve corresponder à URL pública definitiva (por exemplo, https://auth.example.com). Alterar esse valor após a configuração invalida os clientes e tokens OIDC existentes.

A estrutura da implantação é:

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:

Use o arquivo Compose oficial se a versão atual adicionar serviços ou comandos obrigatórios. Valide, inicie e inspecione:

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

Execute o comando documentado para inicializar ou migrar o banco de dados antes de criar ambientes de produção. Em servidores sem acesso à internet, passe --disable-admin-pwned-password-check durante a carga inicial do banco; caso contrário, o cadastro do primeiro administrador fica parado na verificação do Have I Been Pwned.

Etapa 4, Configurar o proxy reverso

O Logto expõe duas portas: 3001 para a API principal, a experiência do usuário e a autenticação, e 3002 para o console de administração. Direcione o tráfego dos usuários para a porta 3001 e o tráfego administrativo para a porta 3002, de acordo com a versão. Encerre o HTTPS com Caddy ou Nginx, encaminhe os cabeçalhos de nome de host e protocolo e mantenha privadas as duas portas do contêiner. Quando possível, use um nome de host separado para o console e uma restrição de acesso adicional.

Teste os URIs de redirecionamento, a segurança dos cookies e a renovação dos certificados. Os clientes OAuth rejeitam pequenas diferenças no nome do host ou no esquema, portanto use exatamente as URLs HTTPS configuradas no Logto. Defina TRUST_PROXY_HEADER=1 no ambiente ao executar o Logto atrás de um proxy reverso. Sem isso, a URL do emissor OIDC será http://127.0.0.1:3001 por padrão.

Etapa 5, Primeiro acesso e configuração inicial

Abra o console protegido e crie o primeiro ambiente de identidade ou organização. Cadastre uma aplicação de teste, configure seu URI de redirecionamento e crie um usuário de teste. Verifique o início e o encerramento da sessão, a renovação de tokens e o retorno de um ambiente descartável.

Mantenha os IDs de cliente na configuração da aplicação e os segredos de cliente no servidor. Habilite somente os conectores sociais e escopos necessários. Revise as políticas de convite de usuários e senhas antes de cadastrar usuários reais.

Manutenção

Faça backup do PostgreSQL e de todos os segredos do Logto em conjunto. Teste a restauração de um ambiente de identidade em outro servidor. Atualize o Logto pelo processo compatível com a versão, monitore os logs de migração e verifique o fluxo completo de início de sessão após cada atualização.

Monitore logins com falha, conexões ao banco de dados, espaço em disco e vencimento dos certificados. Nunca tente resolver um problema de login desativando o HTTPS ou expondo publicamente o PostgreSQL.