Pular para o conteúdo principal

Docker

O Docker é a maneira mais simples de fazer uma implantação com características de produção em um único servidor.

Para uma instalação em servidor único acessível pela Internet, comece por Implantação remota privada. Seu modelo do Compose não publica portas do aplicativo, usa por padrão a imagem main e adiciona uma barreira externa do Cloudflare Access, controles do host, backups e limites de contêineres.

Disponibilidade do Work​

O Work é ativado por padrão nos arquivos Compose do repositório. A imagem inclui a CLI do Docker, e o Compose monta /var/run/docker.sock; assim, os contêineres das tarefas do Work são irmãos do contêiner do Libre WebUI. Eles aparecem em docker ps no host.

Um processo com acesso a esse socket tem controle equivalente ao root do host Docker. Ativar o Work por padrão é uma escolha deliberada: o Work é um recurso central e não funciona sem acesso ao daemon. Como consequência, todo administrador do Libre WebUI é, na prática, um administrador do host. Planeje-se:

  • Mantenha a pilha em um host cujos administradores já sejam confiáveis.
  • Não exponha a porta publicada a uma rede não confiável.
  • Remova a montagem de /var/run/docker.sock quando o Work não for necessário. A página do Work passará a informar Ambiente de execução indisponível.

No Linux, o socket pertence ao grupo docker, e não ao root; portanto, o usuário sem privilégios de root do aplicativo precisa do ID desse grupo. Defina-o uma vez:

echo "DOCKER_GID=$(docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  alpine stat -c '%g' /var/run/docker.sock)" >> .env

Leia-o por meio de um contêiner, como mostrado. Um host macOS informa um valor diferente daquele visto pelo contêiner, porque o Docker Desktop encaminha o socket por meio de uma VM. Se o grupo estiver incorreto, a página do Work identificará o problema em vez de falhar silenciosamente. Consulte Work: espaços de trabalho isolados.

As prévias do Work e o Work Computer publicam portas aleatórias apenas em uma interface privada do host. O Docker Desktop funciona com os padrões do Compose: loopback do host para o bind e host.docker.internal para a conexão do backend. O Docker Engine nativo não alcança um listener no loopback do host a partir de um contêiner irmão. Em vez disso, defina o bind com o gateway não público da bridge do Docker:

echo "WORK_PREVIEW_BIND=$(docker network inspect bridge \
  --format '{{(index .IPAM.Config 0).Gateway}}')" >> .env
echo "WORK_DOCKER_PUBLISHED_HOST=host.docker.internal" >> .env
docker compose up -d --force-recreate libre-webui

Os arquivos Compose mapeiam host.docker.internal por meio de host-gateway. Nunca use WORK_PREVIEW_BIND=0.0.0.0; isso publicaria portas efêmeras de tarefas sem autenticação em todas as interfaces do host, em vez de mantê-las atrás do proxy assinado do Libre WebUI.

Ollama incluído​

Executa o Libre WebUI e o Ollama em uma única pilha do Compose:

docker compose up -d

Abra http://localhost:8080.

A porta da WebUI é vinculada ao loopback do host por padrão. Defina WEBUI_BIND_ADDRESS=0.0.0.0 somente quando uma LAN confiável ou um proxy reverso do host precisar acessá-la, e restrinja a porta com o firewall do host.

O Ollama permanece privado na rede do Compose. Para disponibilizá-lo a aplicativos do host no loopback, adicione a substituição explícita para o host:

docker compose -f docker-compose.yml -f docker-compose.ollama-host.yml up -d

Defina OLLAMA_BIND_ADDRESS somente quando outra máquina precisar acessar o Ollama e proteja essa porta com um firewall e um proxy compatível com autenticação.

GPU NVIDIA​

Use o arquivo Compose de GPU quando o Docker tiver acesso ao ambiente de execução da NVIDIA:

docker compose -f docker-compose.gpu.yml up -d

Confirme o acesso à GPU pelo contêiner do Ollama se os modelos ainda estiverem em execução na CPU.

Ollama externo​

Use esta opção quando o Ollama já estiver em execução no host ou em outro servidor:

docker compose -f docker-compose.external-ollama.yml up -d

Substitua a URL do Ollama, se necessário:

OLLAMA_BASE_URL=http://192.168.1.10:11434 docker compose -f docker-compose.external-ollama.yml up -d

Work isolado do socket​

Os arquivos Compose padrão montam o socket Docker no contêiner do Libre WebUI para que o Work possa executar contêineres de tarefas; essa montagem concede controle equivalente ao root do host Docker. Para manter o Work sem fornecer o socket ao aplicativo web, use a variante com proxy de socket:

docker compose -f docker-compose.socket-proxy.yml up -d

Um proxy de socket em uma rede interna mantém /var/run/docker.sock e encaminha somente as seções da API usadas pelo Work (contêineres, imagens, volumes, redes, exec, info). Endpoints de Swarm, secrets, configs, build e system são negados no proxy. O Libre WebUI o acessa por DOCKER_HOST=tcp://docker-socket-proxy:2375 — sem montagem de socket, sem DOCKER_GID, e o terminal interativo e os diagnósticos do sistema funcionam sem alterações. Consulte a documentação de espaços de trabalho para entender o que essa barreira cobre e o que não cobre.

Persistência de dados​

O Libre WebUI armazena os dados do backend em /app/backend/data dentro do contêiner. Os arquivos Compose montam esse caminho como um volume nomeado.

A imagem também usa esse caminho por padrão quando é iniciada diretamente com docker run; os arquivos temporários da verificação prévia do banco de dados ficam separados em /app/backend/temp. Monte /app/backend/data sempre que o contêiner puder ser recriado.

Para produção, defina segredos estáveis:

JWT_SECRET=replace-with-a-long-random-secret
ENCRYPTION_KEY=replace-with-64-hex-characters

Faça backup do volume de dados e da chave de criptografia juntos.

Antes de remover um contêiner iniciado diretamente e criado a partir de uma imagem mais antiga, confirme que /app/backend/data/.encryption_key existe ou registre o ENCRYPTION_KEY configurado. Imagens antigas podiam gravar uma chave gerada automaticamente apenas na camada do contêiner; excluir esse contêiner também exclui a única chave capaz de descriptografar seu banco de dados persistente.

Se você opera um ambiente de execução personalizado compatível com o Work, os arquivos das tarefas ficam em volumes nomeados separados do Docker e não estão incluídos no backup normal de /app/backend/data.

Acesso público​

Os arquivos Compose do repositório vinculam a WebUI ao loopback e definem CORS_ORIGIN diretamente. Um valor no seu shell ou arquivo .env não substitui esse literal. Edite a entrada libre-webui.environment ou salve uma substituição explícita como compose.origin.yml:

services:
  libre-webui:
    environment:
      CORS_ORIGIN: https://your-domain.example
      BASE_URL: https://your-domain.example

Aplique a substituição junto com o arquivo Compose selecionado do repositório:

docker compose -f docker-compose.yml -f compose.origin.yml up -d

Depois, coloque o Libre WebUI atrás de HTTPS usando um proxy reverso ou balanceador de carga da plataforma. Defina WEBUI_BIND_ADDRESS como a interface exata de que esse proxy precisa; não publique a porta em todas as interfaces, a menos que o firewall exija isso.

O servidor já entrega o frontend compilado de forma eficiente: os pacotes com hash em /js/ e /assets/ são enviados comprimidos com brotli ou gzip e com um tempo de cache immutable de um ano, enquanto index.html e o service worker são marcados como no-cache, de modo que uma nova versão passa a valer no carregamento seguinte. O proxy não precisa recomprimir nem armazenar essas rotas em cache; repasse o Accept-Encoding.

Comandos úteis​

docker compose ps
docker compose logs -f libre-webui
docker compose logs -f ollama
docker compose pull
docker compose up -d

Documentação relacionada​