Configuração do gemini-cli-openai com o Docker Compose

README.md

Tutorial: Configurando o gemini-cli-openai com Docker

Este guia detalha como configurar e executar a imagem ghcr.io/gewoonjaap/gemini-cli-openai:main usando Docker Compose.

Passo 1: Obtenha a Credencial de Autenticação (GCP_SERVICE_ACCOUNT)

A aplicação precisa de uma credencial OAuth para se autenticar com os serviços do Google. O método mais simples é gerá-la usando o gemini-cli oficial.

1. Instale o @google/gemini-cli via npm. Abra seu terminal e execute:

   npm install -g @google/gemini-cli

2. Faça o login. Este comando iniciará um fluxo de autenticação no seu navegador.

   gemini auth login

3. Localize e copie o conteúdo da credencial. Após o login, a ferramenta cria o arquivo oauth_creds.json. Para obter seu conteúdo formatado como uma única linha (que é como a variável de ambiente espera), execute o comando abaixo:

   cat ~/.gemini/oauth_creds.json | jq -c .

   Nota: Se você não tiver o utilitário jq, pode abrir o arquivo ~/.gemini/oauth_creds.json manualmente, copiar todo o seu conteúdo e remover as quebras de linha para transformá-lo em uma única string.

   O resultado será algo como: {"client_id":"...", "client_secret":"...", "refresh_token":"...", "type":"authorized_user"}. Copie esta string para usar no próximo passo.

Passo 2: Crie o Arquivo de Variáveis de Ambiente (.dev.vars)

Este arquivo conterá a credencial e outras configurações para a aplicação.

1. Crie o arquivo. Em um diretório de sua escolha no seu computador (por exemplo, no seu diretório home), crie o arquivo gemin-account-1.dev.vars.

   Importante: Anote o caminho completo para este arquivo (ex: /home/seu-usuario/gemin-account-1.dev.vars), pois você precisará dele para o docker-compose.yaml.

2. Preencha o arquivo. Cole o conteúdo abaixo dentro do arquivo. Na variável GCP_SERVICE_ACCOUNT, cole a string de linha única que você copiou no passo anterior.

   GCP_SERVICE_ACCOUNT={"client_id":"...", "client_secret":"...", "refresh_token":"...", "type":"authorized_user"}
   ENABLE_REAL_THINKING=true
   ENABLE_AUTO_MODEL_SWITCHING=false
   STREAM_THINKING_AS_CONTENT=false
   ENABLE_GEMINI_NATIVE_TOOLS=true
   ENABLE_GOOGLE_SEARCH=true
   GEMINI_TOOLS_PRIORITY=native_first

Passo 3: Crie o Arquivo docker-compose.yaml

Crie um arquivo chamado docker-compose.yaml e cole o conteúdo abaixo.

Atenção: Lembre-se de ajustar o caminho no bind mount do volume para apontar para o local onde você criou o arquivo .dev.vars.

version: '3.8'

services:
  gemini-cli:
    # Imagem do Docker a ser utilizada
    image: ghcr.io/gewoonjaap/gemini-cli-openai:main
    
    # Mapeamento de portas: expõe a porta 8787 do contêiner na porta 80 do host
    ports:
      - "80:8787"
    
    # Mapeamento dos volumes de persistência
    volumes:
      # Volume nomeado pelo Docker para persistir dados da aplicação
      - app-account-1-gemini-cli-to-open-ai:/app/.mf
      
      # Bind mount para o arquivo de variáveis de ambiente no host.
      # !! ATENÇÃO !! Altere o caminho abaixo para o local correto do seu arquivo.
      - /home/your-user/gemin-account-1.dev.vars:/app/.dev.vars:ro
    
    # Política de reinicialização para o contêiner
    restart: unless-stopped

# Definição do volume nomeado
volumes:
  app-account-1-gemini-cli-to-open-ai:

Passo 4: Execute o Contêiner

Com os dois arquivos prontos (.dev.vars e docker-compose.yaml), navegue até o diretório onde o docker-compose.yaml foi salvo e execute o seguinte comando para iniciar o serviço em segundo plano:

docker-compose up -d

Passo 5: Configure seu Cliente

Após o contêiner estar rodando, a aplicação estará acessível em http://localhost.

Para que suas aplicações clientes (como LLM UIs, scripts, etc.) se comuniquem corretamente com a API compatível com OpenAI, é essencial configurar a URL base (Base URL) da seguinte forma:

URL Base da API: http://localhost/v1

O sufixo /v1 é obrigatório. Ele garante que as requisições sejam direcionadas para os endpoints corretos, como /v1/chat/completions.

Observação Importante: Streaming e Proxies Reversos (Traefik, Nginx)

O padrão de API da OpenAI utiliza Server-Sent Events (SSE) para fazer o streaming da resposta (o efeito de "digitação" em tempo real). Proxies reversos como Traefik, Nginx ou Caddy podem, por padrão, armazenar a resposta em um buffer antes de enviá-la ao cliente.

• O Problema: Esse comportamento de buffer quebra a experiência de streaming. Em vez de receber a resposta palavra por palavra, você verá um longo tempo de "pensamento" e, em seguida, receberá todo o texto de uma só vez.

• Solução Simples (Recomendada): A forma mais fácil de evitar isso é usar o mapeamento de porta direto do Docker (ports: - "80:8787"), como feito neste tutorial. Isso expõe o serviço diretamente, garantindo que o streaming funcione.

• Solução com Proxy: Se você precisa usar um proxy reverso, deve desabilitar o buffer de resposta para a rota que aponta para este serviço.

Anexo: Configuração para Usuários do CapRover

Se você utiliza o CapRover para gerenciar suas aplicações, o proxy reverso Nginx padrão irá causar o problema de buffering descrito acima. Para corrigi-lo, você precisa personalizar a configuração do Nginx para esta aplicação específica.

Siga os passos:

1. Acesse o painel do seu CapRover.

2. Vá para Apps e selecione a aplicação correspondente.

3. Clique na aba HTTP Settings.

4. Role para baixo até a seção Customize Nginx Configuration.

5. Dentro do bloco location / { ... }, localize as diretivas proxy_set_header. Adicione as três linhas destacadas abaixo para desabilitar o buffering e ajustar o timeout.

   ...
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
   
           # --- Adicione as linhas abaixo para habilitar o streaming (SSE) ---
           proxy_buffering off;
           proxy_cache off;
           proxy_read_timeout 86400s; # Evita que a conexão caia por inatividade
           # -----------------------------------------------------------------
   
       <%
       if (s.websocketSupport) {
       %>
   ...

6. Clique em Save & Update para aplicar as alterações.

Com essa modificação, o Nginx do CapRover deixará de fazer buffer na resposta, e o streaming da API funcionará corretamente em tempo real.