ข้ามไปยังเนื้อหาหลัก

การปรับใช้และการตั้งค่า

ในบทความก่อนหน้านี้ เราได้พูดถึงพื้นฐานของ เริ่มต้นใช้งาน Logto อย่างรวดเร็ว บทความนี้จะลงลึกยิ่งขึ้น โดยเน้นแนวปฏิบัติที่ดีที่สุดและขั้นตอนการตั้งค่ารายละเอียดสำหรับการปรับใช้ Logto ในสภาพแวดล้อม production

ตัวแปรสภาพแวดล้อม (Environment variables)​

เราใช้ชุดตัวแปรสภาพแวดล้อมที่สร้างขึ้นอัตโนมัติในเดโม (docker-compose.yml) ซึ่งคุณควรเปลี่ยนเป็นของคุณเองและรักษาความสอดคล้องกันระหว่าง Logto หลายอินสแตนซ์

คุณสามารถตั้งค่าตัวแปร env ได้โดยตรงหรือใส่ไฟล์ .env ไว้ใน root ของโปรเจกต์ Logto หากคุณกำลังทดสอบด้วย Docker ให้ตรวจสอบไฟล์ .env ที่สร้างโดย image ใน /etc/logto

สิ่งจำเป็น (Essentials)​

  • DB_URL Postgres DSN สำหรับฐานข้อมูล Logto
  • DATABASE_STATEMENT_TIMEOUT (v1.36.0+) PostgreSQL statement_timeout หน่วยเป็นมิลลิวินาที ใช้เป็น string ตัวเลข (เช่น 5000) หรือ DISABLE_TIMEOUT สำหรับ PgBouncer/RDS Proxy ดูรายละเอียดที่ Configuration
  • PORT พอร์ตที่ Logto รับฟัง ค่าเริ่มต้น 3001
  • ENDPOINT คุณสามารถระบุ URL พร้อมโดเมนของคุณเองสำหรับ production (เช่น ENDPOINT=https://logto.domain.com) ค่านี้จะมีผลกับ OIDC issuer identifier ด้วย

เปิดใช้งาน Admin Console

  • ADMIN_PORT พอร์ตที่ Logto Admin Console รับฟัง ค่าเริ่มต้น 3002
  • ADMIN_ENDPOINT คุณสามารถระบุ URL พร้อมโดเมนของคุณเองสำหรับ production (เช่น ADMIN_ENDPOINT=https://admin.domain.com) ค่านี้จะมีผลกับค่า Admin Console Redirect URIs ด้วย

ปิดใช้งาน Admin Console

  • ADMIN_DISABLE_LOCALHOST ตั้งค่าเป็น 1 หรือ true เพื่อปิดพอร์ตของ Admin Console หาก ADMIN_ENDPOINT ไม่ถูกตั้งค่า จะปิด Admin Console ทั้งหมด

ดูรายละเอียดเพิ่มเติมเกี่ยวกับตัวแปรสภาพแวดล้อมได้ที่ Configuration

เปิดใช้งาน Secret Vault

  • หากต้องการใช้ Secret Vault คุณต้องตั้งค่า SECRET_VAULT_KEK เป็น string ที่เข้ารหัส base64 ของ Key Encryption Key (KEK) ของคุณ ใช้สำหรับเข้ารหัส Data Encryption Keys (DEK) ใน Secret Vault แนะนำให้ใช้ AES-256 (32 ไบต์) ตัวอย่าง: crypto.randomBytes(32).toString('base64')

Outbound HTTP proxy​

หาก Logto ที่คุณโฮสต์เองต้องใช้ HTTP proxy เพื่อเชื่อมต่อกับบริการภายนอก เช่น API ของตัวเชื่อมต่อโซเชียล หรือผู้ให้บริการ CAPTCHA ให้เปิดใช้งาน environment proxy และตั้งค่าตัวแปร proxy มาตรฐาน

ตัวอย่าง เพิ่มตัวแปรสภาพแวดล้อมต่อไปนี้ในบริการ Logto ในไฟล์ 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 เปิดใช้งาน environment proxy ต้องใช้ Node.js 22 เวอร์ชัน 22.21.0 ขึ้นไป
  • HTTP_PROXY ระบุ proxy สำหรับ HTTP requests
  • HTTPS_PROXY ระบุ proxy สำหรับ HTTPS requests โดย URL ของ proxy เองจะเป็น HTTP หรือ HTTPS ก็ได้
  • NO_PROXY รายการ host ที่คั่นด้วย comma ซึ่งควรเชื่อมต่อโดยตรง ให้รวม endpoint HTTP ภายในที่ไม่ควรผ่าน proxy ด้วย

โปรดทราบว่าการตั้งค่า proxy นี้อาจไม่มีผลกับทุก outbound request

HTTPS​

คุณสามารถใช้ Node.js เพื่อให้บริการ HTTPS โดยตรง หรือจะตั้งค่า HTTPS proxy / balancer ไว้หน้าตัว Node.js ก็ได้ ดูรายละเอียดที่ Enabling HTTPS

Reverse proxy​

หากคุณต้องการใช้ reverse proxy บนเซิร์ฟเวอร์ของคุณ เช่น Nginx หรือ Apache คุณต้อง map พอร์ต 3001 และ 3002 แยกกันใน proxy pass สมมติว่าคุณใช้ Nginx, Logto auth endpoint รันที่พอร์ต 3001 และ Logto admin console รันที่ 3002 ให้ใส่ config ต่อไปนี้ใน nginx.conf:

ตั้งค่า TRUST_PROXY_HEADER=1 ให้ Logto เชื่อ header ที่ถูกส่งต่อ ใช้ $http_host สำหรับทั้ง Host และ X-Forwarded-Host เพื่อรักษาพอร์ตที่ไม่มาตรฐานใน public URL

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>
  ...
}

จากนั้นเพิ่ม config ลักษณะเดียวกันสำหรับ admin console ของคุณ:

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>
  ...
}

รีโหลด config ของ Nginx เพื่อให้การเปลี่ยนแปลงมีผล:

nginx -s reload

เรียบร้อยแล้ว เปิดเบราว์เซอร์และไปที่ https://admin.your-domain.com คุณควรเห็นหน้า welcome ของ Logto

การทำให้เป็นคอนเทนเนอร์ (Containerization)​

สำหรับ production คุณสามารถใช้ Docker เพื่อทำ Logto ให้เป็นคอนเทนเนอร์ คุณจะพบ Dockerfile ใน root ของโปรเจกต์ หากคุณต้องการรัน Logto หลายอินสแตนซ์ เช่น ปรับใช้ Logto ใน Kubernetes cluster จะมีขั้นตอนเพิ่มเติมที่ต้องทำ

การตั้งค่าฐานข้อมูล (Database setup)​

เตรียมฐานข้อมูล Postgres สำหรับ Logto ขอแนะนำอย่างยิ่งให้ใช้ Logto CLI เพื่อ initialize ฐานข้อมูล

npm run cli db seed -- --swe

ดูรายละเอียดเพิ่มเติมได้ที่ Logto CLI

สำหรับการติดตั้งแบบ air-gapped หรือออฟไลน์:

หากสภาพแวดล้อมที่คุณปรับใช้ไม่สามารถเข้าถึง api.pwnedpasswords.com ให้เพิ่ม --disable-admin-pwned-password-check ใน logto init หรือ npm run cli db seed เพื่อไม่ให้การสมัครแอดมินครั้งแรกค้างที่การตรวจสอบ breach ของ Have I Been Pwned ดูรายละเอียดที่ Seed for air-gapped or offline deployments

โฟลเดอร์ connectors ที่ใช้ร่วมกัน (Shared connectors folder)​

โดยปกติ Logto จะสร้างโฟลเดอร์ connectors ใน root ของโฟลเดอร์ core Docker image อย่างเป็นทางการได้รวมตัวเชื่อมต่ออย่างเป็นทางการไว้ในโฟลเดอร์นี้แล้ว ดังนั้นหากคุณใช้เฉพาะตัวเชื่อมต่ออย่างเป็นทางการ ไม่จำเป็นต้องแชร์โฟลเดอร์นี้

หากคุณต้องการตัวเชื่อมต่อที่ไม่ได้รวมอยู่ใน image เช่น ตัวเชื่อมต่อของคุณเอง แนะนำให้แชร์โฟลเดอร์นี้ระหว่าง Logto หลายอินสแตนซ์ ให้ mount โฟลเดอร์ packages/core/connectors ไปยัง container และรัน npm run cli connector add -- --official เพื่อ deploy ตัวเชื่อมต่ออย่างเป็นทางการ จากนั้นเพิ่มตัวเชื่อมต่อของคุณเองในโฟลเดอร์เดียวกัน การ mount volume ไปยังโฟลเดอร์นี้จะซ่อนตัวเชื่อมต่อที่รวมอยู่ใน image ดังนั้นต้องเพิ่มตัวเชื่อมต่ออย่างเป็นทางการใหม่ ซึ่งต้องเข้าถึง npm registry

ตัวอย่าง deployment ขั้นต่ำสำหรับ 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

ในตัวอย่างนี้ เราสร้างไดเรกทอรีว่างเป็น volume และ mount ไปยัง container จากนั้นรัน npm run cli connector add -- --official ใน init container เพื่อดาวน์โหลดตัวเชื่อมต่อ สุดท้ายทุก container จะใช้โฟลเดอร์ connectors เดียวกันที่มีตัวเชื่อมต่ออย่างเป็นทางการอยู่แล้ว

บันทึก:

นี่คือตัวอย่าง yaml ในการรัน Logto คุณต้องตั้งค่า envs ให้ถูกต้อง

สำหรับ production คุณสามารถเปลี่ยน volume แบบ "empty dir" เป็น persistent volume และทำ "init" job ด้วยวิธีของคุณเองได้เลย

การเปลี่ยนแปลงฐานข้อมูล (Database alteration)​

เช่นเดียวกับ connectors การเปลี่ยนแปลงฐานข้อมูลต้องรันในอินสแตนซ์เดียว คุณสามารถใช้ job เพื่อรันสคริปต์ alteration

ต้องตั้งค่าตัวแปรสภาพแวดล้อม CI=true เมื่อ alteration รันแบบ non-interactive

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

ดูรายละเอียดเกี่ยวกับคำสั่ง alteration ได้ที่ Database alteration