Passa al contenuto principale

Docker

Docker è il metodo più semplice per una distribuzione in stile produzione su un singolo server.

Per un'installazione su un singolo server raggiungibile da Internet, inizia da Distribuzione remota privata. Il relativo modello Compose non pubblica porte dell'applicazione, usa per impostazione predefinita l'immagine main e aggiunge un limite esterno Cloudflare Access, controlli dell'host, backup e limiti dei container.

Disponibilità di Work​

Work è abilitato per impostazione predefinita nei file Compose del repository. L'immagine include la CLI Docker e Compose monta /var/run/docker.sock, quindi i container delle attività Work sono fratelli del container Libre WebUI. Compaiono in docker ps sull'host.

Un processo che accede a quel socket dispone di un controllo dell'host Docker equivalente a quello di root. Abilitare Work per impostazione predefinita è una scelta deliberata: Work è una funzionalità essenziale e non può funzionare senza accesso al daemon. La conseguenza è che ogni amministratore di Libre WebUI è di fatto un amministratore dell'host. Pianifica di conseguenza:

  • Mantieni lo stack su un host i cui amministratori siano già persone fidate.
  • Non esporre la porta pubblicata a una rete non attendibile.
  • Rimuovi il mount di /var/run/docker.sock quando Work non serve. La pagina Work segnalerà Runtime non disponibile.

Su Linux, il socket appartiene al gruppo docker invece che a root, quindi l'utente non root dell'app richiede l'ID di quel gruppo. Impostalo una volta:

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

Leggilo attraverso un container come mostrato. Un host macOS segnala un valore diverso da quello visto dal container, perché Docker Desktop inoltra il socket tramite una VM. Se il gruppo è errato, la pagina Work indica il problema anziché non riuscire senza spiegazioni. Consulta Work: aree di lavoro isolate.

Le anteprime di Work e il Work Computer pubblicano porte casuali solo su un'interfaccia privata dell'host. Con Docker Desktop bastano i valori predefiniti di Compose: loopback dell'host per il bind e host.docker.internal per la connessione del backend. Docker Engine nativo non riesce a raggiungere un listener sul loopback dell'host da un container fratello: imposta invece il bind sul gateway non pubblico del bridge 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

I file Compose mappano host.docker.internal tramite host-gateway. Non usare mai WORK_PREVIEW_BIND=0.0.0.0: pubblicherebbe su ogni interfaccia dell'host le porte effimere delle attività, prive di autenticazione, invece di tenerle dietro il proxy firmato di Libre WebUI.

Ollama incluso​

Esegue Libre WebUI e Ollama in un unico stack Compose:

docker compose up -d

Apri http://localhost:8080.

Per impostazione predefinita, la porta della WebUI viene associata all'interfaccia di loopback dell'host. Imposta WEBUI_BIND_ADDRESS=0.0.0.0 solo quando deve essere raggiunta da una LAN attendibile o da un proxy inverso dell'host e limita la porta con il firewall dell'host.

Ollama rimane privato nella rete Compose. Per renderlo disponibile alle applicazioni dell'host tramite loopback, aggiungi l'override esplicito per l'host:

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

Imposta OLLAMA_BIND_ADDRESS solo quando Ollama deve essere raggiunto da un'altra macchina e proteggi la porta con un firewall e un proxy dotato di autenticazione.

GPU NVIDIA​

Usa il file Compose per GPU quando Docker dispone dell'accesso al runtime NVIDIA:

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

Se i modelli continuano a essere eseguiti sulla CPU, verifica l'accesso alla GPU dal container Ollama.

Ollama esterno​

Usa questa configurazione quando Ollama è già in esecuzione sull'host o su un altro server:

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

Se necessario, sostituisci l'URL di Ollama:

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

Work con socket isolato​

I file Compose standard montano il socket Docker nel container Libre WebUI affinché Work possa eseguire i container delle attività; questo mount offre un controllo equivalente a quello di root dell'host Docker. Per mantenere Work senza assegnare il socket all'applicazione web, usa la variante con proxy del socket:

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

Un proxy del socket su una rete interna detiene /var/run/docker.sock e inoltra solo le sezioni API usate da Work (container, immagini, volumi, reti, exec, info). Gli endpoint Swarm, secret, configurazioni, build e sistema vengono negati dal proxy. Libre WebUI lo raggiunge tramite DOCKER_HOST=tcp://docker-socket-proxy:2375: nessun mount del socket, nessun DOCKER_GID, mentre il terminale interattivo e la diagnostica di sistema funzionano senza variazioni. Consulta la documentazione sulle aree di lavoro per capire che cosa copre e che cosa non copre questo limite.

Persistenza dei dati​

Libre WebUI archivia i dati del backend in /app/backend/data all'interno del container. I file Compose montano quel percorso come volume con nome.

Anche l'immagine usa quel percorso per impostazione predefinita quando viene avviata direttamente con docker run; l'area temporanea per la verifica preliminare del database rimane separata in /app/backend/temp. Monta /app/backend/data ogni volta che il container potrebbe essere ricreato.

Per la produzione, imposta secret stabili:

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

Esegui insieme il backup del volume dei dati e della chiave di cifratura.

Prima di rimuovere un container avviato direttamente e creato da un'immagine precedente, verifica che esista /app/backend/data/.encryption_key oppure annota il valore configurato di ENCRYPTION_KEY. Le immagini precedenti potevano scrivere una chiave generata automaticamente soltanto nel livello del container; eliminando quel container si elimina anche l'unica chiave in grado di decifrare il database persistente.

Se gestisci un runtime personalizzato che supporta Work, i file delle attività risiedono in volumi Docker con nome separati e non sono inclusi nel normale backup di /app/backend/data.

Accesso pubblico​

I file Compose del repository associano la WebUI al loopback e impostano direttamente CORS_ORIGIN. Un valore nel file .env o nella shell non sostituisce tale valore letterale. Modifica la voce libre-webui.environment oppure salva un override esplicito come compose.origin.yml:

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

Applica l'override insieme al file Compose del repository selezionato:

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

Quindi colloca Libre WebUI dietro HTTPS usando un proxy inverso o un bilanciatore di carico della piattaforma. Imposta WEBUI_BIND_ADDRESS sull'interfaccia esatta richiesta dal proxy; non pubblicare la porta su tutte le interfacce, a meno che non sia il firewall a richiederlo.

Il server distribuisce già in modo efficiente il frontend compilato: i bundle con hash sotto /js/ e /assets/ vengono inviati compressi con brotli o gzip e con una durata di cache immutable di un anno, mentre index.html e il service worker sono contrassegnati no-cache così che una nuova release venga rilevata al caricamento successivo. Un proxy non deve ricomprimere né memorizzare in cache questi percorsi; lascia passare Accept-Encoding.

Comandi utili​

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

Documenti correlati​