From c3fa4d6127a1ba80a707c990ddd69e74a186d509 Mon Sep 17 00:00:00 2001
From: Luca Sacchi Ricciardi <luca@lucasacchi.net>
Date: Tue, 7 Apr 2026 22:17:52 +0200
Subject: [PATCH] docs: add comprehensive Docker documentation to README

Add detailed Docker section explaining:
- All available Docker Compose files and their purposes
- Development vs production configurations
- Included services (PostgreSQL, Redis, Celery, Monitoring)
- Useful Docker commands for daily operations
- Port mappings and access URLs
- Production deployment instructions

Makes Docker setup clear for new developers and operators.
---
 README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 87 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 3516525..fa1270e 100644
--- a/README.md
+++ b/README.md
@@ -169,19 +169,103 @@ A differenza dei semplici calcolatori di costo online, mockupAWS permette di:
 
 ### Metodo 1: Docker Compose (Consigliato)
 
+Il progetto include diversi file Docker Compose per diversi scenari di deployment:
+
+#### File Docker Disponibili
+
+| File | Scopo | Servizi Inclusi |
+|------|-------|-----------------|
+| `docker-compose.yml` | **Sviluppo completo** | PostgreSQL, Redis, Backend API, Celery Worker, Celery Beat, Frontend Dev |
+| `docker-compose.scheduler.yml` | **Report scheduling** | Aggiunge servizi per job scheduling automatico |
+| `docker-compose.monitoring.yml` | **Monitoring stack** | Prometheus, Grafana, Alertmanager, Loki per osservabilità |
+| `Dockerfile.backend` | **Backend production** | Immagine ottimizzata per FastAPI |
+| `frontend/Dockerfile` | **Frontend production** | Immagine Nginx per React build |
+
+#### Avvio Sviluppo Completo
+
 ```bash
 # Clona il repository
 git clone <repository-url>
 cd mockupAWS
 
-# Avvia tutti i servizi (API + Database + Frontend)
+# Setup iniziale (prima volta)
+cp .env.example .env
+# Modifica .env con le tue configurazioni
+
+# Avvia stack completo di sviluppo
 docker-compose up --build
 
+# O in background (detached)
+docker-compose up -d --build
+
 # L'applicazione sarà disponibile su:
-# - Web UI: http://localhost:5173  (Vite dev server)
+# - Web UI: http://localhost:5173  (Vite dev server con hot reload)
 # - API: http://localhost:8000
 # - API Docs: http://localhost:8000/docs
-# - Database: localhost:5432
+# - Flower (Celery monitoring): http://localhost:5555
+# - PostgreSQL: localhost:5432
+# - Redis: localhost:6379
+```
+
+#### Servizi Docker Composizione Sviluppo
+
+```yaml
+# docker-compose.yml include:
+- postgres:       Database PostgreSQL 15
+- redis:          Cache e message broker
+- backend:        API FastAPI (porta 8000)
+- celery-worker:  Worker per job async
+- celery-beat:    Scheduler per job periodic
+- frontend:       React dev server (porta 5173)
+```
+
+#### Avvio con Monitoring (Produzione)
+
+```bash
+# Avvia stack principale + monitoring
+docker-compose -f docker-compose.yml -f docker-compose.monitoring.yml up -d
+
+# Accesso ai servizi di monitoring:
+# - Prometheus: http://localhost:9090
+# - Grafana: http://localhost:3000 (admin/admin)
+# - Alertmanager: http://localhost:9093
+```
+
+#### Comandi Docker Utili
+
+```bash
+# Visualizza logs di tutti i servizi
+docker-compose logs -f
+
+# Logs di un servizio specifico
+docker-compose logs -f backend
+
+# Restart di un servizio
+docker-compose restart backend
+
+# Stop tutti i servizi
+docker-compose down
+
+# Stop e rimuovi anche i volumi (ATTENZIONE: perde dati!)
+docker-compose down -v
+
+# Ricostruisci immagini
+docker-compose build --no-cache
+
+# Esegui comando in un container
+docker-compose exec backend uv run alembic upgrade head
+docker-compose exec postgres psql -U postgres -d mockupaws
+```
+
+#### Production Deployment con Docker
+
+```bash
+# Build immagini production
+docker build -t mockupaws-backend:latest -f Dockerfile.backend .
+cd frontend && docker build -t mockupaws-frontend:latest .
+
+# Avvia con configurazione produzione
+docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
 ```
 
 ### Metodo 2: Sviluppo Locale