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 de ambiente 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 como 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').

HTTPS​

Você pode usar 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 em seu servidor, por exemplo Nginx ou Apache, você precisa mapear as portas 3001 e 3002 separadamente nas configurações do 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 o Logto confiar 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 <caminho-para-seu-certificado-do-endpoint-auth>;
  ssl_certificate_key <caminho-para-sua-chave-do-endpoint-auth>
  ...
}

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 <caminho-para-seu-certificado-do-endpoint-admin>;
  ssl_certificate_key <caminho-para-sua-chave-do-endpoint-admin>
  ...
}

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. É fortemente 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. Recomendamos compartilhar essa pasta entre múltiplas instâncias do Logto; você precisa montar a pasta packages/core/connectors no container e rodar npm run cli connector add -- --official para implantar os conectores.

Aqui está um exemplo mínimo de deployment para Kubernetes:

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: logto
  namespace: default
spec:
  template:
    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 rodamos 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​

Semelhante aos 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.