12 min di lettura 22 giugno 2026

Setup Docker di Odysseus AI: 7 controlli prima di esporre il workspace

Guida pratica per clonare Odysseus AI, creare .env, avviare Compose, trovare la prima password admin, collegare Ollama sull'host, conservare i dati e mantenere privati i servizi interni.

Odysseus AI Wiki

Note editoriali non ufficiali basate sul README pubblico di Odysseus, Docker Compose, routing dei modelli locali e problemi frequenti della community.

Flusso con repository, file ambiente, Docker Compose e browser locale per configurare Odysseus AI con Docker — Il setup Docker è più affidabile quando repository, ambiente, servizi Compose e browser locale vengono verificati separatamente.

Risposta breve: Per la maggior parte dei nuovi utenti, Docker Compose è il percorso più pulito: clona il repository ufficiale, copia .env.example in .env, esegui docker compose up -d --build, apri localhost:7000 e controlla docker compose logs odysseus per la prima password admin. Non esporre lo stack prima di definire autenticazione, HTTPS, porte ed endpoint dei modelli.

La strada Docker è utile perché crea uno stack locale ripetibile senza distribuire tutte le dipendenze sul sistema host. Però Docker aggiunge confini: il localhost del container non è l'host, i volumi decidono cosa resta dopo un rebuild e i servizi ausiliari diventano rischiosi se pubblichi troppe porte.

Quando usare Docker

Mantieni l'ordine: container dell'app, endpoint del modello, poi esposizione di rete. I comandi restano invariati; si localizza la spiegazione.

Per la maggior parte dei nuovi utenti, Docker Compose è il percorso più pulito: clona il repository ufficiale, copia .env.example in .env, esegui docker compose up -d --build, apri localhost:7000 e controlla docker compose logs odysseus per la prima password admin. Non esporre lo stack prima di definire autenticazione, HTTPS, porte ed endpoint dei modelli.

Risposta breve

Avvia Docker Compose in un ordine pulito e verificabile

Parti dal repository ufficiale, non da comandi copiati. Branch, GPU, porte e nomi dei servizi possono cambiare rapidamente.

Controlla che Docker Desktop o il daemon siano attivi e che la cartella del repository non crei problemi di permessi.

1. Clonare il repository corretto

Usa il repository ufficiale e scegli main o un branch di sviluppo prima di modificare i file.

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

2. Creare il file ambiente

Copia l'esempio così Compose e l'app leggono default locali espliciti. Non condividere .env.

cp .env.example .env

3. Costruire e avviare lo stack

Il primo build può richiedere tempo perché scarica immagini e dipendenze. Attendi la fine.

docker compose up -d --build

4. Verificare stato e credenziali

Apri la UI locale solo quando i container sono sani. La prima password admin appare nei log Odysseus.

docker compose ps
docker compose logs odysseus

Capire .env, porta 7000 e cosa deve essere raggiungibile

La UI web è normalmente l'unico punto da aprire nel browser. Il quick start pubblico usa http://localhost:7000.

I servizi ausiliari Compose non devono diventare pubblici solo perché la UI funziona.

Impostazione o controllo	Cosa dimostra	Cosa evitare
.env copiato dall'esempio	L'app legge valori locali espliciti.	Eseguire con variabili ereditate sconosciute.
localhost:7000	Il browser raggiunge la UI sul porto locale previsto.	Aprire servizi ausiliari credendo siano l'app.
docker compose ps	Ogni servizio atteso è attivo o mostra l'errore.	Cambiare modelli prima che il container sia sano.
logs odysseus	Percorso di avvio e prime credenziali sono visibili.	Condividere log con password o token.

Collegare Ollama sull'host senza confondere localhost del container

Ollama è spesso un server di modelli separato. Se Odysseus è nel container e Ollama sull'host, localhost nel container non è l'host.

Testa Ollama sull'host, poi l'accesso dal container, e solo dopo salva l'endpoint in Odysseus AI.

Diagramma di un container Docker Odysseus AI che raggiunge Ollama sull'host — L'errore comune è usare localhost del container quando Ollama vive sull'host.

Endpoint comune da Docker a Ollama sull'host

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

Dove gira Odysseus	Dove gira Ollama	Endpoint iniziale
Container Docker	Macchina host	http://host.docker.internal:11434/v1
Container Docker	Stessa rete Compose	Usa nome del servizio e porta interna Compose.
Processo nativo host	Stesso host	http://127.0.0.1:11434/v1
Server remoto	Altra macchina	Usa HTTPS o rete privata, non una porta grezza esposta.

Sapere cosa sopravvive a rebuild, aggiornamenti e riavvii

Un workspace con account, documenti e impostazioni non è più usa e getta.

I comandi Compose hanno effetti diversi. Riavviare non equivale a rimuovere volumi.

Azione	Quando usarla	Rischio
docker compose restart	Lo stack è già costruito e serve solo riavviare i servizi.	Basso; lo stato normalmente resta.
docker compose pull && docker compose up -d --build	Aggiornare immagini e ricostruire dal source attuale.	Medio; leggi prima il README.
docker compose down	Fermare e rimuovere container mantenendo i volumi.	Di solito sicuro, ma verifica Compose.
docker compose down -v	Rimuovere volumi intenzionalmente per reset.	Alto; può cancellare lo stato del workspace.

Matrice dei problemi al primo avvio

Separa build, salute dei container, accesso browser, credenziali e routing dei modelli. Correggi il primo livello che fallisce.

Sintomo	Causa probabile	Prima correzione
Comando Docker non riconosciuto	Docker Desktop o daemon non è installato, avviato o disponibile.	Avvia Docker e controlla docker version.
Build riuscito ma localhost:7000 non carica	Container ancora in avvio, porta diversa o servizio non sano.	Esegui docker compose ps e logs odysseus.
Password admin iniziale non visibile	Il log è passato, esiste stato precedente o .env imposta credenziali.	Controlla logs odysseus e .env.
Ollama funziona sull'host ma non in Odysseus	Il container usa localhost invece del gateway host.	Usa host.docker.internal:11434/v1 dallo stesso layer.
Dati spariti dopo cleanup	I volumi sono stati rimossi.	Ripristina backup ed evita down -v senza reset intenzionale.

Checklist sicurezza prima di LAN, tunnel o reverse proxy

Un workspace AI self-hosted può toccare file, prompt, documenti, modelli e strumenti.

Pubblica solo la UI necessaria, mantieni privati i servizi interni, cambia credenziali e usa HTTPS da remoto.

Cambia le credenziali admin prima di accessi esterni.
Controlla ogni porta pubblicata in Compose.
Non esporre ChromaDB, modelli e servizi ausiliari.
Usa HTTPS e un proxy affidabile.
Non pubblicare .env, log o screenshot con segreti.
Esegui backup dei volumi prima di update o pulizie distruttive.

Default sicuro

Tieni Odysseus AI su localhost finché auth, porte, HTTPS, firewall ed endpoint modello non sono chiari.

FAQ

Per una prima installazione pulita, spesso sì. I percorsi nativi possono essere migliori per GPU o sviluppo.

http://localhost:7000 salvo porta diversa in .env.

In docker compose logs odysseus, salvo stato persistente o .env diversi.

Entrambi funzionano. Docker verso host usa spesso host.docker.internal:11434/v1.

No, prima verifica auth, HTTPS, firewall e servizi ausiliari.

Backup dei volumi, README aggiornato e rebuild intenzionale.

Riferimenti

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.

Guide correlate

Setup Ollama di Odysseus AI - Leggi se Docker funziona ma il routing dei modelli resta poco chiaro.
Setup Windows di Odysseus AI - Note per WSL2, Docker Desktop, firewall ed endpoint host.
Setup macOS di Odysseus AI - Confronta Docker con il percorso nativo Apple Silicon.
README ufficiale Odysseus - Verifica i comandi attuali prima di eseguirli.

Ultimo aggiornamento: 22 giugno 2026

Torna al Wiki di Odysseus AI