작가:
    생성:2026-06-30마지막 업데이트:2026-06-30

    Intlayer 자체 호스팅

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

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

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

    목차

    아키텍처

    plaintext
                    ┌─────────────────────────────┐ 브라우저 ──────▶ │  앱  (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).

    빠른 시작

    sh
    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을 열고 첫 번째 계정을 생성하세요.

    서비스

    서비스 이미지 호스트 포트 목적
    앱 apps/app/Dockerfile에서 빌드 3000 TanStack Start 대시보드 (CMS UI)
    백엔드 apps/backend/Dockerfile에서 빌드 3100 Fastify REST API (/health 엔드포인트)
    mongo mongo:7 내부 단일 노드 복제본 세트 (rs0)
    redis redis:7-alpine 내부 작업 큐 (BullMQ) 및 캐싱 (ioredis)
    minio minio/minio 9000 (S3), 9001 (콘솔) 아바타 및 스크린샷을 위한 S3 호환 객체 스토리지
    mailpit axllent/mailpit 1025 (SMTP), 8025 (웹 UI) 로컬 트랜잭션 이메일 싱크

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

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

    환경 변수

    설치 프로그램은 즉시 사용할 수 있는 .env 파일을 생성합니다. 아래 표는 모든 변수를 설명합니다.

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

    변수 예시 설명
    NODE_ENV production 런타임 환경
    PORT 3100 백엔드 리스닝 포트
    BACKEND_URL http://localhost:3100 백엔드 API의 공개 URL
    APP_URL http://localhost:3000 대시보드의 공개 URL
    DOMAIN localhost 쿠키 도메인
    MONGODB_URI mongodb://mongo:27017/intlayer?replicaSet=rs0 전체 MongoDB 연결 URI
    REDIS_URL redis://redis:6379 Redis 연결 URL
    BETTER_AUTH_SECRET (생성됨) 세션 서명을 위한 32바이트 비밀 키
    MAIL_PROVIDER smtp 메일 전송 방식: smtp 또는 resend
    MAIL_SMTP_HOST mailpit SMTP 호스트명 (Mailpit 컨테이너 이름)
    MAIL_SMTP_PORT 1025 SMTP 포트
    MAIL_FROM Intlayer <no-reply@localhost> 발신자 주소
    S3_ENDPOINT http://minio:9000 S3 호환 엔드포인트
    S3_PUBLIC_URL http://localhost:9000/intlayer 브라우저 자산 로딩을 위한 공개 URL
    S3_BUCKET_NAME intlayer 버킷 이름
    S3_ACCESS_KEY_ID (생성됨) MinIO 접근 키
    S3_SECRET_ACCESS_KEY (생성됨) MinIO 비밀 키
    VITE_BACKEND_URL http://localhost:3100 빌드 시 대시보드에 내장되는 백엔드 URL
    VITE_DOMAIN localhost 빌드 시 대시보드에 내장되는 도메인

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

    변수 기능
    OPENAI_API_KEY AI 기반 번역 및 콘텐츠 감사
    STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_* 결제 및 구독 관리
    RESEND_API_KEY Resend를 통한 트랜잭션 이메일 (설정 시 Mailpit 재정의)
    GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET GitHub OAuth 로그인
    GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET Google OAuth 로그인
    GITLAB_CLIENT_ID, GITLAB_CLIENT_SECRET GitLab OAuth 로그인
    MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET Microsoft OAuth 로그인
    LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET LinkedIn OAuth 로그인
    ATLASSIAN_CLIENT_ID, ATLASSIAN_CLIENT_SECRET Atlassian OAuth 로그인

    Intlayer 프로젝트 연결하기

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

    프로젝트 설정

    intlayer.config.ts
    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 파일에 환경 변수를 설정하세요:

    sh
    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을 명시적으로 전달하세요:

    cms.ts
    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();

    업그레이드

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

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

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

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

    sh
    docker compose pulldocker compose up -d

    백업 및 복원

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

    백업

    sh
    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

    복원

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

    리버스 프록시 사용 (Nginx / Caddy)

    프로덕션 배포의 경우, 앱 및 백엔드 컨테이너를 직접 노출하는 대신 리버스 프록시를 앞에 배치하세요.

    Nginx 예시

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

    공개 도메인과 일치하도록 다음 .env 변수를 업데이트하세요:

    sh
    BACKEND_URL=https://api.example.comAPP_URL=https://cms.example.comDOMAIN=example.comVITE_BACKEND_URL=https://api.example.comVITE_DOMAIN=example.com
    VITE_* 변수는 빌드 시 대시보드 이미지에 내장됩니다. 이미지가 빌드된 후 이를 변경하는 경우, app 이미지를 다시 빌드(docker compose build app)하거나 런타임 구성 주입을 사용해야 합니다.

    문제 해결

    첫 시작 시 백엔드 충돌 반복

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

    sh
    docker compose psdocker compose logs mongodocker compose logs redis

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

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

    sh
    docker compose build appdocker compose up -d app

    이메일이 전송되지 않음

    기본적으로 모든 발신 이메일은 Mailpit에 의해 캡처됩니다. http://localhost:8025를 열어 전송된 메시지를 확인하세요. 실제 이메일을 보내려면 .env 파일에 MAIL_PROVIDER=resend 및 RESEND_API_KEY=<your-key>를 설정한 다음 백엔드를 다시 시작하세요:

    sh
    docker compose restart backend

    MinIO 버킷 누락

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

    sh
    docker compose run --rm minio-init

    유용한 링크

    Intlayer의 이점