Autoalojamiento de Intlayer

Intlayer puede ejecutarse completamente en tu propia infraestructura, sin necesidad de una cuenta de Intlayer Cloud. Un solo comando inicia una pila lista para producción:

Un comando instala todo:

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

El instalador descarga un docker-compose.yml y un .env, autogenera los secretos necesarios e inicia todos los contenedores con docker compose up -d.

La única dependencia externa es MongoDB: el backend se conecta a un cluster de MongoDB Atlas, que proporcionas. Todo lo demás se ejecuta dentro del contenedor.

Tabla de Contenidos

Arquitectura

                ┌─────────────────────────────┐
 navegador ──────▶ │  app  (TanStack Start)  :3000│ ──┐
                └─────────────────────────────┘   │ VITE_BACKEND_URL
                ┌─────────────────────────────┐   │
                │  backend (Fastify/Bun)  :3100│ ◀─┘
                └──────────────┬──────────────┘
          ┌──────────┬─────────┼──────────┬───────────┐
          ▼          ▼         ▼          ▼           ▼
     mongo:27017  redis:6379  minio:9000  mailpit:1025  Chromium
     (RS de 1 nodo)             (API de S3)     (SMTP)        (en-imagen)
                             minio:9001   mailpit:8025
                             (consola)    (interfaz web)

Chromium (utilizado para la generación de capturas de pantalla de Puppeteer) se incluye dentro de la imagen del backend, no se necesita un contenedor separado.

Requisitos previos

• Docker ≥ 24 y Docker Compose ≥ v2. Si falta alguno, el instalador imprimirá el enlace de instalación y saldrá.
• Puertos 3000, 3100, 8025, 9000 y 9001 disponibles en el host.
• Un host Linux o macOS (o WSL2 en Windows).

Todo lo demás — Bun, Redis, MinIO, Chromium — se incluye dentro de la imagen.

Inicio rápido

1. Ejecutar el instalador

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

Verifica que Docker esté instalado y en ejecución, escribe ./intlayer.env con BETTER_AUTH_SECRET y S3_SECRET_ACCESS_KEY ya generadas, y descarga la imagen. No inicia el contenedor — el backend no puede arrancar sin tus credenciales de base de datos.

Ejecutar nuevamente el instalador es seguro: un intlayer.env existente nunca se sobrescribe, por lo que también sirve como ruta de actualización.

2. Rellena tus credenciales

Abre intlayer.env y completa los valores marcados como TODO:

DB_ID=<atlas-user>
DB_MDP=<atlas-password>
DB_CLUSTER=<cluster>.xxxxx.mongodb.net
RESEND_API_KEY=<your-resend-key>

El archivo también contiene bloques comentados para las características opcionales — SMTP mailer, OPENAI_API_KEY y los proveedores de OAuth. Descomenta lo que necesites.

El archivo se lee mediante docker run --env-file, que no elimina las comillas y trata todo después de = como el valor. Escribe valores sin comillas y mantén los comentarios en sus propias líneas.

3. Inicia el container

Este es el comando que el instalador imprime cuando finaliza:

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 \
  ghcr.io/aymericzip/intlayer-selfhost:latest

Luego abre http://localhost:3000. El primer inicio inicializa los almacenes de datos, así que espera un minuto.

El panel de control se sirve en localhost. Ver Limitaciones — los dominios personalizados no son compatibles con la imagen publicada.

Configuración del instalador

El instalador lee algunas variables de entorno. Dado que se canaliza en sh, pásalas al shell en lugar de a curl:

curl -fsSL https://intlayer.org/install.sh | INTLAYER_ENV_FILE=./config/intlayer.env sh

Las cuatro variables de puerto solo cambian el lado del host del mapeo impreso en el comando docker run. La imagen publicada tiene http://localhost:3000, http://localhost:3100 y http://localhost:9000 compilados en el bundle del dashboard en el momento de la compilación, por lo que reasignarlos deja el navegador apuntando a los puertos antiguos. Mantén los valores predeterminados a menos que estés construyendo tu propia imagen — consulta Limitaciones.

Configuración inicial

En una instancia nueva (base de datos vacía), abrir el dashboard te redirige a la página /init:

1. Crea la primera cuenta. Como la colección de usuarios está vacía, esta cuenta se promociona automáticamente a super admin.
2. Se envía un email de verificación (vía Resend). La verificación de email es obligatoria — por eso RESEND_API_KEY debe estar configurado antes de empezar.
3. Haz clic en el enlace del email e inicia sesión.

Una vez que existe un admin, /init redirige a la página estándar de inicio de sesión.

Servicios

El puerto 9000 de MinIO debe ser accesible desde el navegador porque los activos cargados (avatares, capturas de pantalla) se cargan directamente desde S3_PUBLIC_URL=http://localhost:9000/intlayer.

Variables de entorno

Requerido

Requeridas (autogeneradas o solicitadas)

Opcionales (las características se degradan elegantemente cuando están ausentes)

Servicio de correo global

De forma predeterminada, todos los correos electrónicos transaccionales se envían a través de Resend utilizando RESEND_API_KEY. Los despliegues auto-hospedados pueden enrutar todos los correos electrónicos — incluyendo correos no organizacionales como restablecimiento de contraseña y enlaces mágicos — a través de un servicio de correo global configurado con variables de entorno.

Establece MAIL_PROVIDER para activarlo. Cuando no está configurado, se utiliza el servicio de correo Resend predeterminado.

Precedencia: el servicio de correo propio de una organización (configurado desde el panel de control de Organization) tiene prioridad sobre el servicio de correo global, que a su vez tiene prioridad sobre la clave Resend predeterminada.

Conectando tu proyecto Intlayer

Una vez que la pila esté en funcionamiento, apunta tu proyecto al backend y dashboard autoalojados en lugar de intlayer.org.

Configuración del proyecto

import type { IntlayerConfig } from "intlayer";

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

    /**
     * URL del dashboard CMS autoalojado.
     * Por defecto: https://app.intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL, // e.g. http://localhost:3000

    /**
     * URL de la API del backend autoalojado.
     * Por defecto: https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL, // e.g. http://localhost:3100
  },
};

export default config;

Establece las variables de entorno en el .env de tu proyecto:

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 credenciales de acceso en tu dashboard autoalojado en Proyectos → Claves de acceso en http://localhost:3000/projects.

SDK de @intlayer/api

Al usar el SDK de @intlayer/api programáticamente, pasa backendURL explícitamente:

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

Actualización

Esto descarga las últimas imágenes y reinicia los contenedores con docker compose pull && docker compose up -d. Los volúmenes existentes (mongo-data, redis-data, minio-data) se conservan, sin pérdida de datos.

docker compose pull
docker compose up -d

Copia de seguridad y restauración

Todos los datos persistentes residen en tres volúmenes de Docker con nombre.

Copia de seguridad

docker run --rm \
  -v intlayer_mongo-data:/data \
  -v "$(pwd)":/backup \
  busybox tar czf /backup/mongo-data.tar.gz /data

docker run --rm \
  -v intlayer_redis-data:/data \
  -v "$(pwd)":/backup \
  busybox tar czf /backup/redis-data.tar.gz /data

docker run --rm \
  -v intlayer_minio-data:/data \
  -v "$(pwd)":/backup \
  busybox tar czf /backup/minio-data.tar.gz /data

Restauración

docker run --rm \
  -v intlayer_mongo-data:/data \
  -v "$(pwd)":/backup \
  busybox tar xzf /backup/mongo-data.tar.gz -C /

# Repetir para redis-data y minio-data

Limitaciones

• MongoDB debe ser externo (Atlas). El backend se conecta solo a través de mongodb+srv:// (construido desde DB_ID / DB_MDP / DB_CLUSTER), por lo que un simple mongodb://host:27017 — incluyendo el mongod incluido en el contenedor — no se puede usar. Proporciona un cluster de MongoDB Atlas.
• Sin dominio personalizado. Todas las URLs VITE_* que enfrenta el navegador se insertan en línea en la aplicación en tiempo de compilación, y la imagen publicada se envía con valores de localhost. El dashboard debe accederse en http://localhost:3000; servirlo en un dominio público requeriría reconstruir la imagen con las URLs de destino incorporadas y no es compatible de forma predeterminada.
• El correo electrónico requiere un mailer que funcione. La configuración de primera ejecución obliga a la verificación de correo electrónico, por lo que se debe configurar RESEND_API_KEY o un mailer SMTP global (MAIL_PROVIDER=smtp + MAIL_SMTP_*). Después de que el primer administrador inicie sesión, cada organización también puede configurar su propio mailer SMTP o Resend desde el dashboard.

Solución de problemas

Reinicios del backend en bucle al inicio

MongoDB y Redis deben estar saludables antes de que el backend se inicie. El archivo compose utiliza depends_on con condition: service_healthy. Si ves reinicios repetidos del backend, verifica que los healthchecks de mongo y redis pasen:

docker compose ps
docker compose logs mongo
docker compose logs redis

Busca MongoDB connection error cerca de la parte superior del log.

El dashboard no puede conectar con la API

Verifica que VITE_BACKEND_URL coincida con la URL donde el backend es accesible desde el navegador (no desde la red de Docker). Si cambiaste el puerto del backend o añadiste un proxy inverso, reconstruye la imagen del dashboard:

Falta el bucket de MinIO

Si el servicio de un solo uso minio-init no se ejecutó (o se ejecutó antes de que MinIO estuviera listo), crea el bucket manualmente:

docker compose run --rm minio-init

Enlaces útiles

• Documentación del CMS de Intlayer
• Referencia de configuración
• SDK del CMS — @intlayer/api
• Docker Image (aymercizip/intlayer-selfhost)