Tự host Intlayer

Intlayer có thể chạy hoàn toàn trên hạ tầng của riêng bạn — không yêu cầu tài khoản Intlayer Cloud. Chỉ một lệnh duy nhất sẽ khởi động một stack sẵn sàng cho production:

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

Trình cài đặt sẽ tải xuống docker-compose.yml và .env, tự động tạo các secret cần thiết, và khởi động tất cả các container với docker compose up -d.

Mục lục

Kiến trúc

                ┌─────────────────────────────┐ browser ──────▶ │  app  (TanStack Start)  :3000│ ──┐                └─────────────────────────────┘   │ VITE_BACKEND_URL                ┌─────────────────────────────┐   │                │  backend (Fastify/Bun)  :3100│ ◀─┘                └──────────────┬──────────────┘          ┌──────────┬─────────┼──────────┬───────────┐          ▼          ▼         ▼          ▼           ▼     mongo:27017  redis:6379  minio:9000  mailpit:1025  Chromium     (1-node RS)             (S3 API)     (SMTP)        (in-image)                             minio:9001   mailpit:8025                             (console)    (web UI)

Chromium (được sử dụng để tạo ảnh chụp màn hình Puppeteer) được đóng gói bên trong image backend — không cần container riêng.

Điều kiện tiên quyết

• Docker ≥ 24 và Docker Compose ≥ v2. Nếu thiếu một trong hai, trình cài đặt sẽ in liên kết cài đặt và thoát.
• Các cổng 3000, 3100, 8025, 9000, và 9001 phải khả dụng trên host.
• Host chạy Linux hoặc macOS (hoặc WSL2 trên Windows).

Bắt đầu nhanh

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

Những gì trình cài đặt thực hiện:

1. Kiểm tra xem docker và docker compose có tồn tại không.
2. Tải xuống docker-compose.yml và .env.example vào ./intlayer/.
3. Nếu không có .env tồn tại, sao chép file ví dụ và tạo các secret ngẫu nhiên cho BETTER_AUTH_SECRET, S3_ACCESS_KEY_ID, và S3_SECRET_ACCESS_KEY thông qua openssl rand.
4. Chạy docker compose pull + docker compose up -d.
5. In các URL: dashboard :3000, API :3100, UI email :8025, console MinIO :9001.

Sau khi stack hoạt động, mở http://localhost:3000 và tạo tài khoản đầu tiên của bạn.

Các dịch vụ

Các cổng nội bộ (mongo, redis) không được phơi bày ra host theo mặc định.

Cổng MinIO 9000 phải có thể truy cập được bởi trình duyệt vì các tài sản được tải lên (avatars, ảnh chụp màn hình) được tải trực tiếp từ S3_PUBLIC_URL=http://localhost:9000/intlayer.

Các biến môi trường

Trình cài đặt tạo ra một file .env sẵn sàng để sử dụng. Bảng dưới đây mô tả từng biến.

Bắt buộc (tự động tạo hoặc được nhắc nhở)

Tùy chọn (tính năng sẽ suy giảm khi không có)

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

Khi stack đang chạy, hãy trỏ dự án của bạn đến backend và dashboard được tự host 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 của dashboard CMS được tự host.
     * Mặc định: https://app.intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL, // ví dụ: http://localhost:3000

    /**
     * URL của API backend được tự host.
     * Mặc định: https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL, // ví dụ: http://localhost:3100
  },
};

export default config;

Thiết lập các biến môi trường trong file .env của dự án bạn:

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

Tạo thông tin truy cập trong dashboard được tự host của bạn dưới mục Projects → Access keys tại http://localhost:3000/projects.

SDK @intlayer/api

Khi sử dụng SDK @intlayer/api theo cách 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();

Nâng cấp

Chạy lại trình cài đặt trên một triển khai hiện có sẽ thực hiện nâng cấp cuốn chiếu (rolling upgrade):

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

Thao tác này sẽ kéo các image mới nhất và khởi động lại các container với docker compose pull && docker compose up -d. Các volume hiện có (mongo-data, redis-data, minio-data) được bảo toàn — không mất dữ liệu.

Để nâng cấp thủ công từ bên trong thư mục ./intlayer/:

docker compose pulldocker compose up -d

Sao lưu và phục hồi

Tất cả dữ liệu bền vững nằm trong ba Docker volume được đặt tên.

Sao lưu

docker run --rm \  -v intlayer_mongo-data:/data \  -v "$(pwd)":/backup \  busybox tar czf /backup/mongo-data.tar.gz /datadocker run --rm \  -v intlayer_redis-data:/data \  -v "$(pwd)":/backup \  busybox tar czf /backup/redis-data.tar.gz /datadocker run --rm \  -v intlayer_minio-data:/data \  -v "$(pwd)":/backup \  busybox tar czf /backup/minio-data.tar.gz /data

Phục hồi

docker run --rm \  -v intlayer_mongo-data:/data \  -v "$(pwd)":/backup \  busybox tar xzf /backup/mongo-data.tar.gz -C /# Lặp lại cho redis-data và minio-data

Sử dụng reverse proxy (Nginx / Caddy)

Đối với các triển khai production, hãy đặt một reverse proxy phía trước các container app và backend thay vì phơi bày chúng trực tiếp.

Ví dụ Nginx

server {    listen 80;    server_name cms.example.com;    location / {        proxy_pass http://localhost:3000;        proxy_set_header Host $host;        proxy_set_header X-Real-IP $remote_addr;    }}server {    listen 80;    server_name api.example.com;    location / {        proxy_pass http://localhost:3100;        proxy_set_header Host $host;        proxy_set_header X-Real-IP $remote_addr;    }}

Cập nhật các biến .env sau để khớp với các miền công khai của bạn:

BACKEND_URL=https://api.example.comAPP_URL=https://cms.example.comDOMAIN=example.comVITE_BACKEND_URL=https://api.example.comVITE_DOMAIN=example.com

Các biến VITE_* được tích hợp vào image dashboard tại thời điểm build. Nếu bạn thay đổi chúng sau khi image được build, bạn cần build lại image app (docker compose build app) hoặc sử dụng cấu hình runtime injection.

Khắc phục sự cố

Backend bị crash-loop khi khởi động lần đầu

MongoDB và Redis phải hoạt động tốt trước khi backend khởi động. File compose sử dụng depends_on với condition: service_healthy. Nếu bạn thấy backend khởi động lại liên tục, hãy kiểm tra xem healthcheck của mongo và redis có vượt qua không:

docker compose psdocker compose logs mongodocker compose logs redis

Dashboard không thể kết nối tới API

Xác minh rằng VITE_BACKEND_URL khớp với URL mà backend có thể truy cập được từ trình duyệt (không phải mạng Docker). Nếu bạn đã thay đổi cổng backend hoặc thêm reverse proxy, hãy build lại image dashboard:

docker compose build appdocker compose up -d app

Email không gửi được

Theo mặc định, tất cả email gửi đi được Mailpit thu nhận. Mở http://localhost:8025 để xem các tin nhắn đã gửi. Để gửi email thật, hãy đặt MAIL_PROVIDER=resend và RESEND_API_KEY=<your-key> trong .env, sau đó khởi động lại backend:

docker compose restart backend

Thiếu MinIO bucket

Nếu dịch vụ một lần chạy minio-init không chạy (hoặc chạy trước khi MinIO sẵn sàng), hãy tạo bucket thủ công:

docker compose run --rm minio-init

Các liên kết hữu ích

• Tài liệu Intlayer CMS
• Tham chiếu cấu hình
• CMS SDK — @intlayer/api