434 lines
9.3 KiB
Markdown
434 lines
9.3 KiB
Markdown
# 🐳 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
|