Intlayer 셀프 호스팅

Intlayer는 자체 인프라에서 실행할 수 있으며, Intlayer Cloud 계정이 필요하지 않습니다. 동일한 설치 프로그램(install.sh, Windows의 경우 install.ps1 또는 npx intlayer init infra)으로 설정할 수 있는 세 가지 구성이 제공됩니다:

Table of Contents

게시된 이미지 및 패키지

세 가지 이미지는 모두 동일한 docker/selfhost/Dockerfile에서 빌드되며 매 릴리스마다 게시됩니다. Compose 스택은 공식 mongo:8, redis:8-alpine, quay.io/minio/minio 이미지도 가져옵니다.

설정

설치 프로그램은 원하는 설정을 묻고 사전 요구 사항을 확인한 후(Docker 설치 제안), 이미 생성된 시크릿과 함께 환경 파일을 작성하고 이미지를 가져옵니다. 자체적으로 아무것도 시작하지 않습니다: Docker 모드는 먼저 메일러가 필요하므로 실행할 명령어를 출력하고 종료됩니다. 재실행해도 안전합니다: 기존 환경 파일은 절대 덮어쓰지 않으므로 업그레이드 경로로도 사용됩니다.

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

설치 프로그램 설정

--mode(또는 INTLAYER_MODE)가 없으면 설치 프로그램에 메뉴가 표시됩니다: desktop, docker(올인원) 또는 compose. 또한 몇 가지 환경 변수를 읽습니다. 셸로 파이프되므로 curl이 아닌 셸에 전달하세요:

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

포트 변수는 매핑의 호스트 측만 변경합니다. 게시된 이미지에는 http://localhost:3000, http://localhost:3100, http://localhost:9000이 대시보드 번들에 컴파일되어 있으므로 자체 이미지를 빌드하지 않는 한 기본값을 유지하세요. 제한 사항을 참조하세요.

초기 설정

새 인스턴스(빈 데이터베이스)에서 대시보드를 열면 /init 페이지로 리디렉션됩니다:

1. 첫 번째 계정을 만듭니다. 사용자 컬렉션이 비어 있으므로 이 계정은 자동으로 최고 관리자(super admin) 로 승격됩니다.
2. Resend 또는 SMTP 릴레이를 통해 인증 이메일이 전송됩니다. 이메일 인증은 필수이므로 시작하기 전에 메일러를 구성해야 합니다.
3. 이메일의 링크를 클릭한 다음 로그인합니다.

관리자가 존재하면 /init은 표준 로그인 페이지로 리디렉션됩니다.

환경 변수

두 Docker 모드 모두 docker/selfhost/.env.template에서 생성된 동일한 파일(컨테이너의 경우 intlayer.env, Compose의 경우 .env)을 읽습니다.

필수 항목

배포에 의해 고정됨

이 변수들은 이미지(올인원) 또는 compose 파일에서 설정되며, 비표준 토폴로지인 경우에만 재정의하면 됩니다. 단, DOMAIN, APP_URL, BACKEND_URL, S3_PUBLIC_URL은 예외로, env 파일에 설정하면 두 모드 모두에서 우선 적용됩니다(사용자 지정 도메인 참조).

Compose app 서비스는 추가로 INTLAYER_BACKEND_INTERNAL_URL=http://backend:3100을 받습니다: 브라우저는 localhost:3100에서 API에 연결하지만 서버 측 렌더링은 Compose 네트워크 내부에서 실행되므로 서비스 이름을 사용해야 합니다.

사용자 지정 도메인

백엔드는 런타임에 공개 URL을 읽지만, 대시보드에는 이 URL이 컴파일되어 포함되어 있습니다. 게시된 intlayer/cms-frontend 및 intlayer/cms-all 이미지는 http://localhost:3000에서만 동작합니다. 따라서 자체 도메인에서 Intlayer를 제공하려면 두 가지가 필요하며, 도메인 질문에 답하면 설치 프로그램이 둘 다 준비합니다:

1. env 파일의 네 가지 변수. 백엔드가 읽고(쿠키, 이메일 링크, OAuth 콜백, 에셋 URL) docker-compose.build.yml이 빌드 인수로 사용합니다:

   intlayer.env

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   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. 해당 URL로 빌드한 대시보드 이미지. Docker가 저장소에서 직접 빌드하므로 클론할 필요가 없습니다:

   sh

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   # 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
   

그런 다음 컨테이너 앞에 TLS를 사용하는 리버스 프록시를 둡니다: cms.example.org → 포트 3000, back.example.org → 3100, s3.example.org → 9000. 세션 쿠키의 범위가 DOMAIN으로 지정되므로 세 호스트는 이 접미사를 공유해야 합니다.

선택 항목 (누락 시 기능이 점진적으로 저하됨)

글로벌 메일러

비조직 이메일(비밀번호 재설정 및 매직 링크)을 포함한 모든 트랜잭션 이메일은 두 가지 글로벌 전송 방식 중 하나를 거칩니다:

• Resend: RESEND_API_KEY 사용.
• SMTP: MAIL_SMTP_* 변수 사용. MAIL_SMTP_HOST가 설정되면 즉시 SMTP가 사용되며 RESEND_API_KEY는 무시됩니다.

MAIL_PROVIDER는 둘 다 구성된 경우 하나의 전송 방식을 강제하는 데만 필요합니다(예: SMTP 호스트가 있는 상태에서 Resend를 유지하기 위해 MAIL_PROVIDER=resend).

우선순위: 조직 자체 메일러(조직 대시보드에서 구성)가 글로벌 메일러보다 우선하며, 글로벌 메일러는 기본 Resend 키보다 우선합니다.

Intlayer 프로젝트 연결

스택이 실행되면 intlayer.org 대신 자체 호스팅된 백엔드 및 대시보드를 가리키도록 프로젝트를 설정합니다.

프로젝트 구성

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>

http://localhost:3000/projects의 자체 호스팅 대시보드에서 Projects → Access keys 아래에 액세스 자격 증명을 만듭니다.

@intlayer/api SDK

프로그래밍 방식으로 @intlayer/api SDK를 사용할 때 backendURL을 명시적으로 전달합니다:

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();

제한 사항

• 사용자 지정 도메인은 리빌드가 필요합니다. 브라우저용 모든 VITE_* URL은 빌드 시 대시보드에 번들링되며 게시된 이미지(및 데스크톱 앱)는 localhost / Intlayer Cloud 값과 함께 제공됩니다. 기본적으로 대시보드는 http://localhost:3000, API는 :3100, MinIO는 :9000에서 액세스해야 하며, 호스트 포트를 재매핑해도 같은 결과가 됩니다. 도메인을 입력하면 설치 프로그램이 저장소에서 리빌드하는 데 필요한 모든 것을 준비하지만(사용자 지정 도메인 참조), 빌드 자체는 몇 분이 걸립니다. 데스크톱 앱을 자체 호스팅 백엔드로 지정하는 것은 지원되지 않습니다.
• 이메일 전송을 위해 작동하는 메일러가 필요합니다. 초기 설정에서는 이메일 인증이 강제되므로 RESEND_API_KEY 또는 SMTP 릴레이(MAIL_SMTP_*)를 구성해야 합니다. 첫 번째 관리자가 로그인한 후 각 조직은 대시보드에서 자체 SMTP 또는 Resend 메일러를 구성할 수도 있습니다.
• 데스크톱 앱은 임베디드 서버를 시작하기 위해 머신에 Node.js가 필요합니다.
• 문서 어시스턴트 없음. intlayer.org의 AI 문서 어시스턴트(/api/ai/ask, /api/search/doc)는 자체 호스팅 이미지에 포함되지 않는 약 130MB의 사전 계산된 문서 임베딩에 의존하므로, 자체 호스팅 모드에서는 이 두 경로가 등록되지 않습니다. 대시보드 자체의 AI 기능(번역, 감사, 자동 완성, 채팅)은 영향을 받지 않으며 OPENAI_API_KEY만 있으면 됩니다.

유용한 링크

• Intlayer CMS 문서
• 구성 레퍼런스
• CMS SDK: @intlayer/api
• 데스크톱 앱 릴리스
• Docker Hub: intlayer/cms-all, intlayer/cms-frontend, intlayer/cms-backend, GHCR 미러: ghcr.io/aymericzip/intlayer/
• docker/selfhost/: Dockerfile, docker-compose.yml 및 .env.template