BullMQ & Bull Board - Quick Start

Installazione

I pacchetti necessari sono già installati:


{
  "dependencies": {
    "bullmq": "^5.64.1",
    "@bull-board/api": "^6.16.2",
    "@bull-board/ui": "^6.16.2",
    "ioredis": "^5.8.2"
  }
}

Setup Redis

Assicurati che Redis sia in esecuzione. Configura le variabili d’ambiente:


REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=  # opzionale

Avvio Redis locale (macOS):


brew services start redis

Avvio Workers

I workers elaborano i job dalle code. Devono essere sempre attivi:

Sviluppo (con auto-reload):


npm run workers

Produzione:


npm run workers:prod

Con PM2 (consigliato per produzione):


pm2 start ecosystem.config.js

Accesso Bull Board

Dashboard Web

Apri il browser e vai a:


http://localhost:3000/api/admin/bull-board

La dashboard mostra:

✅ Stato di tutte le code in tempo reale
📊 Metriche (waiting, active, completed, failed, delayed)
🔍 Dettagli di ogni singolo job
⚡ Azioni: retry, remove, pause/resume code
📈 Grafici e statistiche

Alternative se la UI non carica

Dashboard Semplificata


http://localhost:3000/api/admin/queue-status

API REST


# Metriche complete
curl http://localhost:3000/api/admin/queues/metrics
 
# Job di una coda specifica
curl http://localhost:3000/api/admin/queues/bankTransactionAutoMatch/jobs?status=failed

Troubleshooting

Bull Board si blocca al caricamento

Possibili cause e soluzioni:

Redis non raggiungibile


# Verifica Redis
redis-cli ping
# Dovrebbe rispondere: PONG
 
# Se non funziona, avvia Redis
brew services start redis  # macOS

Variabili d’ambiente mancanti
```
# Verifica .env
cat .env | grep REDIS
```

Workers non attivi


# Verifica che i workers siano in esecuzione
ps aux | grep workers
 
# Riavvia workers
npm run workers:prod

Usa la dashboard alternativa


http://localhost:3000/api/admin/queue-status

Documentazione Completa

Per maggiori dettagli consulta:

BULL_BOARD_ADMIN.md - Guida amministratore completa
BULLMQ_GUIDE.md - Guida sviluppatore BullMQ