12 min de lectura 22 de junio de 2026

Configuración Docker de Odysseus AI: 7 comprobaciones antes de exponer el workspace

Guía práctica para clonar Odysseus AI, crear .env, arrancar Compose, encontrar la primera contraseña de administrador, conectar Ollama del host, conservar datos y mantener privados los servicios internos.

Odysseus AI Wiki

Notas editoriales no oficiales basadas en el README público de Odysseus, Docker Compose, rutas de modelos locales y problemas comunes de la comunidad.

Flujo editorial con repositorio, archivo de entorno, Docker Compose y navegador local para instalar Odysseus AI con Docker — La instalación Docker funciona mejor cuando cada paso tiene un dueño claro: archivos del repositorio, valores de entorno, servicios Compose y navegador local.

Respuesta corta: Para la mayoría de usuarios nuevos, Docker Compose es la ruta más limpia: clona el repositorio oficial, copia .env.example a .env, ejecuta docker compose up -d --build, abre localhost:7000 y revisa docker compose logs odysseus para la primera contraseña. No publiques el stack hasta decidir autenticación, HTTPS, puertos y endpoints de modelos.

La ruta Docker es atractiva porque ofrece un stack local repetible sin mezclar todas las dependencias en el sistema anfitrión. A cambio, Docker añade fronteras: un contenedor tiene su propio localhost, los volúmenes deciden qué sobrevive a una reconstrucción y los servicios auxiliares pueden ser peligrosos si publicas más puertos de los necesarios.

Cuándo usar Docker

Mantén este orden: primero verifica el contenedor de la app, luego el endpoint del modelo y finalmente la exposición de red. Si una traducción de un comando parece rara, conserva el comando original y cambia solo la explicación.

Para la mayoría de usuarios nuevos, Docker Compose es la ruta más limpia: clona el repositorio oficial, copia .env.example a .env, ejecuta docker compose up -d --build, abre localhost:7000 y revisa docker compose logs odysseus para la primera contraseña. No publiques el stack hasta decidir autenticación, HTTPS, puertos y endpoints de modelos.

Respuesta corta

Ejecuta Docker Compose en un orden limpio y verificable

Empieza desde el repositorio oficial, no desde un bloque de comandos copiado. Odysseus AI cambia rápido, y detalles como rama, overlays de GPU, puertos y nombres de servicios pueden variar.

En Windows, confirma que Docker Desktop está iniciado. En macOS o Linux, verifica que el daemon responde y que el repositorio está en una carpeta sin problemas de permisos.

1. Clona el repositorio correcto

Usa el repositorio oficial y decide si quieres la rama principal o una rama de desarrollo antes de editar archivos.

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

2. Crea el archivo de entorno

Copia el ejemplo para que Compose y la app lean valores explícitos. No compartas .env ni capturas con secretos.

cp .env.example .env

3. Construye e inicia el stack

La primera construcción puede tardar porque descarga imágenes y dependencias. Espera a que termine antes de depurar.

docker compose up -d --build

4. Comprueba salud y credenciales

Abre la UI local solo cuando los contenedores estén sanos. La primera contraseña aparece en los logs del servicio Odysseus.

docker compose ps
docker compose logs odysseus

Entiende .env, el puerto 7000 y qué debe estar realmente accesible

La UI web es la parte que normalmente necesitas en el navegador. En la ruta pública de inicio rápido, la URL local esperada es http://localhost:7000.

Un stack Compose puede incluir servicios auxiliares. No deben convertirse en entradas públicas solo porque la UI web funcione.

Ajuste o chequeo	Qué demuestra	Qué evitar
Archivo .env copiado del ejemplo	La app lee valores locales explícitos.	Ejecutar con variables heredadas sin saberlo.
localhost:7000	El navegador alcanza la UI web en el puerto local esperado.	Abrir servicios auxiliares y creer que son la app.
docker compose ps	Cada servicio esperado está activo o muestra su fallo.	Cambiar modelos antes de que el contenedor esté sano.
logs odysseus	La ruta de arranque y las credenciales iniciales son visibles.	Compartir logs con contraseñas o tokens.

Conecta Ollama del host sin confundir localhost del contenedor

Ollama suele ser un servidor de modelos separado. Si Ollama corre en el host y Odysseus AI dentro de un contenedor, localhost dentro del contenedor no apunta al host.

Prueba por capas: primero Ollama en el host, luego el acceso desde el contenedor, y finalmente guarda el endpoint en Odysseus AI.

Diagrama de un contenedor Docker de Odysseus AI conectando con Ollama en el host — El error común es usar localhost del contenedor cuando Ollama realmente vive en el host.

Endpoint habitual de Docker hacia Ollama en el host

http://host.docker.internal:11434/v1

Dónde corre Odysseus	Dónde corre Ollama	Endpoint inicial
Contenedor Docker	Máquina host	http://host.docker.internal:11434/v1
Contenedor Docker	Misma red Compose	Usa el nombre del servicio y el puerto interno de Compose.
Proceso nativo del host	Mismo host	http://127.0.0.1:11434/v1
Servidor remoto	Otra máquina	Usa HTTPS o red privada deliberada, no un puerto crudo expuesto.

Sabe qué sobrevive a rebuilds, actualizaciones y reinicios

Docker facilita reconstruir, pero un workspace deja de ser desechable cuando contiene cuentas, documentos, memoria o configuración.

Usa comandos Compose con intención. Reiniciar no es lo mismo que borrar volúmenes.

Acción	Cuándo usarla	Riesgo
docker compose restart	El stack ya está construido y solo necesitas reiniciar servicios.	Bajo; el estado normalmente permanece.
docker compose pull && docker compose up -d --build	Quieres refrescar imágenes y reconstruir desde la fuente actual.	Medio; lee notas del README antes.
docker compose down	Quieres detener y quitar contenedores conservando volúmenes.	Normalmente seguro, pero revisa Compose.
docker compose down -v	Quieres borrar volúmenes para reiniciar desde cero.	Alto; puede borrar el estado del workspace.

Matriz de errores del primer arranque

Separa build, salud de contenedores, acceso del navegador, credenciales y modelos. Arregla la primera capa que falla.

Síntoma	Causa probable	Primera solución
Docker no se reconoce	Docker Desktop o el daemon no está instalado, iniciado o disponible.	Inicia Docker y ejecuta docker version antes de reconstruir.
Build correcto pero localhost:7000 no carga	Contenedores arrancando, puerto distinto o servicio no sano.	Ejecuta docker compose ps y logs odysseus; verifica el puerto.
No aparece la contraseña admin	El log pasó, hay estado previo o credenciales en .env.	Revisa logs odysseus y .env.
Ollama funciona en host pero no en Odysseus	El contenedor usa localhost en vez del gateway del host.	Usa host.docker.internal:11434/v1 y prueba desde la misma capa.
Los datos desaparecen tras limpiar	Se eliminaron volúmenes.	Restaura backup y evita down -v salvo reset intencional.

Checklist de seguridad antes de LAN, túnel o proxy inverso

Un workspace de IA autoalojado puede tocar archivos, prompts, documentos, modelos y herramientas. El control local solo ayuda si el límite de despliegue es claro.

La pauta segura es publicar solo la UI necesaria, mantener privados los servicios internos, cambiar credenciales y usar HTTPS para acceso remoto.

Cambia o define la credencial de administrador antes de permitir acceso a otras personas.
Revisa docker compose ps y el archivo Compose para cada puerto publicado.
Mantén ChromaDB, servicios de notificación, modelos y bases fuera de internet público.
Usa HTTPS y un proxy confiable antes del acceso remoto.
No subas .env, logs ni capturas con tokens o contraseñas generadas.
Haz copia de volúmenes antes de upgrades, migraciones o limpiezas destructivas.

Valor seguro por defecto

Mantén Odysseus AI en localhost hasta revisar autenticación, puertos, HTTPS, firewall y endpoint del modelo.

Preguntas frecuentes

Para una primera instalación limpia, normalmente sí. Docker Compose evita mezclar dependencias con el host, aunque las rutas nativas pueden ser mejores para GPU o desarrollo.

La ruta pública de inicio rápido apunta a http://localhost:7000 cuando los contenedores están sanos. Si cambiaste el puerto en .env, usa ese puerto.

Revisa docker compose logs odysseus. Si ya existe estado persistente o definiste credenciales en .env, el comportamiento puede cambiar.

Ambas opciones pueden funcionar. Si Odysseus está en Docker y Ollama en el host, normalmente usarás host.docker.internal:11434/v1.

No expongas el stack local por defecto. Revisa autenticación, HTTPS, firewall y servicios auxiliares antes de cualquier acceso remoto.

Haz copia de volúmenes, lee el README actual y reconstruye con intención. Evita borrar volúmenes salvo que quieras resetear.

Referencias

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.

Guías relacionadas

Configuración Odysseus AI con Ollama - Úsala si Docker funciona pero el enrutamiento de modelos sigue confuso.
Odysseus AI en Windows - Notas para WSL2, Docker Desktop, firewall y endpoints del host.
Odysseus AI en macOS - Compara Docker con la ruta nativa de Apple Silicon.
README oficial de Odysseus - Verifica los comandos actuales antes de ejecutarlos.

Última actualización: 22 de junio de 2026

Volver al Wiki de Odysseus AI