Intlayer 자체 호스팅

Intlayer는 Intlayer Cloud 계정 없이도 자체 인프라에서 완전히 실행될 수 있습니다. 단일 명령으로 프로덕션 준비 스택을 부팅합니다:

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

설치 프로그램은 docker-compose.yml 및 .env 파일을 다운로드하고, 필요한 비밀을 자동으로 생성하며, docker compose up -d 명령으로 모든 컨테이너를 시작합니다.

목차

아키텍처

                ┌─────────────────────────────┐ 브라우저 ──────▶ │  앱  (TanStack Start)  :3000│ ──┐                └─────────────────────────────┘   │ VITE_BACKEND_URL                ┌─────────────────────────────┐   │                │  백엔드 (Fastify/Bun)  :3100│ ◀─┘                └──────────────┬──────────────┘          ┌──────────┬─────────┼──────────┬───────────┐          ▼          ▼         ▼          ▼           ▼     mongo:27017  redis:6379  minio:9000  mailpit:1025  Chromium     (1-노드 RS)             (S3 API)     (SMTP)        (이미지 내)                             minio:9001   mailpit:8025                             (콘솔)       (웹 UI)

Chromium (Puppeteer 스크린샷 생성에 사용됨)은 백엔드 이미지 내부에 번들로 제공되므로 별도의 컨테이너가 필요하지 않습니다.

사전 요구 사항

• Docker ≥ 24 및 Docker Compose ≥ v2. 둘 중 하나라도 없으면 설치 프로그램이 설치 링크를 출력하고 종료됩니다.
• 호스트에서 포트 3000, 3100, 8025, 9000, 9001이 사용 가능해야 합니다.
• Linux 또는 macOS 호스트 (또는 Windows의 WSL2).

빠른 시작

게시된 이미지를 pull하고 실행한 후 MongoDB Atlas 자격증명과 보안 키를 제공합니다:

docker run -d --name intlayer \  -p 3000:3000 \  -p 3100:3100 \  -p 9000:9000 \  -p 9001:9001 \  -v intlayer-data:/data \  -e DB_ID="<atlas-user>" \  -e DB_MDP="<atlas-password>" \  -e DB_CLUSTER="<cluster>.xxxxx.mongodb.net" \  -e BETTER_AUTH_SECRET="$(openssl rand -hex 32)" \  -e S3_SECRET_ACCESS_KEY="$(openssl rand -hex 16)" \  -e RESEND_API_KEY="<your-resend-key>" \  aymericzip/intlayer-selfhost

그 다음 http://localhost:3000을 엽니다.

대시보드는 localhost에서 제공됩니다. 제한 사항을 참고하세요 — 게시된 이미지에서는 커스텀 도메인이 지원되지 않습니다.

빠른 시작

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

설치 프로그램의 기능:

1. docker 및 docker compose가 설치되어 있는지 확인합니다.
2. docker-compose.yml 및 .env.example을 ./intlayer/ 디렉토리에 다운로드합니다.
3. .env 파일이 없으면 예제 파일을 복사하고 openssl rand를 통해 BETTER_AUTH_SECRET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY에 대한 임의의 비밀을 생성합니다.
4. docker compose pull + docker compose up -d를 실행합니다.
5. 다음 URL을 출력합니다: 대시보드 :3000, API :3100, 이메일 UI :8025, MinIO 콘솔 :9001.

스택이 실행되면 http://localhost:3000을 열고 첫 번째 계정을 생성하세요.

서비스

내부 포트(mongo, redis)는 기본적으로 호스트에 노출되지 않습니다.

MinIO 포트 9000은 브라우저에서 접근할 수 있어야 합니다. 업로드된 자산(아바타, 스크린샷)은 S3_PUBLIC_URL=http://localhost:9000/intlayer에서 직접 로드되기 때문입니다.

환경 변수

필수

필수 (자동 생성 또는 프롬프트)

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

Global mailer

기본적으로 모든 트랜잭션 이메일은 RESEND_API_KEY를 사용하여 Resend를 통해 전송됩니다. Self-hosted 배포는 대신 환경 변수로 구성된 global mailer를 통해 비조직 이메일(예: 비밀번호 재설정 및 magic link)을 포함한 모든 이메일을 라우팅할 수 있습니다.

MAIL_PROVIDER를 설정하여 활성화합니다. 설정하지 않으면 기본 Resend mailer가 사용됩니다.

Precedence: 조직의 자체 mailer (Organization dashboard에서 구성)가 global mailer보다 우선하며, global mailer는 기본 Resend key보다 우선합니다.

Intlayer 프로젝트 연결하기

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

프로젝트 설정

import type { IntlayerConfig } from "intlayer";

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

    /**
     * 자체 호스팅 CMS 대시보드의 URL.
     * 기본값: https://app.intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL, // 예: http://localhost:3000

    /**
     * 자체 호스팅 백엔드 API의 URL.
     * 기본값: https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL, // 예: http://localhost:3100
  },
};

export default config;

프로젝트의 .env 파일에 환경 변수를 설정하세요:

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

http://localhost:3000/projects의 자체 호스팅 대시보드 프로젝트 → 접근 키에서 접근 자격 증명을 생성하세요.

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

업그레이드

기존 배포에서 설치 프로그램을 다시 실행하면 롤링 업그레이드가 수행됩니다:

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

이는 최신 이미지를 가져오고 docker compose pull && docker compose up -d를 사용하여 컨테이너를 다시 시작합니다. 기존 볼륨(mongo-data, redis-data, minio-data)은 보존되므로 데이터 손실이 없습니다.

./intlayer/ 디렉토리 내부에서 수동으로 업그레이드하려면:

docker compose pulldocker compose up -d

백업 및 복원

모든 영구 데이터는 세 개의 명명된 Docker 볼륨에 저장됩니다.

백업

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

복원

docker run --rm \  -v intlayer_mongo-data:/data \  -v "$(pwd)":/backup \  busybox tar xzf /backup/mongo-data.tar.gz -C /# redis-data 및 minio-data에 대해서도 반복합니다.

제한 사항

• MongoDB는 외부(Atlas)여야 합니다. 백엔드는 mongodb+srv://로만 연결되며(DB_ID / DB_MDP / DB_CLUSTER로 구성됨), 일반 mongodb://host:27017 — 컨테이너의 자체 번들 mongod 포함 — 은 사용할 수 없습니다. MongoDB Atlas 클러스터를 제공하세요.
• 사용자 정의 도메인 없음. 모든 브라우저 대면 VITE_* URL은 빌드 시 앱에 인라인되며, 게시된 이미지는 localhost 값으로 제공됩니다. 대시보드는 http://localhost:3000에서 액세스해야 합니다. 공개 도메인에서 제공하려면 대상 URL을 포함하여 이미지를 다시 빌드해야 하며 기본적으로 지원되지 않습니다.
• 이메일에는 작동하는 메일러가 필요합니다. 초기 실행 설정은 이메일 확인을 강제하므로 RESEND_API_KEY 또는 글로벌 SMTP 메일러(MAIL_PROVIDER=smtp + MAIL_SMTP_*)를 구성해야 합니다. 첫 번째 관리자가 로그인한 후 각 조직은 대시보드에서 자신의 SMTP 또는 Resend 메일러를 구성할 수도 있습니다.

문제 해결

첫 시작 시 백엔드 충돌 반복

백엔드가 시작되기 전에 MongoDB와 Redis가 정상 상태여야 합니다. compose 파일은 condition: service_healthy와 함께 depends_on을 사용합니다. 백엔드 재시작이 반복적으로 발생하면 mongo 및 redis 헬스체크가 통과하는지 확인하세요:

docker compose psdocker compose logs mongodocker compose logs redis

대시보드가 API에 연결할 수 없음

VITE_BACKEND_URL이 브라우저에서 백엔드에 접근 가능한 URL(Docker 네트워크가 아님)과 일치하는지 확인하세요. 백엔드 포트를 변경했거나 리버스 프록시를 추가했다면, 대시보드 이미지를 다시 빌드해야 합니다:

docker compose build appdocker compose up -d app

MinIO 버킷 누락

minio-init 일회성 서비스가 실행되지 않았거나(또는 MinIO가 준비되기 전에 실행된 경우), 수동으로 버킷을 생성하세요:

docker compose run --rm minio-init

유용한 링크

• Intlayer CMS 문서
• 설정 참조
• CMS SDK — @intlayer/api
• Docker Image (aymercizip/intlayer-selfhost)