Passa al contenuto principale

Migrazione a Docker Compose Profiles

Questa guida documenta la migrazione dal vecchio sistema con file multipli al nuovo sistema unificato con Docker Compose Profiles.

🎯 Cosa è Cambiato​

Prima (Sistema Vecchio)​

docker-compose.yml          # Produzione
docker-compose.dev.yml      # Development  
docker-compose.local.yml    # Local (deprecato)

Problemi:

  • ❌ Duplicazione codice
  • ❌ 3+ file da manutenere
  • ❌ Comandi diversi per ogni ambiente
  • ❌ Rischio disallineamento configurazioni

Dopo (Sistema Nuovo)​

docker-compose.yml          # Unico file con 3 profiles
├── profile: dev            # Development
├── profile: staging        # Staging
└── profile: prod           # Production

Vantaggi:

  • ✅ Zero duplicazione
  • ✅ 1 solo file da manutenere
  • ✅ Comandi uniformi
  • ✅ Configurazioni sincronizzate
  • ✅ Script helper inclusi

📝 Tabella di Conversione Comandi​

Development​

Vecchio ComandoNuovo Comando
docker compose -f docker-compose.dev.yml up -ddocker compose --profile dev up -d
docker compose -f docker-compose.dev.yml downdocker compose --profile dev down
docker compose -f docker-compose.dev.yml logs -fdocker compose --profile dev logs -f
docker compose -f docker-compose.dev.yml psdocker compose --profile dev ps
docker compose -f docker-compose.dev.yml builddocker compose --profile dev build

Oppure usa script helper:

./deploy.sh up dev      # Linux/Mac
.\deploy.ps1 up dev     # Windows

Staging/Production​

Vecchio ComandoNuovo Comando (Staging)Nuovo Comando (Prod)
docker compose up -ddocker compose --profile staging up -ddocker compose --profile prod up -d
docker compose downdocker compose --profile staging downdocker compose --profile prod down
docker compose logs -fdocker compose --profile staging logs -fdocker compose --profile prod logs -f
docker compose psdocker compose --profile staging psdocker compose --profile prod ps
docker compose builddocker compose --profile staging builddocker compose --profile prod build

Oppure usa script helper:

./deploy.sh up staging    # Staging
./deploy.sh up prod       # Production

🔄 Procedura di Migrazione​

Step 1: Aggiorna Repository​

# Assicurati di essere sull'ultimo commit
git pull origin [branch]

# Verifica presenza nuovi file
ls -la env.*.example
ls -la deploy.*

Dovresti vedere:

  • ✅ docker-compose.yml (aggiornato)
  • ✅ env.dev.example
  • ✅ env.staging.example
  • ✅ env.prod.example
  • ✅ deploy.sh
  • ✅ deploy.ps1

Step 2: Backup (Opzionale)​

I vecchi file sono già salvati automaticamente come .backup:

  • docker-compose.yml.backup
  • docker-compose.dev.yml.backup
  • docker-compose.local.yml.backup

Step 3: Configura Ambiente​

# Sviluppo
cp env.dev.example .env

# Staging (su server)
cp env.staging.example .env

# Produzione (su server)
cp env.prod.example .env

Modifica .env con i tuoi valori reali.

Step 4: Stop Vecchi Container​

# Se hai container in esecuzione con vecchio sistema
docker compose -f docker-compose.dev.yml down   # Dev
docker compose down                              # Prod/Staging

Step 5: Avvia con Nuovo Sistema​

# Development
./deploy.sh up dev

# Staging
./deploy.sh up staging

# Production
./deploy.sh up prod

Step 6: Verifica​

# Controlla stato
./deploy.sh ps [env]

# Controlla logs
./deploy.sh logs [env]

# Test health endpoint
curl http://localhost:3000/health          # Dev
curl https://langgraphjs-stage.tidiko.ai/health   # Staging
curl https://langgraphjs-prod.tidiko.ai/health    # Production

📊 Mapping Servizi​

Nomi Container Aggiornati​

I container ora hanno suffissi per ambiente:

Vecchio NomeNuovo Nome (Dev)Nuovo Nome (Staging)Nuovo Nome (Prod)
langgraphjs-appapp-devapp-stagingapp-prod
queue-workerqueue-worker-devqueue-worker-stagingqueue-worker-prod
postgrespostgres-devpostgres-stagingpostgres-prod
hatchet-engineN/A (usa Lite)hatchet-engine-staginghatchet-engine-prod

🌐 Domini di Accesso​

ServizioDevStagingProd
Apphttp://localhost:3000https://staging-langgraphjs.tidiko.aihttps://langgraphjs.tidiko.ai
Hatchet Dashboardhttp://localhost:8888https://hatchet.stage.tidiko.aihttps://hatchet.prod.tidiko.ai
RabbitMQhttp://localhost:15672http://localhost:15673http://localhost:15672

Porte Aggiornate​

ServizioDevStagingProd
App300030013000
Worker330033013300
PostgreSQL543254365433
Hatchet DB543454375435
Hatchet Dashboard8888Via TraefikVia Traefik

🐛 Troubleshooting Migrazione​

Problema: "service not found"​

Causa: Stai usando il nome servizio vecchio o profile sbagliato.

Soluzione:

# Lista servizi disponibili per profile
docker compose --profile dev config --services

# Output atteso:
# app-dev
# queue-worker-dev
# postgres-dev
# etc...

Problema: "port already in use"​

Causa: Vecchi container ancora in esecuzione.

Soluzione:

# Stop tutti i container
docker compose -f docker-compose.dev.yml down  # Se esistono vecchi
docker compose --profile dev down
docker compose --profile staging down
docker compose --profile prod down

# Verifica nessun container attivo
docker ps

# Avvia solo l'ambiente desiderato
./deploy.sh up dev

Problema: "network not found"​

Causa: Network Traefik non esiste (solo per staging/prod).

Soluzione:

# Crea network Traefik
docker network create traefic_traefik-network

# Oppure usa dev (senza Traefik)
./deploy.sh up dev

Problema: "File .env non trovato"​

Causa: Non hai copiato il template.

Soluzione:

cp env.dev.example .env
nano .env  # Modifica valori

🔙 Rollback (se necessario)​

Se qualcosa va storto e vuoi tornare al vecchio sistema:

# 1. Stop nuovo sistema
docker compose --profile dev down

# 2. Ripristina backup
cp docker-compose.yml.backup docker-compose.yml
cp docker-compose.dev.yml.backup docker-compose.dev.yml

# 3. Usa comandi vecchi
docker compose -f docker-compose.dev.yml up -d

⚠️ Nota: I dati nei volumi Docker sono preservati, quindi non perdi database o file caricati.

✅ Checklist Post-Migrazione​

Dopo la migrazione, verifica:

  • Container in esecuzione con nomi nuovi
  • Health check passa (/health endpoint)
  • Logs accessibili (./deploy.sh logs [env])
  • Database raggiungibile
  • Hatchet dashboard funzionante
  • Test funzionalità principali:
    • Upload documenti
    • Chat AI
    • Generazione embedding
    • Task asincroni

📚 Documentazione Aggiuntiva​

File nel Repository​

I seguenti file sono disponibili nel repository tidiko-node-agent:

  • QUICK-START.md - Setup rapido 3 passi
  • DEPLOY-GUIDE.md - Guida completa con troubleshooting
  • deploy.sh - Script helper Linux/Mac
  • deploy.ps1 - Script helper Windows

🚀 Nuovo Comando Deploy Completo​

Entrambi gli script ora includono un comando deploy che esegue automaticamente:

  1. Build delle immagini
  2. Down dei servizi esistenti
  3. Up dei nuovi servizi
  4. Health Check automatico ogni 5 secondi per 2 minuti

Esempi:

# Linux/Mac (primo utilizzo: rendi eseguibile)
chmod +x deploy.sh

# Deploy completo
./deploy.sh deploy dev
./deploy.sh deploy prod
./deploy.sh deploy staging
# Windows PowerShell  
.\deploy.ps1 deploy dev
.\deploy.ps1 deploy prod
.\deploy.ps1 deploy staging

Il comando si ferma automaticamente quando tutti i container sono healthy, oppure mostra un errore dopo 2 minuti di timeout.

🆘 Supporto​

Se incontri problemi durante la migrazione:

  1. Controlla logs: ./deploy.sh logs [env]
  2. Verifica configurazione: cat .env
  3. Lista servizi attivi: ./deploy.sh ps [env]
  4. Rollback se necessario (vedi sopra)
  5. Contatta il team se il problema persiste

La migrazione è stata completata con successo! Il nuovo sistema offre maggiore flessibilità e manutenibilità. 🎉