Initial commit

2026-03-26 22:46:03 +01:00
commit 18e0e04700
80 changed files with 13114 additions and 0 deletions
@@ -0,0 +1,433 @@
+# 🐳 Docker Guide - Amici Scommesse Backend
+
+Guida completa per eseguire il backend con Docker e Docker Compose.
+
+## 📋 Prerequisiti
+
+- Docker >= 20.10
+- Docker Compose >= 2.0
+
+Verifica installazione:
+```bash
+docker --version
+docker compose version
+```
+
+## 🚀 Quick Start
+
+### Development (con Hot Reload)
+
+```bash
+# Avvia tutti i servizi in development
+docker compose -f docker-compose.dev.yml up -d
+
+# Visualizza logs
+docker compose -f docker-compose.dev.yml logs -f backend
+
+# Ferma tutti i servizi
+docker compose -f docker-compose.dev.yml down
+```
+
+### Production
+
+```bash
+# Avvia tutti i servizi in production
+docker compose up -d
+
+# Visualizza logs
+docker compose logs -f backend
+
+# Ferma tutti i servizi
+docker compose down
+```
+
+## 📦 Servizi Inclusi
+
+### Docker Compose Production (`docker-compose.yml`)
+
+| Servizio | Porta | Descrizione |
+|----------|-------|-------------|
+| `backend` | 3000 | Backend Node.js (production build) |
+| `postgres` | 5432 | PostgreSQL 16 |
+| `mongodb` | 27017 | MongoDB 7 |
+
+### Docker Compose Development (`docker-compose.dev.yml`)
+
+| Servizio | Porta | Descrizione |
+|----------|-------|-------------|
+| `backend` | 3000 | Backend Node.js (development + hot reload) |
+| `postgres` | 5432 | PostgreSQL 16 |
+| `mongodb` | 27017 | MongoDB 7 |
+| `mongo-express` | 8081 | Web UI per MongoDB (opzionale) |
+| `pgadmin` | 5050 | Web UI per PostgreSQL (opzionale) |
+
+## 🔧 Configurazione
+
+### File .env
+
+Crea un file `.env` nella root del progetto:
+
+```bash
+# Copia il template
+cp .env.example .env
+
+# Modifica le variabili se necessario
+nano .env
+```
+
+Le variabili d'ambiente sono automaticamente caricate da Docker Compose.
+
+### Variabili Importanti
+
+```env
+# Application
+NODE_ENV=development
+PORT=3000
+
+# PostgreSQL
+POSTGRES_DB=amici_scommesse
+POSTGRES_USER=admin
+POSTGRES_PASSWORD=admin
+
+# MongoDB
+MONGO_DB=amici-scommesse
+MONGO_USER=root
+MONGO_PASSWORD=root@servovio
+```
+
+## 📝 Comandi Docker Compose
+
+### Gestione Servizi
+
+```bash
+# Avvia tutti i servizi (production)
+docker compose up -d
+
+# Avvia tutti i servizi (development)
+docker compose -f docker-compose.dev.yml up -d
+
+# Avvia solo alcuni servizi
+docker compose up -d postgres mongodb
+
+# Ferma tutti i servizi
+docker compose down
+
+# Ferma e rimuovi volumi (ATTENZIONE: cancella i dati!)
+docker compose down -v
+
+# Restart di un servizio specifico
+docker compose restart backend
+```
+
+### Build e Rebuild
+
+```bash
+# Build dell'immagine backend
+docker compose build backend
+
+# Rebuild forzato (ignora cache)
+docker compose build --no-cache backend
+
+# Build e avvia
+docker compose up -d --build
+```
+
+### Logs e Debug
+
+```bash
+# Visualizza logs di tutti i servizi
+docker compose logs
+
+# Visualizza logs di un servizio specifico
+docker compose logs backend
+
+# Follow logs in real-time
+docker compose logs -f backend
+
+# Ultimi 100 log lines
+docker compose logs --tail=100 backend
+
+# Logs da timestamp specifico
+docker compose logs --since 2024-01-01T00:00:00
+```
+
+### Shell nei Container
+
+```bash
+# Shell nel container backend
+docker compose exec backend sh
+
+# Shell nel container postgres
+docker compose exec postgres psql -U admin -d amici_scommesse
+
+# Shell nel container mongodb
+docker compose exec mongodb mongosh -u root -p root@servovio --authenticationDatabase admin
+```
+
+### Health Check
+
+```bash
+# Verifica health di tutti i servizi
+docker compose ps
+
+# Health check specifico
+curl http://localhost:3000/health
+```
+
+## 🔍 Troubleshooting
+
+### Il backend non si avvia
+
+**1. Verifica che i database siano healthy:**
+```bash
+docker compose ps
+```
+
+Dovresti vedere:
+```
+NAME                    STATUS                    HEALTH
+amici-scommesse-backend   Up 30 seconds             healthy
+amici-scommesse-postgres  Up 45 seconds (healthy)   healthy
+amici-scommesse-mongodb   Up 45 seconds (healthy)   healthy
+```
+
+**2. Controlla i logs:**
+```bash
+docker compose logs backend
+```
+
+**3. Verifica la connessione ai database:**
+```bash
+# Test PostgreSQL
+docker compose exec postgres pg_isready -U admin
+
+# Test MongoDB
+docker compose exec mongodb mongosh --eval "db.adminCommand('ping')"
+```
+
+### Errore "port already in use"
+
+**Soluzione**: Cambia la porta nel file `.env`:
+```env
+PORT=3001
+POSTGRES_PORT=5433
+MONGO_PORT=27018
+```
+
+### I database non mantengono i dati
+
+**Soluzione**: Verifica che i volumi esistano:
+```bash
+docker volume ls | grep amici-scommesse
+```
+
+Per ripristinare i volumi:
+```bash
+docker compose down
+docker compose up -d
+```
+
+### Hot reload non funziona in development
+
+**Verifica volumi**: Il file `docker-compose.dev.yml` deve avere:
+```yaml
+volumes:
+  - ./:/app
+  - /app/node_modules
+```
+
+**Rebuild del container**:
+```bash
+docker compose -f docker-compose.dev.yml up -d --build
+```
+
+### Errore di connessione tra servizi
+
+**Soluzione**: Usa i nomi dei servizi come hostname:
+- Backend → Postgres: `postgres:5432`
+- Backend → MongoDB: `mongodb:27017`
+
+Non usare `localhost` quando sei dentro Docker!
+
+## 🌐 Accesso ai Servizi
+
+### Backend API
+
+- **API v1**: http://localhost:3000/api/v1
+- **Legacy API**: http://localhost:3000/api/legacy
+- **Health Check**: http://localhost:3000/health
+
+### Database Web UIs (Solo Development)
+
+**Mongo Express** (MongoDB UI):
+- URL: http://localhost:8081
+- Username: `admin`
+- Password: `admin`
+
+**pgAdmin** (PostgreSQL UI):
+- URL: http://localhost:5050
+- Email: `admin@admin.com`
+- Password: `admin`
+
+**Connessione PostgreSQL in pgAdmin**:
+1. Add New Server
+2. General → Name: `Amici Scommesse`
+3. Connection:
+   - Host: `postgres` (il nome del servizio Docker)
+   - Port: `5432`
+   - Username: `admin`
+   - Password: `admin`
+   - Database: `amici_scommesse`
+
+## 📊 Gestione Dati
+
+### Backup Database
+
+**PostgreSQL**:
+```bash
+# Backup
+docker compose exec postgres pg_dump -U admin amici_scommesse > backup.sql
+
+# Restore
+docker compose exec -T postgres psql -U admin amici_scommesse < backup.sql
+```
+
+**MongoDB**:
+```bash
+# Backup
+docker compose exec mongodb mongodump --username root --password root@servovio --authenticationDatabase admin --db amici-scommesse --out /tmp/backup
+
+# Export dal container
+docker compose cp mongodb:/tmp/backup ./mongodb-backup
+
+# Restore
+docker compose cp ./mongodb-backup mongodb:/tmp/backup
+docker compose exec mongodb mongorestore --username root --password root@servovio --authenticationDatabase admin --db amici-scommesse /tmp/backup/amici-scommesse
+```
+
+### Reset Completo
+
+**ATTENZIONE: Cancella tutti i dati!**
+
+```bash
+# Ferma tutto e rimuovi volumi
+docker compose down -v
+
+# Rimuovi immagini
+docker compose rm -f
+
+# Rebuild e riavvia
+docker compose up -d --build
+```
+
+## 🎯 Best Practices
+
+### Development
+
+1. **Usa docker-compose.dev.yml** per development
+2. **Mount dei volumi** per hot reload
+3. **Abilita SQL logging** per debug
+4. **Usa le Web UI** per ispezionare i database
+
+### Production
+
+1. **Usa docker-compose.yml** per production
+2. **Non montare volumi sorgente**
+3. **Disabilita SQL logging**
+4. **Usa secrets** per password sensibili
+5. **Configura backup automatici**
+
+### Sicurezza
+
+1. **Non committare .env** nel repository
+2. **Cambia password** di default per production
+3. **Usa user non-root** (già configurato nel Dockerfile)
+4. **Limita risorse** del container se necessario
+
+## 🔨 Multi-Stage Build
+
+Il Dockerfile usa multi-stage build per ottimizzare le immagini:
+
+| Stage | Target | Uso |
+|-------|--------|-----|
+| `base` | - | Base comune |
+| `dependencies` | - | Tutte le dipendenze |
+| `development` | Development | Con devDependencies + hot reload |
+| `production-dependencies` | - | Solo prod dependencies |
+| `production` | Production | Ottimizzato, user non-root |
+
+**Build target specifico**:
+```bash
+# Development
+docker build --target development -t backend:dev .
+
+# Production
+docker build --target production -t backend:prod .
+```
+
+## 📈 Monitoraggio
+
+### Resource Usage
+
+```bash
+# Uso risorse di tutti i container
+docker stats
+
+# Uso risorse di un container specifico
+docker stats amici-scommesse-backend
+```
+
+### Container Logs in Produzione
+
+Per produzione, considera l'uso di:
+- **Docker logging drivers** (json-file, syslog, fluentd)
+- **Log aggregators** (ELK Stack, Loki)
+- **APM tools** (Datadog, New Relic)
+
+## 🚀 Deploy in Production
+
+### Docker Swarm
+
+```bash
+# Inizializza Swarm
+docker swarm init
+
+# Deploy lo stack
+docker stack deploy -c docker-compose.yml amici-scommesse
+
+# Lista servizi
+docker service ls
+
+# Scala il backend
+docker service scale amici-scommesse_backend=3
+```
+
+### Kubernetes
+
+Per Kubernetes, converti il docker-compose:
+```bash
+# Installa kompose
+curl -L https://github.com/kubernetes/kompose/releases/download/v1.31.2/kompose-linux-amd64 -o kompose
+chmod +x kompose
+sudo mv kompose /usr/local/bin
+
+# Converti
+kompose convert -f docker-compose.yml
+```
+
+## 🔗 Link Utili
+
+- [Docker Documentation](https://docs.docker.com/)
+- [Docker Compose Documentation](https://docs.docker.com/compose/)
+- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)
+- [PostgreSQL Docker Image](https://hub.docker.com/_/postgres)
+- [MongoDB Docker Image](https://hub.docker.com/_/mongo)
+
+## 💡 Tips
+
+1. **Cache delle dipendenze**: `COPY package*.json` prima di `COPY .` per ottimizzare il build
+2. **Multi-stage**: Usa stage diversi per dev e prod
+3. **Health checks**: Sempre configurare healthcheck per monitoraggio
+4. **Named volumes**: Usa volumi nominati per persistenza dati
+5. **Networks**: Isola i servizi in network dedicati
+6. **Secrets**: Usa Docker secrets per dati sensibili in produzione