본문으로 건너뛰기

배포 및 구성

이전 글에서는 Logto 빠르게 시작하기의 기본 사항을 다루었습니다. 이번 글에서는 프로덕션 환경에서 Logto를 배포할 때의 모범 사례와 상세한 구성 단계를 중점적으로 다룹니다.

환경 변수​

데모(docker-compose.yml)에서는 미리 생성된 환경 변수 프리셋을 사용하지만, 실제 환경에서는 반드시 본인만의 값으로 교체하고 여러 Logto 인스턴스 간에 일관성을 유지해야 합니다.

환경 변수는 직접 설정하거나, Logto 프로젝트 루트에 .env 파일을 둘 수 있습니다. Docker로 테스트할 경우, 이미지에서 생성된 .env 파일이 /etc/logto에 있으니 참고하세요.

필수 항목​

  • DB_URL Logto 데이터베이스용 Postgres DSN.
  • DATABASE_STATEMENT_TIMEOUT (v1.36.0+) PostgreSQL statement_timeout (밀리초 단위). 숫자 문자열(예: 5000) 또는 PgBouncer/RDS Proxy용 DISABLE_TIMEOUT 사용. 자세한 내용은 구성 참고.
  • PORT Logto가 리스닝하는 포트. 기본값은 3001.
  • ENDPOINT 프로덕션 환경에서 커스텀 도메인으로 URL을 지정할 수 있습니다 (예: ENDPOINT=https://logto.domain.com). 이 값은 OIDC 발급자 식별자에도 영향을 줍니다.

관리 콘솔 활성화

  • ADMIN_PORT Logto 관리 콘솔이 리스닝하는 포트. 기본값은 3002.
  • ADMIN_ENDPOINT 프로덕션 환경에서 커스텀 도메인으로 URL을 지정할 수 있습니다 (예: ADMIN_ENDPOINT=https://admin.domain.com). 이 값은 관리 콘솔 리디렉션 URI에도 영향을 줍니다.

관리 콘솔 비활성화

  • ADMIN_DISABLE_LOCALHOST 값을 1 또는 true로 설정하면 관리 콘솔 포트가 닫힙니다. ADMIN_ENDPOINT가 설정되지 않은 경우, 관리 콘솔이 완전히 비활성화됩니다.

환경 변수에 대한 자세한 내용은 구성을 참고하세요.

Secret Vault 활성화

  • Secret Vault를 사용하려면, SECRET_VAULT_KEK에 Key Encryption Key (KEK)의 base64 인코딩 문자열을 설정해야 합니다. 이는 Secret Vault에서 Data Encryption Key (DEK)를 암호화하는 데 사용됩니다. AES-256 (32바이트) 권장. 예시: crypto.randomBytes(32).toString('base64').

아웃바운드 HTTP 프록시​

자체 호스팅 Logto 인스턴스가 외부 서비스(예: 소셜 커넥터 API, CAPTCHA 제공자)에 접근하기 위해 HTTP 프록시를 사용해야 한다면, 환경 프록시 지원을 활성화하고 표준 프록시 변수를 설정하세요.

예를 들어, Docker Compose 설정의 Logto 서비스에 다음 환경 변수를 추가하세요:

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 환경 프록시 지원을 활성화합니다. Node.js 22에서는 22.21.0 이상 버전이 필요합니다.
  • HTTP_PROXY HTTP 요청용 프록시를 지정합니다.
  • HTTPS_PROXY HTTPS 요청용 프록시를 지정합니다. 프록시 URL 자체는 HTTP 또는 HTTPS 모두 사용 가능합니다.
  • NO_PROXY 프록시를 사용하지 않고 직접 접근해야 하는 호스트 목록(쉼표로 구분). 내부 HTTP 엔드포인트를 반드시 포함하세요.

이 프록시 설정이 모든 아웃바운드 요청에 적용되는 것은 아닐 수 있습니다.

HTTPS​

Node.js에서 직접 HTTPS를 제공하거나, Node.js 앞단에 HTTPS 프록시 / 로드 밸런서를 설정할 수 있습니다. 자세한 내용은 HTTPS 활성화를 참고하세요.

리버스 프록시​

서버에서 리버스 프록시(예: Nginx, Apache)를 사용하려면, 3001과 3002 포트를 각각 프록시 패스 설정에서 매핑해야 합니다. Nginx를 사용하는 경우, Logto 인증 엔드포인트는 3001 포트, Logto 관리 콘솔은 3002 포트에서 동작한다고 가정하고, nginx.conf에 다음 설정을 추가하세요:

Logto가 전달된 헤더를 신뢰하도록 TRUST_PROXY_HEADER=1을 설정하세요. 퍼블릭 URL에서 비표준 포트를 유지하려면 Host와 X-Forwarded-Host 모두에 $http_host를 사용하세요.

server {
  listen 443 ssl;
  server_name <your_endpoint_url>; // 예: auth.your-domain.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>
  ...
}

관리 콘솔에도 유사한 설정을 추가하세요:

server {
  listen 443 ssl;
  server_name <your_admin_endpoint_url>; // 예: admin.your-domain.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>
  ...
}

Nginx 설정을 다시 불러와 최신 변경 사항을 적용하세요:

nginx -s reload

이제 준비가 완료되었습니다. 브라우저에서 https://admin.your-domain.com에 접속하면 Logto 환영 페이지를 볼 수 있습니다.

컨테이너화​

프로덕션 환경에서는 Docker를 사용해 Logto를 컨테이너화할 수 있습니다. 프로젝트 루트 디렉터리에서 Dockerfile을 찾을 수 있습니다. 여러 Logto 인스턴스를 실행하거나, 예를 들어 Kubernetes 클러스터에 Logto를 배포하려면 추가로 수행해야 할 단계가 있습니다.

데이터베이스 설정​

Logto용 Postgres 데이터베이스를 준비하세요. 데이터베이스 초기화는 Logto CLI를 사용하는 것이 강력히 권장됩니다.

npm run cli db seed -- --swe

자세한 내용은 Logto CLI를 참고하세요.

에어갭 또는 오프라인 설치:

배포 환경에서 api.pwnedpasswords.com에 접근할 수 없다면, logto init 또는 npm run cli db seed에 --disable-admin-pwned-password-check를 추가하세요. 그러면 최초 관리자 가입 시 Have I Been Pwned 침해 검사에서 멈추지 않습니다. 자세한 내용은 에어갭 또는 오프라인 배포용 시드를 참고하세요.

공유 커넥터 폴더​

기본적으로 Logto는 core 폴더의 루트에 connectors 폴더를 생성합니다. 공식 Docker 이미지에는 이미 공식 커넥터가 이 폴더에 포함되어 있으므로, 공식 커넥터만 사용할 경우 별도로 공유할 필요가 없습니다.

이미지에 포함되지 않은 커넥터(예: 자체 커넥터)가 필요하다면, 여러 Logto 인스턴스 간에 해당 폴더를 공유하는 것이 좋습니다. packages/core/connectors 폴더를 컨테이너에 마운트하고, npm run cli connector add -- --official 명령으로 공식 커넥터를 배포한 뒤, 동일 폴더에 자체 커넥터를 추가하세요. 이 폴더에 볼륨을 마운트하면 이미지에 포함된 커넥터가 숨겨지므로, 공식 커넥터를 다시 추가해야 하며, 이때 npm 레지스트리 접근이 필요합니다.

Kubernetes용 최소 예시 deployment는 다음과 같습니다:

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

이 예시에서는 빈 디렉터리를 볼륨으로 생성해 컨테이너에 마운트합니다. 그리고 init 컨테이너에서 npm run cli connector add -- --official 명령을 실행해 커넥터를 다운로드합니다. 마지막으로 모든 컨테이너가 공식 커넥터가 포함된 동일한 커넥터 폴더를 공유하게 됩니다.

노트:

이것은 예시 yaml이며, Logto를 실행하려면 환경 변수 설정이 필요합니다.

프로덕션 환경에서는 "empty dir" 볼륨을 영구 볼륨으로 교체하고, "init" 작업은 환경에 맞게 직접 수행하세요.

데이터베이스 변경​

커넥터와 마찬가지로, 데이터베이스 변경 작업도 단일 인스턴스에서 실행해야 합니다. 작업(Job)을 사용해 변경 스크립트를 실행할 수 있습니다.

비상호작용 환경에서 변경 작업을 실행할 때는 CI=true 환경 변수가 필요합니다.

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

변경 명령에 대한 자세한 내용은 데이터베이스 변경을 참고하세요.