Docker (Linux Remoto)

Para usar este guia, você precisa de um computador remoto ou uma VM implantada. Embora você possa usar este guia com uma instalação local, tenha em mente que ele foi originalmente escrito para implantação na nuvem.

⚠️ Este guia foi originalmente projetado para Digital Ocean, portanto, você pode precisar modificar as instruções para outras plataformas, mas a ideia principal permanece inalterada.

Parte I: Instalando o Docker e outras dependências:

Existem muitas maneiras de configurar o Docker em sistemas Linux. Vou guiá-lo pela melhor e mais recomendada maneira com base neste guia.

Observe que a "melhor" maneira para a instalação do Docker no Ubuntu não significa a "mais rápida" ou a "mais fácil". Significa a melhor maneira de instalá-lo para benefícios a longo prazo (ou seja, atualizações mais rápidas, patches de segurança, etc.).

1. Atualize e instale as dependências do Docker

Primeiro, vamos atualizar nossa lista de pacotes e instalar as dependências do Docker necessárias.

sudo apt update

Em seguida, use o seguinte comando para instalar as dependências ou pacotes de pré-requisitos.

sudo apt install apt-transport-https ca-certificates curl software-properties-common gnupg lsb-release

Notas de Instalação

• Digite "Y" para todos os prompts de terminal [Y/n] (sim/não) ao longo de todo este guia.
• Após o primeiro prompt [Y/n], você verá a primeira de algumas telas roxas solicitando a reinicialização dos serviços.
  • Cada vez que isso acontecer, você pode pressionar ENTER com segurança para as opções padrão, já selecionadas:

• Se em algum momento o console do seu droplet desconectar, faça o seguinte e depois continue de onde parou:
  • Acesse o console novamente conforme indicado acima
  • Mude para o usuário que você criou com su - <yourusername>

2. Adicionar o repositório Docker às fontes APT

Embora instalar o Docker Engine a partir dos repositórios do Ubuntu seja mais fácil, adicionar o repositório oficial do Docker oferece atualizações mais rápidas. Por isso, este é o método recomendado.

Primeiro, vamos obter a chave GPG necessária para conectar ao repositório do Docker. Para isso, use o seguinte comando.

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Em seguida, adicione o repositório à lista de fontes. Embora você também possa adicioná-lo manualmente, o comando abaixo fará isso automaticamente para você.

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

O comando acima preencherá automaticamente o seu codinome de lançamento (jammy para 22.04, focal para 20.04 e bionic para 18.04).

Por fim, atualize seus pacotes novamente.

sudo apt update

Se você esquecer de adicionar a chave GPG, a etapa acima falhará com uma mensagem de erro. Caso contrário, vamos prosseguir com a instalação do Docker no Ubuntu.

3. Instalar o Docker

Qual é a diferença entre docker.io e docker-ce?

docker.io é o pacote docker oferecido por algumas distribuições Linux populares (por exemplo, Ubuntu/Debian). docker-ce, por outro lado, é o pacote docker do repositório oficial do Docker. Normalmente, o docker-ce é mais atualizado e preferível.

Agora instalaremos o docker-ce (e não o pacote docker.io)

sudo apt install docker-ce

Tela roxa significa pressione ENTER. :)

Recomendado: você deve garantir que o usuário criado seja adicionado ao grupo docker para o uso contínuo de comandos:

sudo usermod -aG docker $USER

Agora, vamos reiniciar o sistema para garantir que tudo esteja bem.

sudo reboot

Após reiniciar, se estiver usando o console do droplet no navegador, você pode clicar em recarregar e aguardar para acessar o console novamente.

Lembrete: Sempre que você reiniciar com sudo reboot, você deve alternar para o usuário que configurou anteriormente com su - <yourusername>.

4. Verifique se o Docker está em execução no Ubuntu

Existem várias maneiras de verificar se o Docker está em execução no Ubuntu. Uma delas é usar o seguinte comando:

sudo systemctl status docker

Você deve ver uma saída que diz active (running) para o status.

Saia deste log pressionando CTRL (ou CMD) + C.

5. Instalar o Docker Compose

Como já adicionamos o repositório oficial do Docker no passo 2, instalar o Docker Compose é simples usando o plugin oficial do Compose:

sudo apt install docker-compose-plugin

Verifique a instalação:

docker compose version

Nota: O Docker Compose v2 usa o comando docker compose (sem hífen) em vez do legado docker-compose. Todos os comandos neste guia usam a sintaxe moderna.

6. Como parte deste guia, recomendo que você tenha o git e o npm instalados:

Embora não seja tecnicamente obrigatório, ter o git e o npm tornará a instalação/atualização muito simples:

sudo apt install git nodejs npm

Prepare as linhas da matrix.

Você pode confirmar se esses pacotes foram instalados com sucesso com o seguinte:

git --version
node -v
npm -v

Nota: isso pode instalar versões antigas do Node.js e npm. Se você executar o LibreChat diretamente no host, use o Node.js v24.16.0 com o npm v11.16.0. Para este guia baseado em Docker, a versão do Node.js no host não importa, pois o LibreChat é executado dentro de containers.

Ok, agora que você configurou o Droplet, você configurará o próprio aplicativo

Parte II: Configuração do LibreChat

1. Clone o repositório

A partir da linha de comando do droplet (como seu usuário, não como root):

# clone down the repository
git clone https://github.com/danny-avila/LibreChat.git

# enter the project directory
cd LibreChat/

2. Criar arquivos de configuração e ambiente do LibreChat

Arquivo de Config (librechat.yaml)

Em seguida, criamos o arquivo de configuração do LibreChat, também conhecido como librechat.yaml, permitindo a personalização das configurações do aplicativo, bem como endpoints personalizados.

Independentemente de você querer personalizar o aplicativo ainda mais, ele é necessário para o arquivo deploy-compose.yml que estamos usando, para que possamos criar um com o valor mínimo necessário para começar:

nano librechat.yaml

Você entrará na tela do editor e poderá colar o seguinte:

# For more information, see the Configuration Guide:
# https://www.librechat.ai/docs/configuration/librechat_yaml

# Configuration version (required)
version: 1.3.5
# This setting caches the config file for faster loading across app lifecycle
cache: true

Saia do editor com CTRL + X, depois Y para salvar e ENTER para confirmar.

Arquivo de ambiente (.env)

Os valores padrão são suficientes para você começar e executar o aplicativo, permitindo que você forneça suas credenciais a partir do aplicativo web.

# Copies the example file as your global env file
cp .env.example .env

No entanto, é altamente recomendado que você ajuste os valores "secret" de seus padrões para maior segurança. Os logs de inicialização da API irão avisá-lo caso você não o faça.

Para sua conveniência, você pode executar isto para gerar seus próprios valores:

https://www.librechat.ai/toolkit/creds_generator

nano .env

# FIND THESE VARIABLES AND REPLACE THEIR DEFAULT VALUES!

# Must be a 16-byte IV (32 characters in hex)

CREDS_IV=e2341419ec3dd3d19b13a1a87fafcbfb

# Must be 32-byte keys (64 characters in hex)

CREDS_KEY=f34be427ebb29de8d88c107a71546019685ed8b241d8f2ed00c3df97ad2566f0
JWT_SECRET=16f8c0ef4a5d391b26034086c628469d3f9f497f08163ab9b40137092f2909ef
JWT_REFRESH_SECRET=eaa5191f2914e30b9387fd84e254e4ba6fc51b4654968a9b0803b456a54b8418

Se você quiser fornecer quaisquer credenciais para que todos os usuários da sua instância possam consumir, você deve adicioná-las enquanto ainda estiver editando este arquivo:

OPENAI_API_KEY=sk-yourKey

Como antes, saia do editor com CTRL + X, depois Y para salvar e ENTER para confirmar.

É isso!

Para uma configuração completa, no entanto, você deve editar seu arquivo .env conforme necessário, e leia os comentários no arquivo e os recursos abaixo.

# if editing the .env file
nano .env

Esta é uma dessas variáveis de ambiente para se ter em mente. Isso desativa inscrições externas, caso você queira configurá-la após ter criado sua conta.

ALLOW_REGISTRATION=false

Recursos:

• Tokens/Apis/etc
• Sistema de Usuário/Autenticação

3. Iniciar o Docker

# should already be running, but just to be safe
sudo systemctl start docker

# confirm docker is running
docker info

Agora podemos iniciar o container do app. Pela primeira vez, usaremos o comando completo e, posteriormente, poderemos usar um comando abreviado.

sudo docker compose -f ./deploy-compose.yml up -d

É seguro fechar o terminal se desejar -- o aplicativo Docker continuará sendo executado.

Nota: isto está utilizando um arquivo compose especial otimizado para este ambiente implantado. Se você deseja mais configurações aqui, deve inspecionar os arquivos deploy-compose.yml e Dockerfile.multi para ver como eles estão configurados. Não estamos construindo a imagem neste ambiente, pois não há RAM suficiente para fazê-lo adequadamente. Em vez disso, puxamos a imagem dev-api mais recente do LibreChat, que é construída automaticamente após cada push para a main.

Se você estiver configurando um domínio para ser usado com o LibreChat, este arquivo compose está usando o arquivo nginx localizado em client/nginx.conf. Instruções sobre isso estão abaixo na parte V.

4. Assim que o aplicativo estiver em execução, você poderá acessá-lo em http://yourserverip

Volte para a página do droplet para obter o IP do seu servidor, copie-o e cole-o no seu navegador!

Inscreva-se, faça login e aproveite seu próprio LibreChat hospedado remotamente e de forma privada :)

Parte III: Atualizando o LibreChat

Tornei esta etapa bastante simples, desde que tudo acima tenha sido instalado com sucesso e você não tenha editado o histórico do git.

Nota: Se você estiver trabalhando em uma branch editada, com seus próprios commits, por exemplo, como com edições em client/nginx.conf, você deve inspecionar config/deployed-update.js para executar alguns dos comandos manualmente conforme achar adequado. Veja a parte V para mais informações sobre isso.

Execute o seguinte para uma atualização automatizada

npm run update:deployed

Parando o container Docker

npm run stop:deployed

Isso simplesmente executa docker compose -f ./deploy-compose.yml down

Iniciando o container Docker

npm run start:deployed

Isso simplesmente executa docker compose -f ./deploy-compose.yml up -d

Verificar containers Docker ativos

docker ps

Você pode atualizar manualmente sem os scripts caso encontre problemas.

docker compose -f ./deploy-compose.yml down

# Linux/Mac
docker images -a | grep "librechat" | awk '{print $3}' | xargs docker rmi

# Windows (PowerShell)
docker images -a --filter "reference=registry.librechat.ai/danny-avila/librechat*" --format "{{.ID}}" | ForEach-Object { docker rmi $_ }
docker images -a --filter "reference=ghcr.io/danny-avila/librechat*" --format "{{.ID}}" | ForEach-Object { docker rmi $_ }

git pull

docker compose -f ./deploy-compose.yml pull

docker compose -f ./deploy-compose.yml up

Parte IV: Editando o arquivo NGINX (para domínios personalizados e configurações avançadas)

Caso você queira editar o arquivo NGINX por qualquer motivo, como apontar seu servidor para um domínio personalizado, use o seguinte:

npm run stop:deployed

nano client/nginx.conf

Não vou explicar como configurar um domínio personalizado ou quaisquer outras alterações no NGINX; você pode consultar o guia do Cloudflare, o guia do Traefik ou o guia do NGINX para começar a usar domínios personalizados.

No entanto, mostrarei o que editar no lado do LibreChat para um domínio personalizado com esta configuração.

Como o NGINX está sendo usado como proxy pass por padrão, eu edito apenas o seguinte:

# before
server_name localhost;

# after
server_name custom.domain.com;

Nota: isso funciona porque o arquivo deploy-compose.yml está usando NGINX por padrão, ao contrário do arquivo docker-compose.yml principal. Como sempre, você pode configurar os arquivos compose conforme necessário.

Agora, envie essas alterações para uma branch separada:

# create a new branch
# example: git checkout -b edit
git checkout -b <branchname>

# stage all file changes
git add .

Para confirmar (commit) alterações em uma branch do git, você precisará se identificar no git. Estes podem ser valores fictícios, mas se você quiser que eles sejam sincronizados com o GitHub, caso envie esta branch para um repositório forked do LibreChat, use seu e-mail do GitHub.

# these values will work if you don't care what they are
git config --global user.email "[email protected]"
git config --global user.name "Your Name"

# Now you can commit the change
git commit -m "edited nginx.conf"

A atualização em um branch editado funcionará de forma um pouco diferente agora

npm run rebase:deployed

Você está pronto!

Aviso Você encontrará conflitos de merge se começar a editar significativamente a branch, e isso não é recomendado a menos que você saiba o que está fazendo.

Observe que quaisquer alterações no código neste ambiente não serão refletidas, pois o arquivo compose está extraindo as imagens Docker criadas automaticamente pelo GitHub.

Parte V: Use a Versão Estável Mais Recente em vez da Branch Main Mais Recente

Por padrão, esta configuração buscará as atualizações mais recentes da branch principal do LibreChat. Se você preferir a versão "estável" mais recente, que é definida pelas latest tags, você precisará editar o deploy-compose.yml e confirmar (commit) suas alterações exatamente como acima na Parte V. Esteja ciente de que você não se beneficiará dos recursos mais recentes assim que eles forem lançados se optar por isso.

Vamos editar o deploy-compose.yml:

nano deploy-compose.yml

Altere librechat-dev-api para librechat-api:

image: registry.librechat.ai/danny-avila/librechat-api:latest

Prepare e faça o commit como na Parte V, e pronto!