Auto-hospedagem do Intlayer

O Intlayer pode ser executado em sua própria infraestrutura, sem necessidade de conta no Intlayer Cloud. Três configurações estão disponíveis, todas gerenciadas pelo mesmo instalador (install.sh, install.ps1 no Windows ou npx intlayer init infra):

Table of Contents

Imagens e pacotes publicados

Todas as três imagens são construídas a partir do mesmo docker/selfhost/Dockerfile e publicadas a cada versão. A stack do Compose também baixa as imagens oficiais mongo:8, redis:8-alpine e quay.io/minio/minio.

Configuração

O instalador pergunta qual configuração você deseja, verifica os pré-requisitos (oferecendo a instalação do Docker), grava o arquivo de ambiente com os segredos já gerados e baixa as imagens. Ele nunca inicia nada por conta própria: os modos Docker precisam primeiro de um serviço de e-mail, portanto ele termina imprimindo o comando a ser executado. Executá-lo novamente é seguro: um arquivo de ambiente existente nunca é sobrescrito, servindo também como caminho de atualização.

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

Configurações do instalador

Sem --mode (ou INTLAYER_MODE), o instalador exibe um menu: desktop, docker (tudo-em-um) ou compose. Ele também lê algumas variáveis de ambiente. Como é passado via pipe para a shell, passe-as para a shell em vez 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

As variáveis de porta alteram apenas o lado do host do mapeamento. As imagens publicadas possuem http://localhost:3000, http://localhost:3100 e http://localhost:9000 compiladas no pacote do painel, portanto mantenha os padrões a menos que construa suas próprias imagens, consulte Limitações.

Configuração inicial

Em uma nova instância (banco de dados vazio), a abertura do painel redireciona você para a página /init:

1. Crie a primeira conta. Como a coleção de usuários está vazia, esta conta é automaticamente promovida a super admin.
2. Um e-mail de verificação é enviado pelo Resend ou relay SMTP. A verificação do e-mail é obrigatória, por isso um serviço de e-mail deve ser configurado antes de iniciar.
3. Clique no link no e-mail e depois faça login.

Quando um administrador já existir, /init redireciona para a página de login padrão.

Variáveis de ambiente

Ambos os modos Docker leem o mesmo arquivo (intlayer.env para o contêiner, .env para Compose), gerado a partir de docker/selfhost/.env.template.

Obrigatórias

Fixadas pela implantação

Estas são definidas pela imagem (tudo-em-um) ou pelo arquivo compose, e só precisam ser sobrescritas para uma topologia fora do padrão. DOMAIN, APP_URL, BACKEND_URL e S3_PUBLIC_URL são a exceção: definidas no arquivo env, elas têm precedência em ambos os modos (consulte Domínio personalizado).

O serviço Compose app recebe adicionalmente INTLAYER_BACKEND_INTERNAL_URL=http://backend:3100: o navegador acessa a API em localhost:3100, mas a renderização do lado do servidor é executada dentro da rede Compose e deve usar o nome do serviço.

Domínio personalizado

O backend lê suas URLs públicas em tempo de execução, mas o painel as tem compiladas: as imagens publicadas intlayer/cms-frontend e intlayer/cms-all só funcionam em http://localhost:3000. Servir o Intlayer no seu próprio domínio exige, portanto, duas coisas, ambas preparadas pelo instalador quando você responde à pergunta do domínio:

1. Quatro variáveis no arquivo env, lidas pelo backend (cookies, links de e-mail, callbacks OAuth, URLs de recursos) e usadas como build args pelo docker-compose.build.yml:

   intlayer.env

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   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. Uma imagem do painel compilada com essas URLs. O Docker a compila diretamente a partir do repositório, sem necessidade de cópia local:

   sh

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   # 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
   

Em seguida, coloque um reverse proxy com TLS na frente do contêiner: cms.example.org → porta 3000, back.example.org → 3100, s3.example.org → 9000. Os três hosts devem compartilhar o sufixo DOMAIN, já que o cookie de sessão é restrito a ele.

Opcionais (as funcionalidades degradam graciosamente quando ausentes)

Mailer global

Cada e-mail transacional, incluindo e-mails fora da organização como redefinições de senha e links mágicos, passa por um dos dois transportes globais:

• Resend, usando RESEND_API_KEY.
• SMTP, usando as variáveis MAIL_SMTP_*. Assim que MAIL_SMTP_HOST for definido, o SMTP será usado e RESEND_API_KEY será ignorado.

MAIL_PROVIDER só é necessário para forçar um transporte quando ambos estiverem configurados (por exemplo, MAIL_PROVIDER=resend para manter o Resend enquanto um host SMTP estiver presente).

Precedência: o mailer da própria organização (configurado no painel da Organização) tem prioridade sobre o mailer global, que por sua vez tem prioridade sobre a chave padrão do Resend.

Conectando seu projeto Intlayer

Assim que a stack estiver em execução, aponte seu projeto para o backend e painel auto-hospedados em vez de intlayer.org.

Configuração do projeto

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>

Crie credenciais de acesso em seu painel auto-hospedado em Projetos → Chaves de acesso em http://localhost:3000/projects.

SDK @intlayer/api

Ao usar o SDK @intlayer/api programaticamente, passe backendURL explicitamente:

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

Limitações

• Um domínio personalizado exige recompilar. Todas as URLs VITE_* voltadas para o navegador são embutidas no painel no momento da compilação, e as imagens publicadas (e o aplicativo desktop) vêm com valores de localhost / Intlayer Cloud. Por padrão, o painel deve ser acessado em http://localhost:3000, a API em :3100 e o MinIO em :9000; remapear as portas do host tem o mesmo efeito. O instalador prepara tudo para uma recompilação a partir do repositório quando você informa um domínio (consulte Domínio personalizado), mas a compilação em si leva vários minutos. Apontar o aplicativo desktop para um backend auto-hospedado não é suportado.
• O e-mail requer um serviço funcional. A configuração inicial impõe a verificação de e-mail, portanto RESEND_API_KEY ou um relay SMTP (MAIL_SMTP_*) deve ser configurado. Depois que o primeiro administrador faz login, cada organização também pode configurar seu próprio serviço SMTP ou Resend a partir do painel.
• O aplicativo desktop precisa de Node.js na máquina para iniciar seu servidor embutido.
• Sem assistente de documentação. O assistente de documentação com IA do intlayer.org (/api/ai/ask, /api/search/doc) depende de cerca de 130 MB de embeddings de documentação pré-calculados que as imagens auto-hospedadas não incluem; essas duas rotas não são registradas no modo auto-hospedado. Os recursos de IA próprios do painel (tradução, auditoria, autocompletar, chat) não são afetados e só precisam de OPENAI_API_KEY.

Links úteis

• Documentação do Intlayer CMS
• Referência de configuração
• SDK do CMS: @intlayer/api
• Releases do aplicativo desktop
• Docker Hub: intlayer/cms-all, intlayer/cms-frontend, intlayer/cms-backend, espelhado no GHCR em ghcr.io/aymericzip/intlayer/
• docker/selfhost/: Dockerfile, docker-compose.yml e .env.template