Passa al contenuto principale

Deploy e Monitoraggio

Questa guida descrive i processi di deploy e monitoraggio per tutti gli ambienti della piattaforma.

Ambienti Disponibili​

1. Sviluppo (Development)​

  • Branch: develop o branch di feature
  • URL: http://localhost:3000 (app) + http://localhost:3300 (worker)
  • Database: PostgreSQL locale
  • Queue: Hatchet Lite

2. Stage​

  • Branch: stage
  • URL: https://langgraphjs-stage.tidiko.ai
  • Dashboard Hatchet: https://hatchet.stage.tidiko.ai
  • Database: PostgreSQL su VPS

3. Produzione (Production)​

  • Branch: main
  • URL: https://langgraphjs.tidiko.ai
  • Dashboard Hatchet: https://hatchet.prod.tidiko.ai
  • Database: PostgreSQL su VPS

Flusso di Deploy​

Workflow Completo​

1. Deploy Ambiente di Sviluppo​

Setup Iniziale​

# Clona il repository
git clone https://github.com/netingweb/tidiko-node-agent.git
cd tidiko-node-agent

# Copia le variabili d'ambiente
cp .env.example .env

# Configura le variabili per lo sviluppo
# Modifica .env con i valori appropriati

Avvio con Docker Compose​

Nuovo Sistema Unificato

A partire dalla versione corrente, usiamo un singolo file docker-compose.yml con Profiles per gestire tutti gli ambienti.

# Copia configurazione ambiente
Copy-Item env.dev.example .env

# Modifica .env con i tuoi valori
notepad .env

# Avvia ambiente di sviluppo
.\deploy.ps1 up dev

# Verifica stato
.\deploy.ps1 ps dev

# Visualizza logs
.\deploy.ps1 logs dev -Follow

Servizi Disponibili​

  • App LangGraph: http://localhost:3000
  • Worker: http://localhost:3300
  • PostgreSQL: localhost:5432
  • Hatchet Dashboard: http://localhost:8888
  • MinIO Console: http://localhost:9001

2. Deploy Stage​

Prerequisiti​

  1. Pull Request su branch stage:
  1. Fare il commit dei cambiamenti da VS Code, Cursor o GitHub Desktop con un messaggio chiaro e descrittivo
  2. Fare il push dei cambiamenti da VS Code, Cursor o GitHub Desktop
  3. Apri GitHub Desktop
  4. Clicca sul bottone "Preview Pull Request". Se non si vede la scritta "Preview Pull Request", clicca sulla freccia accanto alla scritta "Create Pull Request" e poi su "Preview Pull Request". GitHub Desktop Preview Pull Request
  5. Selziona la branch stage o origin/stage e clicca su "Create Pull Request", si aprirà la pagina del Pull Request su GitHub GitHub Desktop Create Pull Request
  6. Clicca sul bottone "Create Pull Request"
  7. Clicca sul bottone "Merge pull Request"
  8. Clicca sul bottone "Confirm merge"
  9. Clicca sul bottone "Delete branch" (se non è più necessaria il branch di feature)

  1. Accesso SSH al server VPS:

    informazioni

    Scarica la chiave da 1Password: neting-contabo-private-key-2

    ssh -i [percorso-chiave] root@161.97.184.132

Deploy su Stage​

Connettiti al server

ssh -i [percorso-chiave] root@161.97.184.132

Naviga alla directory stage

cd /home/tidiko-node-agent-stage

Aggiorna il codice

git pull origin stage

Deploy con rebuild

docker compose down
docker compose up -d --build --force-recreate

Verifica lo stato. Tutti i container devono avere lo stato "up" e healthy. Da controllare che il tempo nello status "up" incrementi, e con si siano riavvi, se ci sono dei riavvi è perché il container non si è avviato correttamente. Tutti i container dovrebbero avere lo stato healthy entro 40 secondi. Se non è così, controlla i logs per vedere il motivo.

docker compose ps
docker compose logs -f

Test Post-Deploy​

  1. Verifica URL: https://langgraphjs-stage.tidiko.ai/health
  2. Test funzionalità principali:
    • Upload documenti
    • Chat AI
    • Generazione embedding
  3. Monitoraggio logs: dashboard Yacht (Dashboard Yacht, credenziali in 1Password)

3. Deploy Produzione​

Prerequisiti​

  1. Test completi su stage
  2. Pull Request da stage a main:
  1. Apri GitHub Desktop
  2. Passa alla branch stage
  3. Clicca su "Pull Origin" o "Fetch Origin"
  4. Clicca sul bottone "Preview Pull Request". Se non si vede la scritta "Preview Pull Request", clicca sulla freccia accanto alla scritta "Create Pull Request" e poi su "Preview Pull Request". GitHub Desktop Preview Pull Request
  5. Selziona la branch main o origin/main (se non è già selezionata) e clicca su "Create Pull Request", si aprirà la pagina del Pull Request su GitHub GitHub Desktop Create Pull Request
  6. Clicca sul bottone "Create Pull Request"
  7. Clicca sul bottone "Merge pull Request"
  8. Clicca sul bottone "Confirm merge"
Importante

Il branch branch stage NON deve essere eliminato.

Deploy su Produzione​

Connettiti al server

ssh -i [percorso-chiave] root@161.97.184.132

Naviga alla directory produzione

cd /home/tidiko-node-agent-prod

Aggiorna il codice

git pull origin main

Deploy con rebuild

# Ferma ambiente produzione
docker compose --profile prod down

# Avvia con rebuild (forza ricreazione)
docker compose --profile prod up -d --build --force-recreate

# OPPURE usa script helper
# ./deploy.sh down prod
# ./deploy.sh build prod
# ./deploy.sh up prod

Verifica lo stato. Tutti i container devono avere lo stato "up" e healthy. Da controllare che il tempo nello status "up" incrementi, e con si siano riavvi, se ci sono dei riavvi è perché il container non si è avviato correttamente. Tutti i container dovrebbero avere lo stato healthy entro 40 secondi. Se non è così, controlla i logs per vedere il motivo.

# Con profile prod
docker compose --profile prod ps
docker compose --profile prod logs -f

# OPPURE con script helper
# ./deploy.sh ps prod
# ./deploy.sh logs prod -f

Test Post-Deploy​

  1. Verifica URL: https://langgraphjs-prod.tidiko.ai/health
  2. Test funzionalità critiche:
    • Upload documenti
    • Chat AI
    • Generazione embedding
    • Salvataggio chat
  3. Monitoraggio completo: Tutti i sistemi

Configurazione Docker​

Sistema Unificato con Profiles​

Novità

Il sistema ora utilizza un singolo file docker-compose.yml con Docker Compose Profiles per gestire tutti gli ambienti (dev, staging, prod). Questo elimina la duplicazione e semplifica la gestione.

File di Configurazione​

File Unificato​

  • Docker Compose: docker-compose.yml (con profiles: dev, staging, prod)
  • Script Helper: deploy.sh (Linux/Mac), deploy.ps1 (Windows)
  • Env Templates: env.dev.example, env.staging.example, env.prod.example

Dockerfile per Ambiente​

Sviluppo:

  • Dockerfile App: Dockerfile.dev
  • Dockerfile Worker: Dockerfile.worker.dev

Staging/Produzione:

  • Dockerfile App: Dockerfile
  • Dockerfile Worker: Dockerfile.worker

Variabili d'Ambiente​

Gestione Semplificata

Ogni ambiente ha il suo file template: env.dev.example, env.staging.example, env.prod.example. Copia il template appropriato in .env e modifica i valori secondo le tue necessità.

Sviluppo​

.env (da env.dev.example)
# Variabili principali
NODE_ENV=development
APP_PORT=3000
WORKER_PORT=3300
DB_PORT=5432
HATCHET_DB_PORT=5434

# Database
DB_URI=postgresql://postgres:postgres@postgres-dev:5432/langgraphjs_dev

# MinIO (Object Storage)
MINIO_ENDPOINT=http://minio:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET_NAME=crawler-results

# Hatchet Lite (per dev)
HATCHET_HOST=host.docker.internal:7077

Staging​

.env (da env.staging.example)
# Variabili principali
NODE_ENV=production
SENTRY_ENVIRONMENT=staging
SUBDOMAIN=staging-langgraphjs

# Porte diverse da prod
APP_PORT=3001
DB_PORT=5436
HATCHET_DB_PORT=5437

# Database
DB_URI=postgresql://${DB_USER}:${DB_PASSWORD}@postgres-staging:5432/${DB_NAME}

# MinIO (Object Storage)
MINIO_ENDPOINT=http://minio:9000
MINIO_ACCESS_KEY=${MINIO_ACCESS_KEY}
MINIO_SECRET_KEY=${MINIO_SECRET_KEY}
MINIO_BUCKET_NAME=${MINIO_BUCKET_NAME}

Produzione​

.env (da env.prod.example)
# Variabili principali
NODE_ENV=production
SENTRY_ENVIRONMENT=production
SUBDOMAIN=langgraphjs

# Porte
APP_PORT=3000
WORKER_PORT=3300
DB_PORT=5433

# Database
DB_URI=postgresql://${DB_USER}:${DB_PASSWORD}@postgres-prod:5432/${DB_NAME}

# MinIO (Object Storage)
MINIO_ENDPOINT=http://minio:9000
MINIO_ACCESS_KEY=${MINIO_ACCESS_KEY}
MINIO_SECRET_KEY=${MINIO_SECRET_KEY}
MINIO_BUCKET_NAME=${MINIO_BUCKET_NAME}

Monitoraggio​

1. Monitoraggio Logs​

Dashboard Yacht​

  • URL: http://161.97.184.132:8000/#/apps
  • Funzionalità:
    • Lista container in esecuzione
    • Visualizzazione logs in tempo reale
    • Stato dei servizi

Troubleshooting Logs​

Se i logs non si caricano:

  1. Copia il link della pagina
  2. Chiudi la scheda
  3. Apri nuova scheda con il link copiato

Logs via SSH​

  1. Connettiti al server
ssh -i [percorso-chiave] root@161.97.184.132
  1. Visualizza logs specifici
# Con profile staging
docker compose --profile staging logs -f app-staging
docker compose --profile staging logs -f queue-worker-staging

# Con script helper
./deploy.sh logs staging -f

2. Monitoraggio Task (Hatchet)​

Dashboard Hatchet​

Stage:

Produzione:

Metriche Disponibili​

  • Task completate/fallite
  • Tempo medio di esecuzione
  • Queue size
  • Worker status
  • Error rate

3. Monitoraggio Agente (LangSmith)​

Dashboard LangSmith​

Progetti per Ambiente​

Sviluppo:

  • Progetto: tidiko-agent
  • Monitoraggio: Interazioni agente, costi, tool usage

Stage:

  • Progetto: tidiko-agent-stage
  • Monitoraggio: Test stage

Produzione:

  • Progetto: tidiko-agent-prod
  • Monitoraggio: Performance produzione

Metriche Disponibili​

  • Costo per messaggio
  • Utilizzo tool
  • Tempo di risposta
  • Qualità risposte
  • Error rate

Troubleshooting​

Problemi Comuni​

1. Container non si avvia​

# Verifica logs (es. staging)
docker compose --profile staging logs app-staging

# Riavvia servizio
docker compose --profile staging restart app-staging

# Rebuild completo
docker compose --profile staging down
docker compose --profile staging build
docker compose --profile staging up -d

# OPPURE con script helper
./deploy.sh logs staging
./deploy.sh restart staging
./deploy.sh down staging
./deploy.sh build staging
./deploy.sh up staging

2. Database connection error​

# Verifica stato PostgreSQL (es. prod)
docker compose --profile prod ps postgres-prod

# Riavvia database
docker compose --profile prod restart postgres-prod

# Verifica connessione
docker compose --profile prod exec postgres-prod psql -U [user] -d [database]

# Con script helper
./deploy.sh ps prod
./deploy.sh restart prod

3. Worker non processa task​

# Verifica Hatchet (es. prod)
docker compose --profile prod ps hatchet-engine-prod

# Riavvia worker
docker compose --profile prod restart queue-worker-prod

# Verifica queue
# Accedi a dashboard Hatchet

# Con script helper
./deploy.sh ps prod
./deploy.sh restart prod

4. Memory issues​

# Verifica utilizzo memoria
docker stats

# Pulisci container non utilizzati
docker system prune -f

# Riavvia servizi (es. prod)
docker compose --profile prod restart

# Con script helper
./deploy.sh restart prod

Comandi Utili​

Con Script Helper (Consigliato)​

# Stato generale
.\deploy.ps1 ps prod

# Logs in tempo reale
.\deploy.ps1 logs prod -Follow

# Riavvia
.\deploy.ps1 restart prod

# Ferma
.\deploy.ps1 down prod

# Rebuilda
.\deploy.ps1 build prod

# Avvia
.\deploy.ps1 up prod

# Pulizia completa
.\deploy.ps1 clean prod

# 🚀 DEPLOY COMPLETO (Build → Down → Up → Health Check)
.\deploy.ps1 deploy prod

Docker Compose Diretto​

# Stato generale
docker compose --profile prod ps

# Logs in tempo reale
docker compose --profile prod logs -f

# Riavvia servizio specifico
docker compose --profile prod restart app-prod

# Rebuild completo
docker compose --profile prod down
docker compose --profile prod build
docker compose --profile prod up -d

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

# Lista tutti i profiles
docker compose config --profiles

# Pulisci sistema
docker system prune -f

# Verifica spazio disco
df -h

# Verifica memoria
free -h

Sicurezza​

Accesso SSH​

  • Chiave privata: Scaricare da 1Password (neting-contabo-private-key-2)
  • Server: 161.97.184.132
  • User: root

Variabili Sensibili​

  • Tutte le chiavi API sono gestite tramite variabili d'ambiente
  • Non committare mai file .env con dati sensibili
  • Utilizzare .env.example come template

Backup​

  • Backup automatico su VPS
  • Configurazioni: Versionate su Git

Checklist Deploy​

Pre-Deploy​

  • Test completi su ambiente di sviluppo
  • Pull Request creata su branch corretto
  • Code review completata
  • Variabili d'ambiente verificate

Deploy​

  • Accesso SSH al server
  • Backup automatico su VPS
  • Deploy eseguito
  • Verifica stato container
  • Test funzionalità principali

Post-Deploy​

  • Monitoraggio logs
  • Test completi
  • Verifica metriche
  • Documentazione aggiornata
  • Team notificato

Contatti e Supporto​

  • Server VPS: 161.97.184.132
  • SSH Key: 1Password (neting-contabo-private-key-2)
  • LangSmith: Dashboard
  • Hatchet Stage: https://hatchet.stage.tidiko.ai
  • Hatchet Prod: https://hatchet.prod.tidiko.ai