lucasacchi/llm-monitor

Fork 0

Files

T

Luca Sacchi Ricciardi 831b41f487 docs: aggiorna README e documentazione con feature attuali

2026-04-25 18:10:49 +02:00

5.7 KiB

Raw Blame History

Development Setup - LLM Monitor

🛠️ Setup Locale

1. Installare Dipendenze Python

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

2. Installare Dipendenze Node (per Tailwind CSS)

npm install

3. Compilare Tailwind CSS

Modalità Development (watch mode)

npm run tailwind:dev

Questo comando:

Compila app/web/static/css/input.css in app/web/static/css/output.css
Rimane in watch mode per compilare automaticamente al salvataggio
Legge la configurazione da tailwind.config.js

Modalità Production (minified)

npm run tailwind:build

Questo comando:

Compila e minifica il CSS
Ottimizzato per produzione
Usato durante il build Docker

4. Avviare l'Applicazione

In una finestra di terminale (con npm run tailwind:dev in watch):

source venv/bin/activate
python3 -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

O usar il comando Makefile:

make dev

Accedi a: http://localhost:8000

📱 Workflow di Sviluppo

Sviluppare il Frontend

Terminal 1 - Tailwind Watcher:
```
npm run tailwind:dev
```

Terminal 2 - FastAPI Dev Server:

source venv/bin/activate
uvicorn main:app --reload

Modificare i file:
- HTML: app/web/templates/index.html, servers.html, models_running.html
- CSS input: app/web/static/css/input.css (raramente, usa classi Tailwind)
- JavaScript: app/web/static/js/app.js, servers.js, models-running.js, data-sync.worker.js
⚠️ Classi Tailwind dinamiche: Le classi generate dinamicamente via innerHTML (es. in accordion o card) non vengono rilevate dal JIT scanner. Usa stili inline (style="...") o classi hardcoded nei template HTML per queste situazioni.
Compilato automaticamente:
- Tailwind genera app/web/static/css/output.css automaticamente
- FastAPI recarica il server automaticamente
- Browser reload automatico (se abilitato)

🐳 Build Docker

Il Dockerfile multi-stage:

Stage 1 - CSS Builder (Node):
- Installa dipendenze npm
- Compila Tailwind CSS
- Genera app/web/static/css/output.css
Stage 2 - Python Builder:
- Installa dipendenze Python
- Crea virtualenv
Stage 3 - Runtime:
- Copia CSS compilato dal Stage 1
- Copia Python packages dal Stage 2
- Immagine finale ottimizzata (~300MB)

Build locale:

docker build -t llm-monitor:latest .

Eseguire il container:

docker run -p 8000:8000 --env-file .env llm-monitor:latest

⚙️ Configurazione Tailwind

File: tailwind.config.js

module.exports = {
  content: [
    "./app/web/templates/**/*.html",
    "./app/web/static/**/*.js",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Content: Specifica quali file Tailwind deve scansionare per le classi utilizzate

🎯 CSS Architecture

Input CSS

File: app/web/static/css/input.css

@tailwind base;
@tailwind components;
@tailwind utilities;

Output CSS

File: app/web/static/css/output.css (generato)

Contiene solo le classi Tailwind utilizzate
Minificato in produzione (~30KB)
Ottimizzato per performance

Usage in HTML

File: app/web/templates/index.html

<!-- Usa il CSS compilato (produzione) -->
<link rel="stylesheet" href="/static/css/output.css">

<!-- Fallback CDN per sviluppo (se output.css non esiste) -->
<script src="https://cdn.tailwindcss.com"></script>

📝 Tips di Sviluppo

Hot Reload CSS

npm run tailwind:dev
# Guarda i file e compila automaticamente

Debug CSS Compilation

npm run tailwind:build
# Se il CSS non appare, verifica:
# 1. Le classi sono usate nei file HTML/JS?
# 2. C'è un errore nella sintassi CSS?
# 3. I percorsi in tailwind.config.js sono corretti?

Aggiungere Nuove Classi Tailwind

Modifica i file HTML/JS con classi Tailwind
Tailwind watcher le detetta automaticamente
output.css viene rigenerato

<!-- Nuova classe aggiunta -->
<div class="bg-gradient-to-r from-purple-500 to-pink-500">
  <!-- Viene aggiunta automaticamente al CSS compilato -->
</div>

🚀 Production Checklist

Eseguire npm run tailwind:build per minificare
Verificare che output.css sia generato
Eseguire i test Python: make test
Eseguire i test E2E: npm run test:e2e

🧪 Testing

Unit Test (pytest)

# Tutti i test
pytest tests/ -v

# Con coverage
pytest tests/ --cov=app

E2E Test (Playwright)

I test E2E verificano il comportamento del browser (cache-first, navigazione, PWA).

# Installare i browser Playwright (prima volta)
npx playwright install --with-deps

# Eseguire i test E2E (richiede Ollama attivo)
OLLAMA_HOST=http://<ollama-host>:11434 npm run test:e2e

# Con report HTML
npm run test:e2e -- --reporter=html

I test si trovano in tests/e2e/. Il report viene generato in playwright-report/ (gitignored).

Makefile

make test          # pytest
make lint          # flake8
make format        # black
make dev           # uvicorn --reload
make deploy-no-cache  # Docker rebuild forzato

Controllare che il container Docker usi il CSS compilato
Test performance con Lighthouse
Verifica bundle size output.css

🔗 Risorse

Ultimo aggiornamento: Aprile 2024

5.7 KiB Raw Blame History