Passa al contenuto principale

Comandi Utili

Raccolta di comandi frequentemente utilizzati nello sviluppo di Emblema, organizzati per categoria.

📦 Gestione Dipendenze​

pnpm - Package Manager​

# Installa tutte le dipendenze del monorepo
pnpm install

# Installa in un workspace specifico
pnpm --filter=www-emblema add <package>
pnpm --filter=ui add -D <dev-package>

# Rimuovi dipendenza
pnpm --filter=www-emblema remove <package>

# Update dipendenze
pnpm update
pnpm update --interactive

# Pulizia cache
pnpm store prune

uv - Python Package Manager​

# Installa dipendenze Python
cd apps/background-task
uv sync

# Aggiungi dipendenza
uv add fastapi
uv add --dev pytest

# Crea ambiente virtuale
uv venv

# Attiva ambiente
source .venv/bin/activate  # Linux/macOS

🏗️ Build & Development​

Sviluppo Frontend​

# Avvia app principale in sviluppo
pnpm --filter=www-emblema dev

# Avvia tutti i servizi frontend
pnpm dev

# Build produzione
pnpm build
pnpm --filter=www-emblema build

# Type checking
pnpm type-check

# Linting
pnpm lint
pnpm lint:fix

# Formattazione codice
pnpm format

Sviluppo Backend​

# FastAPI development server
cd apps/background-task
uv run fastapi dev app/main.py --reload --port 8001

# Celery worker
uv run celery -A app.celery_app worker --loglevel=info

# Celery Flower (monitoring)
uv run celery -A app.celery_app flower --port=5555

# Run tests
uv run pytest
uv run pytest -v --cov=app

🐳 Docker Commands​

Container Management​

# Build immagini
pnpm docker:build
docker compose build --no-cache www-emblema

# Avvia servizi
docker compose up -d
docker compose up -d www-emblema background-task

# Stop servizi
docker compose stop
docker compose down

# Restart servizio
docker compose restart www-emblema

# Logs
docker compose logs -f
docker compose logs -f www-emblema
docker compose logs --tail=100 background-task

# Shell in container
docker compose exec www-emblema sh
docker compose exec background-task bash

Docker Utility​

# Pulizia sistema
docker system prune -f
docker volume prune -f
docker image prune -a -f

# Export/Import immagini
pnpm export-docker-images
pnpm import-docker-images

# Stats risorse
docker stats
docker compose stats

# Inspect
docker compose ps
docker network ls
docker volume ls

🔧 Installazione & Setup​

Setup Iniziale​

# Clone repository
git clone <repo-url>
cd emblema

# Setup completo con script
./install.sh

# Con percorso custom per volumi
EMBLEMA_VOLUME_PATH=/data/emblema ./install.sh

# Setup manuale
cp .env.example .env
docker network create emblema
docker compose up -d

Gestione Volumi​

# Lista volumi Emblema
docker volume ls | grep emblema

# Backup volume
docker run --rm -v emblema-postgres-data:/data -v $(pwd):/backup alpine tar czf /backup/postgres-backup.tar.gz -C /data .

# Restore volume
docker run --rm -v emblema-postgres-data:/data -v $(pwd):/backup alpine tar xzf /backup/postgres-backup.tar.gz -C /data

# Pulizia volumi (ATTENZIONE!)
./install/clean-docker-volumes.sh

🔍 Debugging & Monitoring​

Logs e Debugging​

# Logs in tempo reale
docker compose logs -f --tail=50

# Logs con filtro
docker compose logs -f | grep ERROR
docker compose logs -f www-emblema | grep -i auth

# Debug Python con debugpy
# In apps/background-task/app/main.py aggiungere:
# import debugpy
# debugpy.listen(("0.0.0.0", 5678))

# Debug Next.js
# In .env.local
DEBUG_MODE=1
NEXT_PUBLIC_DEBUG=true

Health Checks​

# Check salute servizi
curl http://localhost:8080/healthz      # Hasura
curl http://localhost:19530/health      # Milvus
curl http://localhost:4000/health       # LiteLLM
curl http://localhost:3000/api/health   # www-emblema

# Check connettività
docker compose exec www-emblema ping postgres
docker compose exec www-emblema ping redis-master
docker compose exec www-emblema ping milvus

Performance Monitoring​

# Monitor risorse Docker
docker stats $(docker compose ps -q)

# Monitor Celery tasks
docker compose exec background-task celery -A app.celery_app inspect active
docker compose exec background-task celery -A app.celery_app inspect stats

# Database queries
docker compose exec postgres psql -U emblema -c "SELECT * FROM pg_stat_activity;"

🔒 Security Scanning​

Vulnerability Scanning​

# Scan completo con report
pnpm security:full

# Solo scan
pnpm security:scan

# Genera report HTML
pnpm security:report

# Scan specifico servizio
./scripts/security/scan.sh www-emblema

# Test security fixes
./scripts/security/test-container-security.sh www-emblema

SBOM Generation​

# Genera Software Bill of Materials
./scripts/security/generate-sbom.sh

# Check dipendenze sicurezza
./scripts/security/check-security-deps.sh

📝 Git Workflow​

Branch Management​

# Crea feature branch
git checkout -b feature/nome-feature

# Update da main
git checkout main
git pull origin main
git checkout feature/nome-feature
git rebase main

# Push changes
git add .
git commit -m "feat: descrizione feature"
git push origin feature/nome-feature

Commit Convention​

# Tipi di commit
feat:     # Nuova feature
fix:      # Bug fix
docs:     # Documentazione
style:    # Formattazione
refactor: # Refactoring
test:     # Test
chore:    # Manutenzione

# Esempi
git commit -m "feat: aggiunto supporto chunking audio"
git commit -m "fix: corretto errore upload file grandi"
git commit -m "docs: aggiornata guida setup ambiente"

🎯 Generazione Codice​

Plop Generators​

# Genera nuovo servizio Python
pnpm plop:service
# Input: nome-servizio
# Output: apps/nome-servizio/

# Genera nuova web app
pnpm plop:web
# Input: nome-app
# Output: apps/nome-app/

# Genera componente UI
pnpm plop:component
# Input: NomeComponente
# Output: packages/ui/src/components/

🌐 Database Operations​

PostgreSQL​

# Accedi a psql
docker compose exec postgres psql -U emblema

# Backup database
docker compose exec postgres pg_dump -U emblema emblema > backup.sql

# Restore database
docker compose exec -T postgres psql -U emblema emblema < backup.sql

# Query utili
docker compose exec postgres psql -U emblema -c "SELECT COUNT(*) FROM documents;"

Redis​

# Redis CLI
docker compose exec redis-master redis-cli

# Monitor comandi
docker compose exec redis-master redis-cli monitor

# Info server
docker compose exec redis-master redis-cli info

# Flush cache (ATTENZIONE!)
docker compose exec redis-master redis-cli FLUSHDB

Milvus​

# Check collections via Python
docker compose exec www-emblema python -c "
from pymilvus import connections, list_collections
connections.connect(host='milvus', port='19530')
print(list_collections())
"

# Attu UI
# Apri browser: http://localhost:8085

🚀 Deploy & CI/CD​

Build per Produzione​

# Build tutte le immagini
pnpm docker:build

# Tag per registry
docker tag emblema/www:dev registry.esempio.com/emblema/www:v1.0.0

# Push a registry
docker push registry.esempio.com/emblema/www:v1.0.0

Export per Air-Gap​

# Export immagini
pnpm export-docker-images
# Crea: docker-images-YYYYMMDD-HHMMSS.tar.gz

# Import su server target
pnpm import-docker-images docker-images-20240120-143022.tar.gz

🛠️ Utility Scripts​

Alias Consigliati​

Aggiungi al tuo ~/.bashrc o ~/.zshrc:

# Emblema shortcuts
alias e-dev="pnpm --filter=www-emblema dev"
alias e-logs="docker compose logs -f"
alias e-restart="docker compose restart"
alias e-build="pnpm build"
alias e-lint="pnpm lint:fix && pnpm format"
alias e-test="pnpm test"
alias e-clean="docker compose down && docker system prune -f"

# Docker shortcuts
alias dc="docker compose"
alias dce="docker compose exec"
alias dcl="docker compose logs -f"
alias dcp="docker compose ps"
alias dcs="docker compose stats"

Funzioni Utili​

# Funzione per entrare in container
emblema-shell() {
  docker compose exec $1 sh
}

# Funzione per logs con grep
emblema-grep() {
  docker compose logs -f $1 | grep -i $2
}

# Uso:
# emblema-shell www-emblema
# emblema-grep background-task error

📊 Monitoring URLs​

Durante lo sviluppo, questi URL sono disponibili:

ServizioURLCredenziali
App Principalehttp://localhost:3000Via Keycloak
Documentazionehttp://localhost:3002-
Hasura Consolehttp://localhost:8080/consoleAdmin secret in .env
Keycloakhttp://localhost:8888admin/password da .env
MinIO Consolehttp://localhost:9001root user da .env
Attu (Milvus)http://localhost:8085-
Grafanahttp://localhost:5050admin/password da .env
Celery Flowerhttp://localhost:5555-
LiteLLMhttp://localhost:4000Master key da .env

🆘 Troubleshooting Rapido​

# Container non parte
docker compose logs <service-name>
docker compose up <service-name>  # Vedi errori in tempo reale

# Porta già in uso
lsof -i :3000
kill -9 <PID>

# Permission denied
sudo chown -R $USER:$USER .

# Spazio disco pieno
docker system prune -a -f --volumes
df -h

# Reset completo (ATTENZIONE!)
docker compose down -v
./install/clean-docker-volumes.sh
rm -rf node_modules pnpm-lock.yaml
./install.sh

💡 Tip: Salva questa pagina nei bookmark per accesso rapido durante lo sviluppo!

Questa pagina ti è stata utile?