Self-hosting Intlayer

Intlayer może działać na Twojej własnej infrastrukturze, bez konieczności posiadania konta Intlayer Cloud. Dostępne są trzy konfiguracje, zarządzane przez ten sam instalator (install.sh, install.ps1 w systemie Windows lub npx intlayer init infra):

Table of Contents

Opublikowane obrazy i pakiety

Wszystkie trzy obrazy są budowane z tego samego pliku docker/selfhost/Dockerfile i publikowane przy każdym wydaniu. Stos Compose pobiera również oficjalne obrazy mongo:8, redis:8-alpine oraz quay.io/minio/minio.

Konfiguracja

Instalator pyta o preferowaną konfigurację, sprawdza wymagania wstępne (proponując instalację Dockera), zapisuje plik środowiskowy z wygenerowanymi sekretami i pobiera obrazy. Nigdy nie uruchamia niczego samodzielnie: tryby Dockera wymagają najpierw mailera, więc na końcu wyświetla polecenie do uruchomienia. Ponowne uruchomienie jest bezpieczne: istniejący plik środowiskowy nigdy nie jest nadpisywany, co czyni go również ścieżką aktualizacji.

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

Ustawienia instalatora

Bez --mode (lub INTLAYER_MODE) instalator wyświetla menu: desktop, docker (all-in-one) lub compose. Odczytuje również kilka zmiennych środowiskowych. Ponieważ instalator jest przekazywany potokiem do powłoki, przekaż je do powłoki, a nie do 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

Zmienne portów zmieniają wyłącznie stronę hosta w mapowaniu. Opublikowane obrazy mają wartości http://localhost:3000, http://localhost:3100 oraz http://localhost:9000 skompilowane w pakiecie pulpitu, więc zachowaj wartości domyślne, chyba że budujesz własne obrazy, zobacz Ograniczenia.

Pierwsza konfiguracja

W nowej instancji (pusta baza danych) otwarcie pulpitu nawigacyjnego przekierowuje na stronę /init:

1. Utwórz pierwsze konto. Ponieważ kolekcja użytkowników jest pusta, to konto zostanie automatycznie awansowane na superadministratora.
2. Wiadomość e-mail weryfikacyjna jest wysyłana za pośrednictwem Resend lub przekaźnika SMTP. Weryfikacja adresu e-mail jest obowiązkowa, dlatego mailer musi być skonfigurowany przed uruchomieniem.
3. Kliknij link w wiadomości e-mail, a następnie zaloguj się.

Gdy administrator już istnieje, /init przekierowuje do standardowej strony logowania.

Zmienne środowiskowe

Oba tryby Dockera odczytują ten sam plik (intlayer.env dla kontenera, .env dla Compose), wygenerowany na podstawie docker/selfhost/.env.template.

Wymagane

Ustalane przez wdrożenie

Są one ustawiane przez obraz (all-in-one) lub przez plik compose i wymagają nadpisania tylko w przypadku niestandardowej topologii. Wyjątkiem są DOMAIN, APP_URL, BACKEND_URL i S3_PUBLIC_URL: ustawione w pliku env, mają pierwszeństwo w obu trybach (zobacz Domena niestandardowa).

Usługa Compose app otrzymuje dodatkowo INTLAYER_BACKEND_INTERNAL_URL=http://backend:3100: przeglądarka łączy się z API pod adresem localhost:3100, ale renderowanie po stronie serwera działa wewnątrz sieci Compose i musi używać nazwy usługi.

Domena niestandardowa

Backend odczytuje swoje publiczne adresy URL w czasie działania, ale pulpit nawigacyjny ma je wkompilowane: opublikowane obrazy intlayer/cms-frontend i intlayer/cms-all działają tylko pod http://localhost:3000. Udostępnienie Intlayer we własnej domenie wymaga więc dwóch rzeczy, które instalator przygotowuje, gdy odpowiesz na pytanie o domenę:

1. Cztery zmienne w pliku env, odczytywane przez backend (ciasteczka, linki w e-mailach, callbacki OAuth, adresy URL zasobów) i używane jako argumenty budowania przez docker-compose.build.yml:

   intlayer.env

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   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. Obraz pulpitu nawigacyjnego zbudowany z tymi adresami URL. Docker buduje go bezpośrednio z repozytorium, bez potrzeby klonowania:

   sh

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   # 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
   

Następnie umieść przed kontenerem reverse proxy z TLS: cms.example.org → port 3000, back.example.org → 3100, s3.example.org → 9000. Trzy hosty muszą mieć wspólny sufiks DOMAIN, ponieważ ciasteczko sesji jest do niego ograniczone.

Opcjonalne (funkcje działają poprawnie w stopniu ograniczonym przy ich braku)

Globalny mailer

Każda transakcyjna wiadomość e-mail, w tym wiadomości spoza organizacji (takie jak resetowanie hasła i linki logowania), przechodzi przez jeden z dwóch globalnych transportów:

• Resend, przy użyciu RESEND_API_KEY.
• SMTP, przy użyciu zmiennych MAIL_SMTP_*. Gdy tylko zostanie ustawiona zmienna MAIL_SMTP_HOST, używany jest protokół SMTP, a RESEND_API_KEY jest ignorowany.

MAIL_PROVIDER jest potrzebny tylko do wymuszenia jednego transportu, gdy oba są skonfigurowane (na przykład MAIL_PROVIDER=resend, aby zachować Resend, gdy zdefiniowany jest host SMTP).

Pierwszeństwo: własny mailer organizacji (skonfigurowany w panelu Organizacja) ma pierwszeństwo przed mailerem globalnym, który z kolei ma pierwszeństwo przed domyślnym kluczem Resend.

Łączenie projektu Intlayer

Po uruchomieniu stosu skieruj swój projekt na samodzielnie hostowany backend i pulpit nawigacyjny zamiast intlayer.org.

Konfiguracja projektu

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>

Utwórz poświadczenia dostępu w swoim hostowanym pulpicie w sekcji Projekty → Klucze dostępu pod adresem http://localhost:3000/projects.

SDK @intlayer/api

W przypadku programistycznego korzystania z pakietu SDK @intlayer/api przekaż backendURL jawnie:

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

Ograniczenia

• Domena niestandardowa oznacza ponowne zbudowanie. Wszystkie adresy URL VITE_* widoczne dla przeglądarki są wbudowane w pulpit nawigacyjny podczas kompilacji, a opublikowane obrazy (i aplikacja desktopowa) są dostarczane z wartościami localhost / Intlayer Cloud. Domyślnie dostęp do pulpitu nawigacyjnego musi odbywać się pod adresem http://localhost:3000, do API pod :3100, a do MinIO pod :9000; remapowanie portów hosta daje ten sam efekt. Gdy podasz domenę, instalator przygotowuje wszystko do ponownego zbudowania z repozytorium (zobacz Domena niestandardowa), ale samo budowanie trwa kilka minut. Wskazywanie aplikacji desktopowej na własny backend nie jest obsługiwane.
• Wysyłanie e-maili wymaga działającego mailera. Pierwsza konfiguracja wymusza weryfikację e-mail, dlatego należy skonfigurować RESEND_API_KEY lub przekaźnik SMTP (MAIL_SMTP_*). Po zalogowaniu się pierwszego administratora każda organizacja może również skonfigurować własny mailer SMTP lub Resend z poziomu pulpitu nawigacyjnego.
• Aplikacja desktopowa wymaga środowiska Node.js na komputerze do uruchomienia wbudowanego serwera.
• Brak asystenta dokumentacji. Asystent AI dokumentacji intlayer.org (/api/ai/ask, /api/search/doc) opiera się na ok. 130 MB wstępnie obliczonych embeddingów dokumentacji, których obrazy self-hosted nie zawierają; te dwie trasy nie są rejestrowane w trybie self-hosted. Własne funkcje AI pulpitu nawigacyjnego (tłumaczenie, audyt, autouzupełnianie, czat) nie są tym objęte i wymagają jedynie OPENAI_API_KEY.

Przydatne linki

• Dokumentacja Intlayer CMS
• Informacje o konfiguracji
• SDK CMS: @intlayer/api
• Wydania aplikacji desktopowej
• Docker Hub: intlayer/cms-all, intlayer/cms-frontend, intlayer/cms-backend, mirror na GHCR: ghcr.io/aymericzip/intlayer/
• docker/selfhost/: Dockerfile, docker-compose.yml i .env.template