llm-monitor/README.md

LLM Monitor - Dashboard Ollama

Una dashboard web moderna e intuitiva per monitorare e gestire i modelli LLM caricati in Ollama. Visualizza i modelli disponibili, i dettagli dei caricamenti e accedi ai dati via API Ollama direttamente da una web app elegante.

🎯 Caratteristiche

• ✨ Dashboard intuitiva - Visualizza in tempo reale i modelli disponibili e in esecuzione su Ollama
• 📊 Monitoraggio modelli - Dettagli completi di ogni modello (nome, dimensione, memoria, stato)
• 🧩 Dettagli accordion on click - Clic su una card per esplorare i dati ollama show in pannelli collassabili (dettagli, parametri, template, modelfile, licenza)
• 🖥️ Multi-server - Gestione di più istanze Ollama con switch istantaneo (pagina /servers)
• 🏃 Modelli in esecuzione - Pagina dedicata /models-running con VRAM, tempo rimanente e backend GPU/CPU
• 📱 PWA - Installabile come app desktop/mobile con Service Worker e cache offline
• 🔌 API REST documentata - Documentazione interattiva con Swagger/OpenAPI
• 🎨 UI moderna - Interfaccia dark-mode realizzata con TailwindCSS
• 🐳 Docker ready - Container sempre acceso (restart: unless-stopped)
• ⚡ Performance - FastAPI + uVicorn, aggiornamenti ogni 30s via Web Worker senza bloccare l'UI
• 🔐 Configurazione flessibile - File .env per personalizzazione

📋 Requisiti

• Python 3.10+
• Ollama installato e in esecuzione
• Docker (opzionale, per containerizzazione)
• Docker Compose (opzionale)

🚀 Installazione Rapida

1. Clonare il repository

git clone https://github.com/LucaSacchiNet/llm-monitor.git
cd llm-monitor

2. Configurare l'ambiente

Copia il file di esempio:

cp env.example .env

Modifica .env con i tuoi parametri (vedi Configurazione):

nano .env

3. Installare le dipendenze

Opzione A: Ambiente virtuale (Sviluppo)

python3 -m venv venv
source venv/bin/activate  # Su Windows: venv\Scripts\activate
pip install -r requirements.txt

Opzione B: Docker (Produzione)

docker compose up -d

4. Avviare l'applicazione

Modalità sviluppo

python3 -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

Modalità produzione

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

⚙️ Configurazione

Crea un file .env nella root del progetto (copia da env.example):

# Ollama Configuration
OLLAMA_HOST=http://localhost:11434
OLLAMA_TIMEOUT=30

# API Configuration
API_HOST=0.0.0.0
API_PORT=8000
API_WORKERS=4
ENABLE_MODEL_RW_API=false

# CORS Configuration
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

# Logging
LOG_LEVEL=INFO

# Environment
ENVIRONMENT=development

Variabili disponibili

Variabile	Default	Descrizione
OLLAMA_HOST	http://localhost:11434	URL della API Ollama
OLLAMA_TIMEOUT	30	Timeout (secondi) per le richieste
API_HOST	0.0.0.0	Host su cui esporre l'API
API_PORT	8000	Porta dell'API
API_WORKERS	4	Worker processes
ENABLE_MODEL_RW_API	false	Abilita endpoint POST/DELETE sui modelli
CORS_ORIGINS	http://localhost:3000	Origini CORS consentite
LOG_LEVEL	INFO	Livello di logging
ENVIRONMENT	development	Ambiente (development/production)

📚 API Swagger

La documentazione interattiva dell'API è disponibile automaticamente:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Endpoint principali

Recuperare modelli caricati

GET /api/v1/models

Risposta:

{
  "models": [
    {
      "name": "llama2",
      "digest": "abc123...",
      "size": 3825922048,
      "modified_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Dettagli di un modello specifico

GET /api/v1/models/{model_name}

Dettagli estesi da Ollama show

GET /api/v1/models/{model_name}/show

Health check API Ollama

GET /api/v1/health

Endpoint R/W modelli (opzionali)

Per impostazione predefinita gli endpoint di scrittura sono disabilitati e non disponibili.

POST /api/v1/models/{model_name}/pull
DELETE /api/v1/models/{model_name}

Per abilitarli, imposta nel file .env:

ENABLE_MODEL_RW_API=true

Risposta:

{
  "status": "healthy",
  "ollama_version": "0.1.0",
  "uptime_seconds": 3600
}

Test API con cURL

# Ottenere i modelli
curl http://localhost:8000/api/v1/models

# Ottenere info su un modello
curl http://localhost:8000/api/v1/models/llama2

# Ottenere dettagli estesi show
curl http://localhost:8000/api/v1/models/llama2/show

# Health check
curl http://localhost:8000/api/v1/health

Comportamento dashboard

• Al refresh della lista modelli, per ogni modello viene recuperato anche il dettaglio show.
• I dati vengono salvati in localStorage nella chiave llm_monitor_models (campo showByModel).
• Cliccando su una card modello, la dashboard mostra i dettagli show senza ricaricare la pagina.

🐳 Docker

Build dell'immagine

docker build -t llm-monitor:latest .

Eseguire il container

docker run -d \
  --name llm-monitor \
  -p 8000:8000 \
  --env-file .env \
  --network host \
  llm-monitor:latest

⚠️ Nota: --network host consente al container di accedere a Ollama su localhost

Docker Compose

Usa il file docker-compose.yml fornito:

# Avviare i servizi
docker compose up -d

# Rebuild completo senza cache (consigliato dopo modifiche UI/Tailwind)
docker compose build --no-cache

# Verificare che il CSS compilato non sia vuoto
docker exec llm-monitor-app wc -l /app/app/web/static/css/output.css

# Visualizzare i log
docker compose logs -f llm-monitor

# Fermare i servizi
docker compose down

# Riavviare
docker compose restart llm-monitor

Deploy consigliato (Tailwind-safe)

Se l'interfaccia appare senza stili o una modale non si posiziona correttamente, usa il deploy con rebuild no-cache e verifica CSS:

cd /opt/llm-monitor
docker compose down
docker compose build --no-cache
docker compose up -d
sleep 5
docker exec llm-monitor-app wc -l /app/app/web/static/css/output.css

In alternativa dal repository:

make deploy-no-cache

Tailwind Build Process

• Lo stage css-builder del Dockerfile installa dipendenze Node con npm ci.
• Prima della build Tailwind vengono copiati template HTML e JS usati dal content scan.
• Dopo npm run tailwind:build una verifica bloccante controlla che output.css esista e abbia almeno 100 linee.
• Lo stage runtime copia output.css compilato da css-builder con COPY --from=css-builder.

Troubleshooting UI

Se la modale non appare o i componenti sembrano "unstyled":

1. Esegui docker compose build --no-cache.
2. Riavvia con docker compose up -d.
3. Verifica CSS compilato: docker exec llm-monitor-app wc -l /app/app/web/static/css/output.css.
4. Se il numero linee e < 100, la build Tailwind non e riuscita correttamente.

Container sempre acceso

Il container llm-monitor rimarrà in esecuzione fino al suo arresto manuale:

# Fermare
docker compose stop llm-monitor
# oppure
docker stop llm-monitor

# Riavviare
docker compose start llm-monitor
# oppure
docker start llm-monitor

📁 Struttura del Progetto

llm-monitor/
├── main.py                 # Entry point dell'applicazione
├── requirements.txt        # Dipendenze Python
├── requirements-dev.txt    # Dipendenze sviluppo (pytest, black, flake8…)
├── env.example             # Esempio di configurazione
├── Dockerfile              # Build multi-stage (Node CSS + Python runtime)
├── docker-compose.yml      # Composizione servizi
├── package.json            # Script Node (Tailwind, Playwright)
├── tailwind.config.js      # Configurazione TailwindCSS
├── playwright.config.js    # Configurazione test E2E
├── Makefile                # Comandi rapidi (dev, test, deploy…)
├── README.md               # Questo file
├── CONTRIBUTING.md         # Guida ai contributi
│
├── app/
│   ├── config.py           # Configurazione via variabili d'ambiente
│   │
│   ├── api/
│   │   ├── models.py       # Endpoint modelli (/api/v1/models)
│   │   └── health.py       # Endpoint health (/api/v1/health)
│   │
│   ├── services/
│   │   └── ollama.py       # Client HTTP verso Ollama
│   │
│   └── web/
│       ├── static/
│       │   ├── css/
│       │   │   ├── input.css    # Sorgente Tailwind
│       │   │   └── output.css   # CSS compilato (generato)
│       │   └── js/
│       │       ├── app.js              # App principale (dashboard modelli)
│       │       ├── servers.js          # Pagina gestione server
│       │       ├── models-running.js   # Pagina modelli in esecuzione
│       │       ├── data-sync.worker.js # Web Worker sincronizzazione dati
│       │       ├── server-config.js    # Utilità multi-server e localStorage
│       │       ├── pwa-register.js     # Registrazione Service Worker
│       │       └── service-worker.js   # PWA Service Worker (cache-first)
│       └── templates/
│           ├── index.html             # Dashboard modelli disponibili
│           ├── servers.html           # Gestione istanze Ollama
│           └── models_running.html    # Modelli attualmente in esecuzione
│
├── docs/
│   ├── PRD.md              # Product Requirements Document
│   ├── DEVELOPMENT.md      # Guida al setup e sviluppo locale
│   └── WEB_WORKERS.md      # Architettura Web Worker e PWA
│
├── scripts/
│   ├── deploy-no-cache.sh       # Deploy Docker con rebuild forzato
│   └── verify-tailwind-css.sh   # Verifica CSS compilato in container
│
└── tests/
    ├── test_api.py         # Unit test endpoint FastAPI
    ├── test_ollama.py      # Unit test client Ollama
    └── e2e/
        └── cache-navigation.spec.js  # Test E2E Playwright (cache/PWA)

🛠️ Sviluppo

Setup locale

# Clonare il repo
git clone https://github.com/LucaSacchiNet/llm-monitor.git
cd llm-monitor

# Ambiente virtuale
python3 -m venv venv
source venv/bin/activate

# Installare dipendenze + dev
pip install -r requirements.txt
pip install -r requirements-dev.txt  # black, pytest, flake8, etc.

Comandi utili

# Formattare codice
black app/ tests/ main.py

# Linting
flake8 app/ tests/ main.py

# Test
pytest tests/ -v

# Test con coverage
pytest tests/ --cov=app

# Browser E2E test (cache-first navigation)
OLLAMA_HOST=http://192.168.254.115:11434 npm run test:e2e

# Hot reload durante sviluppo
uvicorn main:app --reload

Compilare TailwindCSS

# Installare dipendenze Node (opzionale)
npm install

# Generare CSS in modalità développement
npm run tailwind:dev

# Build per produzione
npm run tailwind:build

🐛 Troubleshooting

Errore: "Cannot connect to Ollama"

• Verificare che Ollama sia in esecuzione: curl http://localhost:11434/api/tags
• Controllare che l'indirizzo in .env sia corretto (OLLAMA_HOST)
• Se usi Docker, assicurati che il container abbia accesso a Ollama (vedi Docker)

Errore: "Port 8000 already in use"

# Cambiare la porta in .env
API_PORT=8001

# Oppure liberare la porta
lsof -ti :8000 | xargs kill -9

Dashboard lenta

• Verificare lo stato di Ollama
• Aumentare OLLAMA_TIMEOUT in .env
• Controllare i log: docker compose logs -f llm-monitor

📄 Dipendenze Principali

• FastAPI - Framework web moderno
• uVicorn - Server ASGI ad alte prestazioni
• Pydantic - Validazione dati
• Requests - Client HTTP
• Jinja2 - Template HTML
• TailwindCSS - Utility-first CSS

📜 Licenza

Questo progetto e distribuito con licenza proprietaria (tutti i diritti riservati).

Autore e detentore esclusivo di tutti i diritti: Luca Sacchi Ricciardi.

• Uso consentito gratuitamente
• Software fornito "AS IS"
• Nessuna garanzia
• Nessun supporto o manutenzione obbligatori
• Foro competente esclusivo: Milano, Italia

Dettagli completi:

• LICENSE (notice principale)
• LICENSE.en.txt (testo completo in inglese)
• LICENSE.it.txt (testo completo in italiano)

🤝 Contribuire

Le pull request sono benvenute! Per cambiamenti importanti, apri prima un issue per discutere i cambiamenti proposti.

Processo di contribuzione

1. Fork il repository
2. Crea un branch (git checkout -b feature/amazing-feature)
3. Commit i cambiamenti (git commit -m 'Add amazing feature')
4. Push al branch (git push origin feature/amazing-feature)
5. Apri una Pull Request

📞 Supporto

Per domande o segnalazioni di bug, apri un Issue nel repository oppure contatta l'autore:

• luca.sacchi@gmail.com
• luca@lucasacchi.net

---

Autore: Luca Sacchi Ricciardi (LucaSacchi.Net, luca.sacchi@gmail.com, luca@lucasacchi.net)

Versione: 1.1.0
Ultima modifica: Aprile 2026
Status: 🟢 Active