ScommettiApp/backend-node/DOCKER_GUIDE.md

🐳 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:

docker --version
docker compose version

🚀 Quick Start

Development (con Hot Reload)

# 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

# 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:

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

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:

docker compose logs backend

3. Verifica la connessione ai database:

# 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:

PORT=3001
POSTGRES_PORT=5433
MONGO_PORT=27018

I database non mantengono i dati

Soluzione: Verifica che i volumi esistano:

docker volume ls | grep amici-scommesse

Per ripristinare i volumi:

docker compose down
docker compose up -d

Hot reload non funziona in development

Verifica volumi: Il file docker-compose.dev.yml deve avere:

volumes:
  - ./:/app
  - /app/node_modules

Rebuild del container:

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:

# 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:

# 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!

# 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:

# Development
docker build --target development -t backend:dev .

# Production
docker build --target production -t backend:prod .

📈 Monitoraggio

Resource Usage

# 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

# 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:

# 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
• Docker Compose Documentation
• Docker Best Practices
• PostgreSQL Docker Image
• MongoDB Docker Image

💡 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