Configuração Docker do Odysseus AI: 7 checagens antes de expor o workspace
Guia prático para clonar Odysseus AI, criar .env, iniciar Compose, encontrar a primeira senha admin, conectar Ollama no host, preservar dados e manter serviços internos privados.
Neste guia
A rota Docker é útil porque cria um stack local repetível sem espalhar dependências pelo sistema host. Mas Docker também cria fronteiras: localhost dentro do contêiner não é o host, volumes definem o que sobrevive a rebuilds, e serviços auxiliares podem virar risco se portas demais forem publicadas.
Quando usar Docker
A rota Docker é útil porque cria um stack local repetível sem espalhar dependências pelo sistema host. Mas Docker também cria fronteiras: localhost dentro do contêiner não é o host, volumes definem o que sobrevive a rebuilds, e serviços auxiliares podem virar risco se portas demais forem publicadas.
Siga a ordem: contêiner da aplicação, endpoint do modelo e só depois exposição de rede. Comandos não devem ser traduzidos; traduza a explicação ao redor.
Para a maioria dos iniciantes, Docker Compose é o caminho mais limpo: clone o repositório oficial, copie .env.example para .env, rode docker compose up -d --build, abra localhost:7000 e veja docker compose logs odysseus para a primeira senha admin. Não exponha o stack antes de revisar autenticação, HTTPS, portas e endpoints de modelos.
Resposta curta
Para a maioria dos iniciantes, Docker Compose é o caminho mais limpo: clone o repositório oficial, copie .env.example para .env, rode docker compose up -d --build, abra localhost:7000 e veja docker compose logs odysseus para a primeira senha admin. Não exponha o stack antes de revisar autenticação, HTTPS, portas e endpoints de modelos.
Execute Docker Compose em uma ordem limpa e verificável
Comece pelo repositório oficial, não por comandos copiados. Branches, GPU, portas e nomes de serviços podem mudar rápido.
Confirme que Docker Desktop ou o daemon está ativo e que a pasta do repo não cria problemas de permissão.
1. Clonar o repositório certo
Use o repositório oficial e escolha main ou uma branch de desenvolvimento antes de editar arquivos.
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus2. Criar o arquivo de ambiente
Copie o exemplo para que Compose e app leiam padrões locais explícitos. Não compartilhe .env.
cp .env.example .env3. Construir e iniciar o stack
O primeiro build pode demorar porque baixa imagens e dependências. Espere terminar antes de depurar.
docker compose up -d --build4. Verificar saúde e credenciais
Abra a UI local só quando os contêineres estiverem saudáveis. A primeira senha admin aparece nos logs do Odysseus.
docker compose ps
docker compose logs odysseusEntenda .env, porta 7000 e o que deve ficar acessível
A UI web é normalmente a única parte necessária no navegador. O quickstart público aponta para http://localhost:7000.
Serviços auxiliares do Compose não devem ser expostos só porque a UI funciona.
| Configuração ou checagem | O que comprova | O que evitar |
|---|---|---|
| .env copiado do exemplo | A app lê valores locais explícitos. | Rodar com variáveis herdadas desconhecidas. |
| localhost:7000 | O navegador alcança a UI no porto local esperado. | Abrir serviços auxiliares achando que são a app. |
| docker compose ps | Cada serviço esperado está ativo ou mostra falha. | Alterar modelos antes do contêiner estar saudável. |
| logs odysseus | O caminho de início e credenciais iniciais aparecem. | Compartilhar logs com senhas ou tokens. |
Conecte Ollama no host sem confundir localhost do contêiner
Ollama costuma ser um servidor de modelos separado. Se Odysseus está no contêiner e Ollama no host, localhost do contêiner não é o host.
Teste Ollama no host, depois do contêiner, e só então salve o endpoint no Odysseus AI.
Endpoint comum de Docker para Ollama no host
http://host.docker.internal:11434/v1| Onde Odysseus roda | Onde Ollama roda | Endpoint inicial |
|---|---|---|
| Contêiner Docker | Máquina host | http://host.docker.internal:11434/v1 |
| Contêiner Docker | Mesma rede Compose | Use o nome do serviço e a porta interna do Compose. |
| Processo nativo no host | Mesmo host | http://127.0.0.1:11434/v1 |
| Servidor remoto | Outra máquina | Use HTTPS ou rede privada deliberada, não uma porta crua exposta. |
Saiba o que sobrevive a rebuilds, atualizações e reinícios
Um workspace com contas, documentos e configurações não é descartável.
Comandos Compose têm impactos diferentes. Reiniciar não é apagar volumes.
| Ação | Quando usar | Risco |
|---|---|---|
| docker compose restart | O stack já foi construído e só precisa reiniciar serviços. | Baixo; o estado normalmente permanece. |
| docker compose pull && docker compose up -d --build | Atualizar imagens e reconstruir do source atual. | Médio; leia o README antes. |
| docker compose down | Parar e remover contêineres mantendo volumes. | Geralmente seguro, mas confira Compose. |
| docker compose down -v | Remover volumes de propósito para reset. | Alto; pode apagar estado do workspace. |
Matriz de problemas no primeiro boot
Separe build, saúde dos contêineres, navegador, credenciais e modelos. Corrija a primeira camada que falhar.
| Sintoma | Causa provável | Primeira correção |
|---|---|---|
| Comando Docker não reconhecido | Docker Desktop ou daemon não está instalado, iniciado ou disponível. | Inicie Docker e rode docker version. |
| Build ok mas localhost:7000 não carrega | Contêineres iniciando, porta diferente ou serviço não saudável. | Rode docker compose ps e logs odysseus. |
| Senha admin inicial não aparece | Log passou, já existe estado ou .env define credenciais. | Confira logs odysseus e .env. |
| Ollama funciona no host mas não no Odysseus | O contêiner usa localhost em vez do gateway do host. | Use host.docker.internal:11434/v1 na mesma camada. |
| Dados somem após limpeza | Volumes foram removidos. | Restaure backup e evite down -v sem reset intencional. |
Checklist de segurança antes de LAN, túnel ou proxy reverso
Um workspace de IA auto-hospedado pode tocar arquivos, prompts, documentos, modelos e ferramentas.
Publique só a UI necessária, mantenha serviços internos privados, troque credenciais e use HTTPS para acesso remoto.
- Troque a credencial admin antes de permitir acesso externo.
- Revise cada porta publicada no Compose.
- Não exponha ChromaDB, modelos e serviços auxiliares.
- Use HTTPS e proxy confiável.
- Não publique .env, logs ou capturas com segredos.
- Faça backup de volumes antes de atualizações ou limpeza destrutiva.
Padrão seguro
Mantenha Odysseus AI em localhost até revisar autenticação, portas, HTTPS, firewall e endpoint de modelo.
FAQ
Referências
- Official Odysseus AI GitHub repository - Current README, Docker quick start, feature list, and security notes.
- Docker Compose documentation - Reference for Compose commands, services, networks, and volumes.
- Docker Desktop networking documentation - Host-to-container and container-to-host networking behavior.
- Ollama API documentation - Endpoint checks for local model server connectivity.
Guias relacionados
- Configuração Odysseus AI com Ollama - Leia se Docker funciona mas o modelo ainda não conecta.
- Odysseus AI no Windows - Notas para WSL2, Docker Desktop, firewall e endpoints do host.
- Odysseus AI no macOS - Compare Docker com o caminho nativo Apple Silicon.
- README oficial do Odysseus - Verifique comandos atuais antes de executar.
Última atualização: 22 de junho de 2026
Voltar ao Wiki Odysseus AI