Auto-hosting di Intlayer

Intlayer può essere eseguito sulla tua infrastruttura, nessun account Intlayer Cloud richiesto. Sono disponibili tre configurazioni, tutte gestite dallo stesso programma di installazione (install.sh, install.ps1 su Windows o npx intlayer init infra):

Table of Contents

Immagini e pacchetti pubblicati

Tutte e tre le immagini sono compilate dallo stesso docker/selfhost/Dockerfile e pubblicate a ogni rilascio. Lo stack Compose scarica anche le immagini ufficiali mongo:8, redis:8-alpine e quay.io/minio/minio.

Configurazione

Il programma di installazione chiede quale configurazione desideri, controlla i prerequisiti (proponendo di installare Docker), scrive il file di ambiente con i segreti già generati e scarica le immagini. Non avvia nulla autonomamente: le modalità Docker richiedono prima un mailer, quindi termina stampando il comando da eseguire. Rieseguirlo è sicuro: un file di ambiente esistente non viene mai sovrascritto, fungendo anche da percorso di aggiornamento.

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

Impostazioni del programma di installazione

Senza --mode (o INTLAYER_MODE), il programma di installazione mostra un menu: desktop, docker (all-in-one) o compose. Legge anche alcune variabili di ambiente. Poiché viene reindirizzato nella shell, passale alla shell anziché a 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

Le variabili di porta modificano solo il lato host della mappatura. Le immagini pubblicate includono http://localhost:3000, http://localhost:3100 e http://localhost:9000 compilati nel pacchetto della dashboard, quindi mantieni i valori predefiniti a meno che non crei le tue immagini, vedi Limitazioni.

Configurazione iniziale

Su una nuova istanza (database vuoto), l'apertura della dashboard reindirizza alla pagina /init:

1. Crea il primo account. Poiché la raccolta degli utenti è vuota, questo account viene automaticamente promosso a super admin.
2. Viene inviata un'email di verifica tramite Resend o il relay SMTP. La verifica dell'email è obbligatoria, motivo per cui un gestore di posta deve essere configurato prima di iniziare.
3. Fai clic sul link nell'email, quindi accedi.

Una volta che esiste un amministratore, /init reindirizza alla pagina di accesso standard.

Variabili di ambiente

Entrambe le modalità Docker leggono lo stesso file (intlayer.env per il container, .env per Compose), generato da docker/selfhost/.env.template.

Richieste

Fissate dal deployment

Queste sono impostate dall'immagine (all-in-one) o dal file compose, e vanno sovrascritte solo per una topologia non standard. DOMAIN, APP_URL, BACKEND_URL e S3_PUBLIC_URL sono l'eccezione: se impostate nel file env, hanno la precedenza in entrambe le modalità (vedi Dominio personalizzato).

Il servizio app di Compose riceve inoltre INTLAYER_BACKEND_INTERNAL_URL=http://backend:3100: il browser raggiunge l'API su localhost:3100, ma il rendering lato server viene eseguito all'interno della rete Compose e deve usare il nome del servizio.

Dominio personalizzato

Il backend legge i propri URL pubblici a runtime, ma la dashboard li ha compilati al suo interno: le immagini pubblicate intlayer/cms-frontend e intlayer/cms-all funzionano solo su http://localhost:3000. Servire Intlayer sul tuo dominio richiede quindi due cose, entrambe preparate dal programma di installazione quando rispondi alla domanda sul dominio:

1. Quattro variabili nel file env, lette dal backend (cookie, link nelle email, callback OAuth, URL delle risorse) e usate come argomenti di build da docker-compose.build.yml:

   intlayer.env

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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. Un'immagine della dashboard compilata con quegli URL. Docker la compila direttamente dal repository, senza bisogno di un clone:

   sh

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   # 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
   

Poi metti un reverse proxy con TLS davanti al container: cms.example.org → porta 3000, back.example.org → 3100, s3.example.org → 9000. I tre host devono condividere il suffisso DOMAIN, poiché il cookie di sessione è limitato a esso.

Opzionali (le funzionalità degradano dolcemente se assenti)

Mailer globale

Ogni email transazionale, comprese le email esterne all'organizzazione come reimpostazioni password e link magici, passa attraverso uno dei due trasporti globali:

• Resend, usando RESEND_API_KEY.
• SMTP, usando le variabili MAIL_SMTP_*. Non appena MAIL_SMTP_HOST viene impostato, viene usato SMTP e RESEND_API_KEY viene ignorato.

MAIL_PROVIDER serve solo a forzare un trasporto quando entrambi sono configurati (ad esempio MAIL_PROVIDER=resend per mantenere Resend pur in presenza di un host SMTP).

Precedenza: il mailer di un'organizzazione (configurato dalla dashboard Organizzazione) ha la precedenza sul mailer globale, che a sua volta ha la precedenza sulla chiave predefinita di Resend.

Connettere il tuo progetto Intlayer

Una volta avviato lo stack, fai puntare il tuo progetto al backend e alla dashboard auto-ospitati invece di intlayer.org.

Configurazione del progetto

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>

Crea credenziali di accesso nella dashboard auto-ospitata in Progetti → Chiavi di accesso all'indirizzo http://localhost:3000/projects.

SDK @intlayer/api

Quando si utilizza l'SDK @intlayer/api a livello di codice, passare backendURL in modo esplicito:

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

Limitazioni

• Un dominio personalizzato richiede una ricompilazione. Tutti gli URL VITE_* visibili dal browser sono incorporati nella dashboard in fase di compilazione e le immagini pubblicate (nonché l'app desktop) vengono fornite con i valori di localhost / Intlayer Cloud. Di default la dashboard deve essere accessibile su http://localhost:3000, l'API su :3100 e MinIO su :9000; rimappare le porte dell'host ha lo stesso effetto. Il programma di installazione predispone tutto per una ricompilazione dal repository quando gli indichi un dominio (vedi Dominio personalizzato), ma la compilazione stessa richiede diversi minuti. Puntare l'app desktop a un backend auto-ospitato non è supportato.
• La posta richiede un mailer funzionante. La configurazione iniziale impone la verifica dell'email, pertanto è necessario configurare RESEND_API_KEY oppure un relay SMTP (MAIL_SMTP_*). Dopo l'accesso del primo amministratore, ciascuna organizzazione può configurare il proprio mailer SMTP o Resend dalla dashboard.
• L'applicazione desktop richiede Node.js sulla macchina per avviare il relativo server incorporato.
• Nessun assistente per la documentazione. L'assistente IA per la documentazione di intlayer.org (/api/ai/ask, /api/search/doc) si basa su circa 130 MB di embedding della documentazione precalcolati che le immagini self-hosted non includono; queste due route non vengono registrate in modalità self-hosted. Le funzionalità di IA proprie della dashboard (traduzione, audit, completamento automatico, chat) non sono interessate e richiedono solo OPENAI_API_KEY.

Link utili

• Documentazione Intlayer CMS
• Riferimento di configurazione
• SDK CMS: @intlayer/api
• Rilasci dell'applicazione desktop
• Docker Hub: intlayer/cms-all, intlayer/cms-frontend, intlayer/cms-backend, con mirror su GHCR sotto ghcr.io/aymericzip/intlayer/
• docker/selfhost/: Dockerfile, docker-compose.yml e .env.template