Self-Hosting Intlayer

Intlayer può essere eseguito interamente sulla tua infrastruttura — non è richiesto alcun account Intlayer Cloud. Un singolo comando avvia uno stack pronto per la produzione:

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

L'installer scarica un docker-compose.yml e un .env, genera automaticamente i segreti richiesti e avvia tutti i container con docker compose up -d.

Indice dei Contenuti

Architettura

                ┌─────────────────────────────┐ browser ──────▶ │  app  (TanStack Start)  :3000│ ──┐                └─────────────────────────────┘   │ VITE_BACKEND_URL                ┌─────────────────────────────┐   │                │  backend (Fastify/Bun)  :3100│ ◀─┘                └──────────────┬──────────────┘          ┌──────────┬─────────┼──────────┬───────────┐          ▼          ▼         ▼          ▼           ▼     mongo:27017  redis:6379  minio:9000  mailpit:1025  Chromium     (1-node RS)             (S3 API)     (SMTP)        (in-image)                             minio:9001   mailpit:8025                             (console)    (web UI)

Chromium (utilizzato per la generazione di screenshot con Puppeteer) è incluso nell'immagine del backend — non è necessario un container separato.

Prerequisiti

• Docker ≥ 24 e Docker Compose ≥ v2. Se uno dei due manca, l'installer stampa il link di installazione ed esce.
• Porte 3000, 3100, 8025, 9000 e 9001 disponibili sull'host.
• Un host Linux o macOS (o WSL2 su Windows).

Avvio rapido

Scarica ed esegui l'immagine pubblicata, fornendo le tue credenziali e i segreti di 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

Quindi apri http://localhost:3000.

La dashboard è servita su localhost. Vedi Limitazioni — i domini personalizzati non sono supportati dall'immagine pubblicata.

Avvio rapido

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

Cosa fa l'installer:

1. Verifica che docker e docker compose siano presenti.
2. Scarica docker-compose.yml e .env.example in ./intlayer/.
3. Se non esiste un .env, copia l'esempio e genera segreti casuali per BETTER_AUTH_SECRET, S3_ACCESS_KEY_ID e S3_SECRET_ACCESS_KEY tramite openssl rand.
4. Esegue docker compose pull + docker compose up -d.
5. Stampa gli URL: dashboard :3000, API :3100, interfaccia utente email :8025, console MinIO :9001.

Dopo che lo stack è attivo, apri http://localhost:3000 e crea il tuo primo account.

Servizi

Le porte interne (mongo, redis) non sono esposte all'host per impostazione predefinita.

La porta 9000 di MinIO deve essere raggiungibile dal browser perché gli asset caricati (avatar, screenshot) vengono caricati direttamente da S3_PUBLIC_URL=http://localhost:9000/intlayer.

Variabili d'ambiente

Obbligatorio

Obbligatorie (generate automaticamente o richieste)

Opzionali (le funzionalità degradano elegantemente se assenti)

Mailer globale

Per impostazione predefinita, tutti i messaggi email transazionali vengono inviati tramite Resend utilizzando RESEND_API_KEY. I deploy self-hosted possono invece instradare ogni email — incluse le email non organizzative come i reset delle password e i magic link — attraverso un mailer globale configurato con variabili di ambiente.

Imposta MAIL_PROVIDER per attivarlo. Quando non impostato, viene utilizzato il mailer predefinito di Resend.

Precedenza: il mailer personalizzato di un'organizzazione (configurato dal dashboard Organization) ha priorità rispetto al mailer globale, che a sua volta ha priorità rispetto alla chiave Resend predefinita.

Collegamento del tuo progetto Intlayer

Una volta che lo stack è in esecuzione, punta il tuo progetto al backend e alla dashboard self-hosted 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 della dashboard CMS self-hosted.
     * Predefinito: https://app.intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL, // e.g. http://localhost:3000

    /**
     * URL dell'API del backend self-hosted.
     * Predefinito: https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL, // e.g. http://localhost:3100
  },
};

export default config;

Imposta le variabili d'ambiente nel .env del tuo progetto:

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

Crea le credenziali di accesso nella tua dashboard self-hosted sotto Progetti → Chiavi di accesso all'indirizzo http://localhost:3000/projects.

SDK @intlayer/api

Quando si utilizza l'SDK @intlayer/api in modo programmatico, passa backendURL esplicitamente:

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

Aggiornamento

Eseguire nuovamente l'installer su un'implementazione esistente esegue un aggiornamento rolling:

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

Questo scarica le immagini più recenti e riavvia i container con docker compose pull && docker compose up -d. I volumi esistenti (mongo-data, redis-data, minio-data) vengono preservati — nessuna perdita di dati.

Per aggiornare manualmente dalla directory ./intlayer/:

docker compose pulldocker compose up -d

Backup e ripristino

Tutti i dati persistenti risiedono in tre volumi Docker nominati.

Backup

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

Ripristino

docker run --rm \  -v intlayer_mongo-data:/data \  -v "$(pwd)":/backup \  busybox tar xzf /backup/mongo-data.tar.gz -C /# Ripetere per redis-data e minio-data

Limitazioni

• MongoDB deve essere esterno (Atlas). Il backend si connette solo su mongodb+srv:// (costruito da DB_ID / DB_MDP / DB_CLUSTER), quindi un semplice mongodb://host:27017 — incluso il mongod incluso nel container — non può essere utilizzato. Fornire un cluster MongoDB Atlas.
• Nessun dominio personalizzato. Tutti gli URL VITE_* rivolti al browser sono inline nell'app al momento della compilazione, e l'immagine pubblicata contiene valori localhost. Il dashboard deve essere accessibile su http://localhost:3000; servarlo su un dominio pubblico richiederebbe di ricompilare l'immagine con gli URL di destinazione incorporati e non è supportato out of the box.
• Email richiede un mailer funzionante. La configurazione al primo avvio applica la verifica email, quindi RESEND_API_KEY o un mailer SMTP globale (MAIL_PROVIDER=smtp + MAIL_SMTP_*) deve essere configurato. Dopo che il primo amministratore ha effettuato l'accesso, ogni organizzazione può anche configurare il proprio mailer SMTP o Resend dal dashboard.

Risoluzione dei problemi

Il backend si riavvia in loop al primo avvio

MongoDB e Redis devono essere sani prima che il backend si avvii. Il file compose utilizza depends_on con condition: service_healthy. Se vedi ripetuti riavvii del backend, verifica che i controlli di integrità di mongo e redis passino:

docker compose psdocker compose logs mongodocker compose logs redis

La dashboard non riesce a raggiungere l'API

Verifica che VITE_BACKEND_URL corrisponda all'URL dove il backend è raggiungibile dal browser (non dalla rete Docker). Se hai cambiato la porta del backend o aggiunto un reverse proxy, ricostruisci l'immagine della dashboard:

docker compose build appdocker compose up -d app

Bucket MinIO mancante

Se il servizio one-shot minio-init non è stato eseguito (o è stato eseguito prima che MinIO fosse pronto), crea il bucket manualmente:

docker compose run --rm minio-init

Link utili

• Documentazione Intlayer CMS
• Riferimento alla configurazione
• SDK CMS — @intlayer/api
• Docker Image (aymercizip/intlayer-selfhost)