Pular para o conteúdo principal

Implantação e configuração

No artigo anterior, abordamos o básico de como começar rapidamente com o Logto. Este artigo aprofunda mais, focando em melhores práticas e etapas detalhadas de configuração para implantar o Logto em um ambiente de produção.

Variáveis de ambiente​

Usamos um conjunto gerado de variáveis de ambiente em nosso demo (docker-compose.yml), que você deve substituir pelas suas próprias e manter a consistência entre múltiplas instâncias do Logto.

Você pode definir as variáveis diretamente ou colocar um arquivo .env na raiz do projeto Logto. Se estiver testando com Docker, confira o .env gerado da imagem em /etc/logto.

Essenciais​

  • DB_URL O DSN do Postgres para o banco de dados do Logto.
  • DATABASE_STATEMENT_TIMEOUT (v1.36.0+) statement_timeout do PostgreSQL em milissegundos. Use uma string numérica (ex: 5000) ou DISABLE_TIMEOUT para PgBouncer/RDS Proxy. Veja Configuração para detalhes.
  • PORT A porta que o Logto escuta. Padrão 3001.
  • ENDPOINT Você pode especificar uma URL com seu domínio personalizado para produção (Ex: ENDPOINT=https://logto.domain.com). Isso também afetará o valor do identificador do emissor OIDC.

Habilitar Console de Administração

  • ADMIN_PORT A porta que o Console de Administração do Logto escuta. Padrão 3002.
  • ADMIN_ENDPOINT Você pode especificar uma URL com seu domínio personalizado para produção (Ex: ADMIN_ENDPOINT=https://admin.domain.com). Isso também afetará o valor dos URIs de redirecionamento do Console de Administração.

Desabilitar Console de Administração

  • ADMIN_DISABLE_LOCALHOST Defina como 1 ou true para fechar a porta do Console de Administração. Com ADMIN_ENDPOINT não definido, irá desabilitar completamente o Console de Administração.

Para mais detalhes sobre variáveis de ambiente, veja Configuração.

Habilitar Secret Vault

  • Para usar o Secret Vault, você precisa definir SECRET_VAULT_KEK para uma string codificada em base64 da sua Key Encryption Key (KEK). Isso é usado para criptografar as Data Encryption Keys (DEK) no Secret Vault. AES-256 (32 bytes) é recomendado. Exemplo: crypto.randomBytes(32).toString('base64').

Proxy HTTP de saída​

Se sua instância Logto auto-hospedada precisar usar um proxy HTTP para acessar serviços externos, como APIs de conectores sociais ou provedores de CAPTCHA, habilite o suporte a proxy de ambiente e configure as variáveis padrão de proxy.

Por exemplo, adicione as seguintes variáveis de ambiente ao serviço Logto na sua configuração 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 o suporte a proxy de ambiente. No Node.js 22, requer a versão 22.21.0 ou superior.
  • HTTP_PROXY especifica o proxy para requisições HTTP.
  • HTTPS_PROXY especifica o proxy para requisições HTTPS. A URL do proxy pode usar HTTP ou HTTPS.
  • NO_PROXY é uma lista separada por vírgulas de hosts que devem ser acessados diretamente. Inclua quaisquer endpoints HTTP internos que não devem usar o proxy.

Observe que essa configuração de proxy pode não ter efeito para todas as requisições de saída.

HTTPS​

Você pode usar o Node.js para servir HTTPS diretamente ou configurar um proxy / balanceador HTTPS na frente do Node.js. Veja Habilitando HTTPS para detalhes.

Proxy reverso​

Se você quiser usar proxy reverso no seu servidor, por exemplo Nginx ou Apache, você precisa mapear as portas 3001 e 3002 separadamente nas configurações de proxy pass. Supondo que você esteja usando Nginx, seu endpoint de autenticação do Logto está rodando na porta 3001 e seu console de administração do Logto está rodando na 3002, coloque a seguinte configuração no nginx.conf:

Defina TRUST_PROXY_HEADER=1 para que o Logto confie nos headers encaminhados. Use $http_host tanto para Host quanto para X-Forwarded-Host para preservar portas não padrão na URL pública.

server {
  listen 443 ssl;
  server_name <your_endpoint_url>; // ex: auth.seu-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 <path-to-your-certificate-for-auth-endpoint>;
  ssl_certificate_key <path-to-your-certificate-key-for-auth-endpoint>
  ...
}

Depois, adicione uma configuração similar para seu console de administração:

server {
  listen 443 ssl;
  server_name <your_admin_endpoint_url>; // ex: admin.seu-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 <path-to-your-certificate-for-admin-endpoint>;
  ssl_certificate_key <path-to-your-certificate-key-for-admin-endpoint>
  ...
}

Recarregue a configuração do Nginx para aplicar as últimas alterações:

nginx -s reload

Tudo pronto. Abra o navegador e acesse https://admin.seu-dominio.com, você deverá ver a página de boas-vindas do Logto.

Containerização​

Para produção, você pode usar Docker para containerizar o Logto. Você encontra o Dockerfile no diretório raiz do projeto. Se quiser rodar múltiplas instâncias do Logto, por exemplo, implantar o Logto em um cluster Kubernetes, há alguns passos adicionais que você precisa seguir.

Configuração do banco de dados​

Prepare um banco de dados Postgres para o Logto. É altamente recomendado usar o Logto CLI para inicializar o banco de dados.

npm run cli db seed -- --swe

Consulte o Logto CLI para mais detalhes.

Instalações air-gapped ou offline:

Se seu ambiente de implantação não pode acessar api.pwnedpasswords.com, adicione --disable-admin-pwned-password-check ao logto init ou npm run cli db seed para que o primeiro cadastro de admin não trave na verificação de vazamento do Have I Been Pwned. Veja Seed para implantações air-gapped ou offline para detalhes.

Pasta compartilhada de conectores​

Por padrão, o Logto criará uma pasta connectors no diretório raiz da pasta core. A imagem oficial do Docker já inclui os conectores oficiais nesta pasta, então você não precisa compartilhá-la se usar apenas conectores oficiais.

Se precisar de conectores que não estão incluídos na imagem, como seus próprios conectores, recomendamos compartilhar a pasta entre múltiplas instâncias do Logto. Monte a pasta packages/core/connectors no container e execute npm run cli connector add -- --official para implantar os conectores oficiais, depois adicione seus próprios conectores na mesma pasta. Montar um volume nesta pasta oculta os conectores incluídos na imagem, então os conectores oficiais precisam ser adicionados novamente, o que requer acesso ao registro npm.

Segue um exemplo 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

Neste exemplo, criamos um diretório vazio como volume e o montamos nos containers. Depois, executamos npm run cli connector add -- --official no init container para baixar os conectores. Por fim, cada container compartilhará a mesma pasta de conectores já com nossos conectores oficiais dentro.

nota:

Este é um exemplo de yaml, para rodar o Logto, você precisa definir as variáveis de ambiente corretamente.

Para produção, você pode substituir o volume "empty dir" por um volume persistente, e fazer o trabalho de "init" do seu próprio jeito, você sabe o que está fazendo!

Alteração do banco de dados​

Assim como os conectores, a alteração do banco de dados precisa ser executada em uma única instância. Você pode usar um job para rodar o script de alteração.

A variável de ambiente CI=true é necessária quando a alteração é executada de forma não interativa.

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

Veja Alteração do banco de dados para detalhes sobre o comando de alteração.