Hospede o LibreChat para ter seu próprio app no estilo ChatGPT

O LibreChat é uma interface web open-source no estilo ChatGPT que conversa com OpenAI, Anthropic, Google e dezenas de outros provedores de modelo (ou um local) usando suas próprias chaves de API, em vez de passar suas conversas pelo produto de chat de terceiros. A única coisa que ele precisa e que não se encaixa nos add-ons comuns de Postgres ou Redis do Railyard é o MongoDB, que é onde a maioria das tentativas de self-host desanda. No final deste guia, você vai ter o LibreChat e o MongoDB rodando juntos atrás de HTTPS, com segredos reais gerados em vez dos valores padrão, e um backup do qual você consegue restaurar.

O que você vai precisar

• Um servidor com Docker e o plugin Compose. Um Hetzner CX23 (2 vCPUs, 4 GB de RAM, 40 GB NVMe, €5,99/mês sem VAT) roda o LibreChat e o MongoDB com folga, já que a inferência real do modelo acontece nos servidores do provedor, não nos seus.
• Um domínio ou subdomínio apontado para o IP do servidor.
• Pelo menos uma chave de API de um provedor de modelo (OpenAI, Anthropic, ou qualquer outro que o LibreChat suporte), adicionada depois que o app estiver no ar.
• Acesso SSH ao servidor.

Etapa 1: Gere os segredos de verdade

O LibreChat vem com valores de placeholder para os segredos de JWT e de criptografia de credenciais, que funcionam para um teste local, mas não são seguros para rodar em produção. Quatro valores precisam de dados reais e únicos: um segredo JWT, um segredo de refresh do JWT, uma chave de criptografia de credenciais e o vetor de inicialização dela. Os dois últimos têm requisitos exatos de tamanho que os outros não têm: CREDS_KEY precisa ser uma chave de 32 bytes (64 caracteres hex), e CREDS_IV precisa ser exatamente um IV de 16 bytes (32 caracteres hex), ou a própria criptografia AES-CBC do LibreChat lança algorithm.iv must contain exactly 16 bytes na inicialização:

openssl rand -hex 32   # JWT_SECRET
openssl rand -hex 32   # JWT_REFRESH_SECRET
openssl rand -hex 32   # CREDS_KEY (32 bytes)
openssl rand -hex 16   # CREDS_IV (16 bytes)
openssl rand -hex 24   # MONGO_PASSWORD

mkdir -p /opt/librechat
cat > /opt/librechat/.env <<'EOF'
JWT_SECRET=paste-the-first-value-here
JWT_REFRESH_SECRET=paste-the-second-value-here
CREDS_KEY=paste-the-third-value-here
CREDS_IV=paste-the-fourth-value-here
MONGO_PASSWORD=paste-the-fifth-value-here
EOF
chmod 600 /opt/librechat/.env

Etapa 2: Escreva o arquivo Compose

services:
  librechat:
    image: ghcr.io/danny-avila/librechat:v0.8.7
    restart: unless-stopped
    env_file: .env
    depends_on:
      - mongo
    environment:
      MONGO_URI: mongodb://librechat:${MONGO_PASSWORD}@mongo:27017/LibreChat?authSource=admin
      DOMAIN_CLIENT: https://chat.yourdomain.com
      DOMAIN_SERVER: https://chat.yourdomain.com
      ALLOW_REGISTRATION: "true"
    volumes:
      - librechat_uploads:/app/uploads
    expose:
      - "3080"

  mongo:
    image: mongo:7
    restart: unless-stopped
    environment:
      MONGO_INITDB_ROOT_USERNAME: librechat
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD}
    volumes:
      - librechat_mongo_data:/data/db

  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      - librechat

volumes:
  librechat_uploads:
  librechat_mongo_data:
  caddy_data:
  caddy_config:

Este guia fixa a v0.8.7, a release estável atual no momento em que isso foi escrito. MONGO_URI carrega o usuário e a senha com que o MongoDB foi inicializado na Etapa 1, junto com authSource=admin, já que o usuário root é criado no banco admin, não no LibreChat. DOMAIN_CLIENT e DOMAIN_SERVER precisam, os dois, da URL HTTPS exata pela qual os usuários vão acessar o app; o LibreChat usa elas para construir cookies e regras de CORS, então uma divergência aqui aparece como uma falha de login confusa em vez de um erro de configuração óbvio. ALLOW_REGISTRATION vem como true por padrão na imagem upstream, e importa aqui porque o LibreChat não tem nenhum outro jeito embutido de criar a primeira conta, o login social também vem desligado por padrão, então isso não é opcional até a Etapa 4.

Confira se o arquivo é interpretado corretamente:

docker compose config

Etapa 3: Aponte o DNS, adicione o Caddy, inicie a stack

chat.yourdomain.com {
	reverse_proxy librechat:3080
}

docker compose up -d

docker compose ps
curl -I https://chat.yourdomain.com

Você deve ver os dois serviços Up e o curl retornando HTTP/2 200 com um certificado válido.

Etapa 4: Crie sua conta, depois tranque a porta

Acesse https://chat.yourdomain.com, registre-se pelo formulário de cadastro normal e confirme que consegue fazer login. Depois que todas as contas que você precisa existirem, desligue o cadastro:

environment:
  ALLOW_REGISTRATION: "false"

docker compose up -d librechat

Etapa 5: Adicione um provedor de modelo

O próprio LibreChat nunca vem com uma chave de API de modelo embutida; ele é um cliente para provedores que você mesmo traz. Adicione sua chave como variável de ambiente, usando a OpenAI como exemplo:

environment:
  OPENAI_API_KEY: ${OPENAI_API_KEY}

Adicione OPENAI_API_KEY=your-real-key ao .env, depois rode docker compose up -d librechat de novo. Abra o app, escolha o provedor no menu de modelos e envie uma mensagem. Você deve receber uma resposta real, não um erro de chave ausente ou inválida.

Etapa 6: Faça backup do MongoDB e dos uploads

Conversas, contas e credenciais criptografadas vivem todos no MongoDB; arquivos enviados vivem no volume librechat_uploads.

cat > /opt/librechat/backup.sh <<'EOF'
#!/bin/sh
cd /opt/librechat
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
docker compose exec -T mongo mongodump --authenticationDatabase admin \
  -u librechat -p "${MONGO_PASSWORD}" --db LibreChat --archive --gzip > backups/mongo-$TIMESTAMP.archive.gz
find backups -mtime +14 -delete
EOF
mkdir -p /opt/librechat/backups
chmod +x /opt/librechat/backup.sh
(crontab -l 2>/dev/null; echo "0 3 * * * /opt/librechat/backup.sh") | crontab -

Rode uma vez à mão e confira que funcionou: ./backup.sh && ls -lh backups. Você deve ver um arquivo .archive.gz com data. Para restaurar é mongorestore --authenticationDatabase admin -u librechat -p "$MONGO_PASSWORD" --archive=path/to/file --gzip, rodado da mesma forma pelo docker compose exec. Copie os backups para fora do servidor; perder tanto o volume ativo do MongoDB quanto o único backup dele significa que toda conversa e credencial salva se vai.

Etapa 7: Faça upgrade

docker compose pull librechat
docker compose up -d librechat

O LibreChat roda suas próprias migrações de dados contra o MongoDB automaticamente na inicialização, quando necessário. Confira as release notes da versão para a qual você está migrando antes de um salto de várias versões, já que uma mudança que quebra o esquema de criptografia de credenciais seria a única categoria que vale a pena ler sobre antes de mais nada.

O caminho curto: faça com o Railyard

Tudo isso acima, o MongoDB como o único banco de dados que o LibreChat genuinamente não consegue compartilhar com os add-ons de Postgres ou Redis do Railyard, os segredos de JWT e de credenciais gerados em vez de deixados no padrão, o volume de uploads, é também o que o template de stack do LibreChat no Railyard configura para você. Conecte um servidor e escolha LibreChat no catálogo de templates: app.railyard.run/deploy?stack=librechat. O Railyard gera JWT_SECRET, JWT_REFRESH_SECRET, CREDS_KEY e o CREDS_IV de 16 bytes para você nos tamanhos corretos, liga a string de conexão do MongoDB automaticamente, e emite HTTPS para o seu domínio; você ainda adiciona sua própria chave de provedor de modelo depois, da mesma forma que na Etapa 5 acima.

Veja deploy with a button e databases and backups para entender como templates e dados persistentes funcionam na plataforma de forma mais geral.

Solução de problemas

O login funciona, mas nada parece persistir entre reinicializações. Confirme que librechat_mongo_data é um volume nomeado real na saída de docker compose ps -a, não um anônimo que foi removido; isso geralmente remonta a um docker compose down -v anterior rodado por acidente, que remove volumes junto com os containers.

algorithm.iv must contain exactly 16 bytes na inicialização. O CREDS_IV não foi gerado com exatamente 16 bytes (32 caracteres hex). Rode openssl rand -hex 16 de novo, da Etapa 1, e confira se o valor no .env tem exatamente 32 caracteres, nem truncado nem preenchido com padding.

O formulário de cadastro retorna 403. ALLOW_REGISTRATION está em false e ainda não existe nenhuma conta, um problema de ovo e galinha se você desligou cedo demais. Volte para true, crie as contas que você precisa, e desligue de novo como na Etapa 4.

O menu de modelos mostra um provedor, mas toda mensagem falha. A chave de API daquele provedor não está definida, está inválida, ou ficou sem crédito do lado do próprio provedor; confira docker compose logs librechat para ver o erro específico vindo do provedor, o LibreChat geralmente repassa a mensagem original do provedor.

O HTTPS não é emitido. docker compose logs caddy mostrando erros repetidos de ACME quase sempre significa que o DNS da Etapa 3 não propagou ainda ou está apontando para o IP errado.

Perguntas frequentes

Posso rodar mais de um provedor de modelo ao mesmo tempo? Sim, adicione quantas chaves de API de provedor você quiser como variáveis de ambiente; os usuários escolhem qual modelo usar por conversa, no mesmo menu.

O LibreChat guarda minhas conversas com o provedor de modelo? Não, o provedor só vê a requisição que você envia para ele; o LibreChat guarda o histórico de conversas em si no seu próprio MongoDB, o provedor não é uma segunda cópia dos seus dados.

Posso rodar um modelo local em vez de uma API hospedada? Sim, o LibreChat suporta qualquer endpoint compatível com OpenAI, incluindo servidores de inferência locais, apontado através de uma configuração de endpoint customizado em vez de uma chave de API de provedor.

Por que MongoDB especificamente, quando tudo mais no Railyard é Postgres ou Redis? O próprio esquema e os padrões de consulta do LibreChat são construídos em torno do modelo de documentos do MongoDB desde o início; não é uma escolha que este guia ou o Railyard fazem, é o que o projeto upstream exige.

O que acontece se eu perder o servidor sem backup? Toda conversa, conta e credencial salva se vai; não existe caminho de recuperação para dados do MongoDB que nunca foram salvos em outro lugar, e é por isso que a Etapa 6 não é opcional na prática.

Depois que os segredos de verdade estão no lugar e o cadastro está travado, um LibreChat self-hosted basicamente some para o segundo plano. O trabalho contínuo é o hábito de backup da Etapa 6 e adicionar qualquer provedor de modelo que você realmente queira usar.