본문으로 건너뛰기

배포 및 구성

이전 글에서는 Logto 빠르게 시작하기의 기본 사항을 다루었습니다. 이 글에서는 프로덕션 환경에서 Logto를 배포하기 위한 모범 사례와 상세한 구성 단계에 대해 더 깊이 다룹니다.

환경 변수​

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

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

필수 항목​

  • DB_URL Logto 데이터베이스용 Postgres DSN.
  • 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_KEK에 Key Encryption Key (KEK)의 base64 인코딩 문자열을 설정해야 합니다. 이 값은 시크릿 볼트 내 Data Encryption Key (DEK)를 암호화하는 데 사용됩니다. AES-256 (32바이트)을 권장합니다. 예시: crypto.randomBytes(32).toString('base64').

HTTPS​

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

리버스 프록시​

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

server {
  listen 443 ssl;
  server_name <your_endpoint_url>; // 예: auth.your-domain.com
  ...

  location / {
    proxy_set_header Host $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 https;

    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 $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 https;

    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는 core 폴더의 루트에 connectors 폴더를 생성합니다. 여러 Logto 인스턴스 간에 이 폴더를 공유하는 것을 권장합니다. 컨테이너에 packages/core/connectors 폴더를 마운트하고, npm run cli connector add -- --official 명령어로 커넥터를 배포하세요.

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

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

이 예시에서는 빈 디렉터리를 볼륨으로 생성해 컨테이너에 마운트합니다. 그리고 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

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