Tự lưu trữ Intlayer (Self-Hosting)

Intlayer có thể chạy trên cơ sở hạ tầng của riêng bạn mà không cần tài khoản Intlayer Cloud. Ba cấu hình được cung cấp, tất cả đều có thể thiết lập bằng cùng một trình cài đặt (install.sh, install.ps1 trên Windows, hoặc npx intlayer init infra):

Table of Contents

Hình ảnh và Gói đã xuất bản

Cả ba hình ảnh đều được xây dựng từ cùng một tệp docker/selfhost/Dockerfile và được xuất bản theo từng bản phát hành. Stack Compose cũng kéo các hình ảnh chính thức mongo:8, redis:8-alpine và quay.io/minio/minio.

Thiết lập

Trình cài đặt sẽ hỏi cấu hình bạn mong muốn, kiểm tra các điều kiện tiên quyết (đề xuất cài đặt Docker), ghi tệp môi trường với các secret đã được tạo sẵn và kéo các hình ảnh. Nó không tự khởi động bất cứ điều gì: các chế độ Docker yêu cầu cấu hình trình gửi thư trước, vì vậy nó kết thúc bằng việc in lệnh cần chạy. Việc chạy lại là an toàn: tệp môi trường hiện có sẽ không bao giờ bị ghi đè, điều này cũng làm cho nó trở thành phương thức nâng cấp.

curl -fsSL https://intlayer.org/install.sh | sh -s -- --mode desktop

$env:INTLAYER_MODE = "desktop"; irm https://intlayer.org/install.ps1 | iex

npx intlayer init infra --mode desktop

                ┌─────────────────────────────┐
 browser ──────▶ │  app  (TanStack Start)  :3000│ ──┐
 (localhost)    └─────────────────────────────┘   │ VITE_BACKEND_URL (baked at build)
                ┌─────────────────────────────┐   │
                │  backend (Fastify/Bun)  :3100│ ◀─┘
                └──────────────┬──────────────┘
          ┌──────────┬─────────┼──────────────┐
          ▼          ▼         ▼               ▼
      mongo:27017  redis:6379  minio:9000   Chromium
      /data/mongo  /data/redis /data/minio  (in-image)
      (1-node RS)              minio:9001

curl -fsSL https://intlayer.org/install.sh | sh -s -- --mode docker

$env:INTLAYER_MODE = "docker"; irm https://intlayer.org/install.ps1 | iex

npx intlayer init infra --mode docker

# Option A: Resend
RESEND_API_KEY=<your-resend-key>

# Option B: SMTP (takes over from Resend as soon as MAIL_SMTP_HOST is set)
MAIL_SMTP_HOST=smtp.example.com
MAIL_SMTP_PORT=587
MAIL_SMTP_USER=<user>
MAIL_SMTP_PASSWORD=<password>
MAIL_FROM=Intlayer <no-reply@example.com>

docker run -d --name intlayer \
  --restart unless-stopped \
  -p 3000:3000 -p 3100:3100 -p 9000:9000 -p 9001:9001 \
  -v intlayer-data:/data \
  --env-file ./intlayer.env \
  intlayer/cms-all:latest

docker run -d --name intlayer `
  --restart unless-stopped `
  -p 3000:3000 -p 3100:3100 -p 9000:9000 -p 9001:9001 `
  -v intlayer-data:/data `
  --env-file ./intlayer.env `
  intlayer/cms-all:latest

# Backup (stop the container first so MongoDB's files are consistent)
docker stop intlayer
docker run --rm -v intlayer-data:/data -v "$(pwd)":/backup busybox tar czf /backup/intlayer-data.tar.gz /data
docker start intlayer

# Restore
docker run --rm -v intlayer-data:/data -v "$(pwd)":/backup busybox tar xzf /backup/intlayer-data.tar.gz -C /

                ┌───────────────────┐
 browser ──────▶ │  app        :3000 │ ── SSR ──▶ http://backend:3100
 (localhost)    └───────────────────┘
                ┌───────────────────┐
 browser ──────▶ │  backend    :3100 │
 (localhost)    └─────────┬─────────┘
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
     mongo:27017     redis:6379      minio:9000 ◀── browser (assets)
     (1-node RS)                     minio:9001

curl -fsSL https://intlayer.org/install.sh | sh -s -- --mode compose

mkdir intlayer && cd intlayer
curl -fsSLO https://raw.githubusercontent.com/aymericzip/intlayer/main/docker/selfhost/docker-compose.yml
curl -fsSL  https://raw.githubusercontent.com/aymericzip/intlayer/main/docker/selfhost/.env.template -o .env
# fill in BETTER_AUTH_SECRET and S3_SECRET_ACCESS_KEY (openssl rand -hex 32)

$env:INTLAYER_MODE = "compose"; irm https://intlayer.org/install.ps1 | iex

mkdir intlayer; cd intlayer
irm https://raw.githubusercontent.com/aymericzip/intlayer/main/docker/selfhost/docker-compose.yml -OutFile docker-compose.yml
irm https://raw.githubusercontent.com/aymericzip/intlayer/main/docker/selfhost/.env.template -OutFile .env
# fill in BETTER_AUTH_SECRET and S3_SECRET_ACCESS_KEY

npx intlayer init infra --mode compose

cd intlayer && docker compose up -d

services:
  backend:
    environment:
      MONGODB_URI: mongodb+srv://user:password@cluster0.xxxxx.mongodb.net/intlayer
      REDIS_URL: rediss://default:password@redis.example.com:6380
      S3_ENDPOINT: https://s3.eu-west-1.amazonaws.com
      S3_PUBLIC_URL: https://intlayer-assets.s3.eu-west-1.amazonaws.com

cd docker/selfhost
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

# Backup one volume (repeat for intlayer_redis-data and intlayer_minio-data)
docker compose stop
docker run --rm -v intlayer_mongo-data:/data -v "$(pwd)":/backup busybox tar czf /backup/mongo-data.tar.gz /data
docker compose start

# Upgrade, volumes are kept
docker compose pull && docker compose up -d

Cài đặt của Trình cài đặt

Nếu không có --mode (hoặc INTLAYER_MODE), trình cài đặt sẽ nhắc menu: desktop, docker (all-in-one), hoặc compose. Nó cũng đọc một số biến môi trường; hãy truyền chúng vào shell thay vì curl vì lệnh này được truyền qua đường ống (piped):

curl -fsSL https://intlayer.org/install.sh | INTLAYER_COMPOSE_DIR=./cms sh -s -- --mode compose

$env:INTLAYER_MODE = "compose"; $env:INTLAYER_COMPOSE_DIR = ".\cms"; irm https://intlayer.org/install.ps1 | iex

Các biến cổng chỉ thay đổi phía máy chủ của ánh xạ. Các hình ảnh đã xuất bản có http://localhost:3000, http://localhost:3100, http://localhost:9000 được biên dịch sẵn vào gói bảng điều khiển, vì vậy hãy giữ nguyên các giá trị mặc định trừ khi bạn tự xây dựng hình ảnh, xem Giới hạn.

Thiết lập lần đầu

Khi mở bảng điều khiển trên một phiên bản mới (cơ sở dữ liệu trống), bạn sẽ tự động được chuyển hướng đến trang /init:

1. Tạo tài khoản đầu tiên. Vì bộ sưu tập người dùng đang trống, tài khoản này sẽ tự động được nâng cấp thành Super Admin.
2. Một email xác minh sẽ được gửi qua Resend hoặc relay SMTP của bạn. Xác minh email là bắt buộc, đó là lý do tại sao phải cấu hình trình gửi thư trước khi khởi chạy.
3. Nhấp vào liên kết trong email và đăng nhập.

Sau khi đã có quản trị viên, /init sẽ chuyển hướng đến trang đăng nhập thông thường.

Biến môi trường

Cả hai chế độ Docker đều đọc cùng một tệp (tệp intlayer.env cho container hoặc .env cho Compose) được tạo từ docker/selfhost/.env.template.

Bắt buộc

Được cố định bởi việc triển khai

Các biến này được đặt bởi hình ảnh (all-in-one) hoặc bởi tệp compose, và chỉ cần ghi đè cho một cấu trúc triển khai không chuẩn. DOMAIN, APP_URL, BACKEND_URL và S3_PUBLIC_URL là ngoại lệ: khi được đặt trong tệp env, chúng được ưu tiên ở cả hai chế độ (xem Tên miền tùy chỉnh).

Dịch vụ Compose app nhận thêm INTLAYER_BACKEND_INTERNAL_URL=http://backend:3100: trình duyệt tiếp cận API tại localhost:3100, nhưng quá trình kết xuất phía máy chủ chạy bên trong mạng Compose nên nó phải sử dụng tên dịch vụ.

Tên miền tùy chỉnh

Backend đọc các URL công khai của nó khi chạy, nhưng bảng điều khiển đã biên dịch sẵn chúng: các hình ảnh đã xuất bản intlayer/cms-frontend và intlayer/cms-all chỉ hoạt động trên http://localhost:3000. Vì vậy, phục vụ Intlayer trên tên miền của riêng bạn cần hai thứ, cả hai đều được trình cài đặt chuẩn bị khi bạn trả lời câu hỏi về tên miền:

1. Bốn biến trong tệp env, được backend đọc (cookie, liên kết email, callback OAuth, URL tài nguyên) và được docker-compose.build.yml dùng làm đối số build:

   intlayer.env

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   DOMAIN=example.org                          # cookie domain, parent of the hosts below
   APP_URL=https://cms.example.org
   BACKEND_URL=https://back.example.org
   S3_PUBLIC_URL=https://s3.example.org/intlayer
   

2. Một hình ảnh bảng điều khiển được build với các URL đó. Docker build trực tiếp từ kho lưu trữ, không cần bản sao:

   sh

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   # Docker Compose: the override reads the build args from .env
   docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
   
   # All-in-one
   docker build -f docker/selfhost/Dockerfile \
     --build-arg VITE_DOMAIN=example.org \
     --build-arg VITE_SITE_URL=https://cms.example.org \
     --build-arg VITE_IDE_URL=https://cms.example.org \
     --build-arg VITE_BACKEND_URL=https://back.example.org \
     -t intlayer/cms-all:custom \
     https://github.com/aymericzip/intlayer.git#main
   

Sau đó đặt một reverse proxy có TLS phía trước container: cms.example.org → cổng 3000, back.example.org → 3100, s3.example.org → 9000. Ba máy chủ phải có chung hậu tố DOMAIN, vì cookie phiên được giới hạn trong phạm vi đó.

Tùy chọn (các tính năng sẽ giảm cấp nhẹ nhàng khi không được đặt)

Trình gửi thư toàn cục (Mailer)

Tất cả các email giao dịch, bao gồm các email ngoài tổ chức như đặt lại mật khẩu và magic links, đều đi qua một trong hai cổng truyền tải toàn cục:

• Resend: Sử dụng RESEND_API_KEY.
• SMTP: Sử dụng các biến MAIL_SMTP_*. Đặt MAIL_SMTP_HOST sẽ lập tức chọn giao thức SMTP và bỏ qua RESEND_API_KEY.

MAIL_PROVIDER chỉ cần thiết khi muốn buộc sử dụng một phương thức truyền tải nếu cả hai đều được cấu hình (ví dụ: MAIL_PROVIDER=resend để giữ Resend khi máy chủ SMTP tồn tại).

Thứ tự ưu tiên: Trình gửi thư riêng của tổ chức (được cấu hình từ bảng điều khiển Tổ chức) sẽ ghi đè trình gửi thư toàn cục, và trình gửi thư toàn cục sẽ ghi đè khóa Resend mặc định.

Kết nối Dự án Intlayer của bạn

Sau khi stack đang chạy, hãy cấu hình dự án của bạn để trỏ đến backend và bảng điều khiển tự lưu trữ thay vì intlayer.org.

Cấu hình dự án

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    clientId: process.env.INTLAYER_CLIENT_ID,
    clientSecret: process.env.INTLAYER_CLIENT_SECRET,

    /**
     * URL of the self-hosted CMS dashboard.
     * Default: https://app.intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL, // e.g. http://localhost:3000

    /**
     * URL of the self-hosted backend API.
     * Default: https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL, // e.g. http://localhost:3100
  },
};

export default config;

Set the environment variables in your project's .env:

INTLAYER_CMS_URL=http://localhost:3000
INTLAYER_BACKEND_URL=http://localhost:3100
INTLAYER_CLIENT_ID=<your-client-id>
INTLAYER_CLIENT_SECRET=<your-client-secret>

Tạo thông tin đăng nhập truy cập trong bảng điều khiển tự lưu trữ của bạn tại Dự án → Khóa truy cập (http://localhost:3000/projects).

SDK @intlayer/api

Khi sử dụng SDK @intlayer/api theo phương thức lập trình, hãy truyền backendURL một cách rõ ràng:

import { createIntlayerCMS } from "@intlayer/api";
import { dictionaryEndpoint } from "@intlayer/api/dictionary";

const cms = createIntlayerCMS({
  editor: {
    clientId: process.env.INTLAYER_CLIENT_ID,
    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
    backendURL: process.env.INTLAYER_BACKEND_URL, // http://localhost:3100
  },
});

const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();

Giới hạn

• Tên miền tùy chỉnh đồng nghĩa với việc build lại. Tất cả các URL VITE_* hướng đến trình duyệt đều được nhúng sẵn vào bảng điều khiển tại thời điểm xây dựng, và các hình ảnh đã xuất bản (cùng với ứng dụng desktop) có sẵn các giá trị localhost / Intlayer Cloud. Mặc định, bảng điều khiển phải được truy cập tại http://localhost:3000, API tại :3100 và MinIO tại :9000; ánh xạ lại cổng của máy chủ cũng có tác dụng tương tự. Trình cài đặt chuẩn bị mọi thứ để build lại từ kho lưu trữ khi bạn cung cấp tên miền (xem Tên miền tùy chỉnh), nhưng bản thân quá trình build mất vài phút. Việc trỏ ứng dụng desktop đến backend tự lưu trữ không được hỗ trợ.
• Gửi thư yêu cầu một mailer hoạt động. Thiết lập lần đầu bắt buộc phải xác minh email, vì vậy phải định cấu hình RESEND_API_KEY hoặc một relay SMTP (MAIL_SMTP_*). Sau khi quản trị viên đầu tiên đăng nhập, các tổ chức cũng có thể cấu hình mailer SMTP hoặc Resend riêng của họ từ bảng điều khiển.
• Ứng dụng desktop yêu cầu Node.js trên máy để khởi động máy chủ nhúng.
• Không có trợ lý tài liệu. Trợ lý tài liệu AI của intlayer.org (/api/ai/ask, /api/search/doc) dựa trên khoảng 130 MB embedding tài liệu được tính toán trước mà các hình ảnh tự lưu trữ không đi kèm; hai route này không được đăng ký ở chế độ tự lưu trữ. Các tính năng AI riêng của bảng điều khiển (dịch, kiểm tra, tự động hoàn thành, chat) không bị ảnh hưởng và chỉ cần OPENAI_API_KEY.

Liên kết hữu ích

• Tài liệu Intlayer CMS
• Tham chiếu cấu hình
• CMS SDK: @intlayer/api
• Bản phát hành ứng dụng Desktop
• Docker Hub: intlayer/cms-all, intlayer/cms-frontend, intlayer/cms-backend, mirror GHCR: ghcr.io/aymericzip/intlayer/
• docker/selfhost/: Dockerfile, docker-compose.yml, .env.template