Setup Ambiente di Sviluppo

Guida completa per configurare l'ambiente di sviluppo di Emblema su sistemi Linux, macOS e Windows.

🛠️ Prerequisiti di Sistema

Sistema Operativo

Linux: Ubuntu 20.04+, Debian 11+, o distribuzioni equivalenti
macOS: 12.0+ (Monterey) con Xcode Command Line Tools
Windows: Windows 10/11 con WSL2 (Ubuntu 22.04 raccomandato)

Strumenti Base Richiesti

1. Docker e Docker Compose

# Ubuntu/Debian
sudo apt update
sudo apt install docker.io docker-compose-plugin
sudo usermod -aG docker $USER

# macOS (usando Homebrew)
brew install --cask docker

# Windows: installa Docker Desktop con WSL2
# https://docs.docker.com/desktop/windows/install/

# Verifica versioni (richiesto Docker Compose v2.20+)
docker --version
docker compose version

Requisiti Docker Compose

Emblema richiede Docker Compose v2.20+ per il supporto delle configurazioni multi-file con la sintassi include.

2. Node.js (tramite nvm)

# Installa nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Ricarica shell
source ~/.bashrc  # o ~/.zshrc

# Installa Node.js 20
nvm install 20
nvm use 20
nvm alias default 20

3. pnpm (Package Manager)

# Installa pnpm globalmente
npm i -g pnpm@8.15.6

# Verifica installazione
pnpm --version

4. Python e uv (raccomandato)

# Installa Python 3.10+
sudo apt install python3.10 python3.10-venv python3-pip  # Ubuntu/Debian

# Installa uv (moderno package manager Python)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Ricarica shell per aggiornare PATH
source ~/.bashrc

5. Git e Strumenti Sviluppo

# Git
sudo apt install git curl wget build-essential

# Configura Git
git config --global user.name "Il Tuo Nome"
git config --global user.email "tua.email@dominio.com"

📦 Clone e Setup Progetto

1. Clone Repository

# Clone del repository
git clone https://github.com/emblema-ai/emblema.git
cd emblema

# Verifica struttura
ls -la

# Copia file di configurazione esempio
cp .env.example .env

2. Installazione Dipendenze

Frontend (pnpm workspace)

# Installa tutte le dipendenze del monorepo
pnpm install

# Verifica installazione
pnpm list --depth=0

Backend Python (per ogni servizio)

# Background Task Service
cd apps/background-task
uv sync
cd ../..

# Document Render Service
cd apps/document-render
uv sync
cd ../..

# MCP Demo Server (opzionale)
cd apps/mcp-demo
uv sync
cd ../..

3. Configurazione Ambiente

File .env

# Copia template ambiente
cp .env.example .env

# Modifica configurazioni base
nano .env

Configurazioni essenziali in .env:

# Domini base
EMBLEMA_WEB_HOSTNAME=localhost
EMBLEMA_WEB_PORT=3000

# Database
POSTGRES_PASSWORD=your_secure_password
HASURA_ADMIN_SECRET=your_hasura_secret

# MinIO Storage
MINIO_ACCESS_KEY_ID=minioadmin
MINIO_SECRET_ACCESS_KEY=your_minio_password

# Auth Keycloak
EMBLEMA_WEB_AUTH_SECRET=your_auth_secret
AUTH_KEYCLOAK_SECRET=your_keycloak_secret

# AI Services
OPENAI_API_KEY=your_openai_key  # opzionale per testing
LITELLM_MASTER_KEY=your_litellm_key

🐳 Setup Docker

1. Inizializzazione Infrastruttura

Installazione Automatica

Lo script install.sh gestisce l'intera configurazione dell'infrastruttura:

# Setup completo con volumi Docker standard (raccomandato)
./install.sh
# Premi Enter quando chiede il percorso per usare volumi Docker standard

# OPPURE con percorso personalizzato per volumi
EMBLEMA_VOLUME_PATH=/data/emblema ./install.sh

Lo script esegue automaticamente:

Import delle immagini Docker (se presenti in docker-images/)
Creazione volumi Docker per persistenza dati
Creazione reti Docker (emblema e redis-net)
Configurazione domini e certificati
Setup servizi base:
- Keycloak (autenticazione)
- MinIO (object storage)
- Hasura (GraphQL API)
- Milvus (vector database)
- Novu (notifiche)

Volumi Docker

Lasciare vuoto il percorso volumi utilizza volumi Docker standard gestiti internamente. Questo è più pulito e raccomandato per lo sviluppo.

2. Creazione Rete Docker

# Crea rete dedicata
docker network create emblema

# Verifica creazione
docker network ls | grep emblema

3. Avvio Servizi Base

Stack Completo

Emblema utilizza Docker Compose con configurazioni modulari:

# Avvia tutti i servizi base
docker compose up -d

# Il docker-compose.yaml principale include:
# - docker-compose-base.yaml (PostgreSQL, Redis, MinIO, Milvus)
# - docker-compose-data-source.yaml (Hasura GraphQL)
# - docker-compose-auth.yaml (Keycloak)
# - docker-compose-llm.yaml (LiteLLM Gateway)
# - docker-compose-monitoring.yaml (Grafana, Prometheus)
# - docker-compose-notification.yaml (Novu)
# - docker-compose-background-task.yaml (Celery workers)

# Verifica status
docker compose ps

# Monitora logs di servizi specifici
docker compose logs -f keycloak
docker compose logs -f hasura
docker compose logs -f background-task

Avvio Selettivo

# Solo database e storage
docker compose -f docker-compose-base.yaml up -d

# Aggiungere autenticazione
docker compose -f docker-compose-base.yaml -f docker-compose-auth.yaml up -d

4. Verifica Servizi

Porte e Servizi Disponibili

Servizio	Porta	URL	Descrizione
www-emblema	3000	http://localhost:3000	App principale (dev)
doc-emblema	3002	http://localhost:3002	Documentazione (dev)
Hasura GraphQL	8080	http://localhost:8080/console	GraphQL Console
Keycloak	8888	http://localhost:8888	Auth Admin Console
MinIO Console	9001	http://localhost:9001	Object Storage UI
MinIO API	9000	http://localhost:9000	S3-compatible API
PostgreSQL	5432	-	Database principale
Redis	6379	-	Cache e message broker
Milvus	19530	-	Vector database API
Attu	8085	http://localhost:8085	Milvus Admin UI
Prometheus	9090	http://localhost:9090	Metrics
Grafana	5050	http://localhost:5050	Monitoring Dashboard
LiteLLM	4000	http://localhost:4000	AI Gateway
Document Render	8094	http://localhost:8094	Rendering service
Traefik	80/443	-	Reverse proxy
Novu API	3003-3004	http://localhost:3003	Notification service

Verifica Health

# Verifica servizi principali
curl http://localhost:8080/healthz      # Hasura GraphQL
curl http://localhost:19530/health      # Milvus
curl http://localhost:4000/health       # LiteLLM

# Se app è in esecuzione
curl http://localhost:3000/api/health   # www-emblema

🚀 Sviluppo

1. Sviluppo Frontend

Applicazione Principale

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

# L'app sarà disponibile su http://localhost:3000

Libreria UI Componenti

# Avvia UI library in sviluppo
pnpm --filter=ui dev

# Componenti disponibili su http://localhost:6006

Documentazione

# Avvia Docusaurus in sviluppo
pnpm docs:dev

# Docs disponibili su http://localhost:3001

2. Sviluppo Backend Python

Background Task Service

cd apps/background-task

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

# In un altro terminale, avvia API FastAPI
uv run fastapi dev app/main.py --port 8001

Document Render Service

cd apps/document-render

# Avvia servizio rendering documenti
uv run fastapi dev app/main.py --port 8094

3. Hot Reload e Watch Mode

Frontend con Turbo

# Avvia tutti i servizi frontend con hot reload
pnpm dev

# Solo servizi specifici
pnpm --filter=www-emblema --filter=ui dev

Backend con Auto-reload

# FastAPI con auto-reload
uv run fastapi dev app/main.py --reload

# Celery con auto-reload (watchdog)
uv run celery -A app.celery_app worker --loglevel=info --pool=solo

🔧 Strumenti Sviluppo Raccomandati

Editor / IDE

VS Code con estensioni:
- Python
- TypeScript and JavaScript Language Features
- Tailwind CSS IntelliSense
- Docker
- GitLens
- Prettier - Code formatter
- ESLint

Browser Extensions

React Developer Tools
Redux DevTools (se utilizzato)
Apollo Client DevTools (per GraphQL)

Terminale

# Installa oh-my-zsh (opzionale ma raccomandato)
sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

# Plugin utili: git, docker, node, python

📊 Monitoraggio Sviluppo

Logs in Tempo Reale

# Logs di tutti i servizi Docker
docker compose logs -f

# Logs servizio specifico
docker compose logs -f www-emblema
docker compose logs -f background-task

# Logs con filtro
docker compose logs -f | grep ERROR

Health Checks

# Script di health check personalizzato
./scripts/health-check.sh

# Verifica singoli servizi
curl http://localhost:8080/healthz      # Hasura
curl http://localhost:19530/health      # Milvus
curl http://localhost:6379/ping         # Redis

Monitoring Resources

# Monitor risorse Docker
docker stats

# Monitor specifico
docker stats $(docker compose ps -q)

🐛 Troubleshooting Comune

Port Già in Uso

# Trova processo su porta specifica
lsof -i :3000
sudo netstat -tulpn | grep :3000

# Termina processo
kill -9 <PID>

Problemi Docker

Servizi che non si avviano

# Verifica logs specifici
docker compose logs keycloak   # Spesso problemi di init
docker compose logs hasura     # Dipende da postgres
docker compose logs milvus     # Richiede molta RAM

# Riavvia servizio singolo
docker compose restart keycloak

# Ricrea servizio con nuovo build
docker compose up -d --force-recreate --build www-emblema

Pulizia Volumi (ATTENZIONE: cancella dati!)

# Pulizia sicura (mantiene volumi)
docker compose down
docker system prune -f

# Pulizia completa con script dedicato
./install/clean-docker-volumes.sh

# Pulizia manuale volumi Emblema
docker volume ls | grep emblema | awk '{print $2}' | xargs docker volume rm

Problemi di Rete

# Ricrea reti Docker
docker network rm emblema redis-net
./install/create-docker-networks.sh

# Verifica connettività
docker run --rm --network emblema alpine ping -c 3 postgres

Problemi Node/pnpm

# Pulizia cache pnpm
pnpm store prune

# Reinstallazione dipendenze
rm -rf node_modules
rm pnpm-lock.yaml
pnpm install

Problemi Python/uv

# Reinstalla ambiente virtuale
rm -rf .venv
uv sync --reinstall

# Problemi con dipendenze GPU (MinerU, WhisperX)
uv sync --extra gpu   # Se hai GPU NVIDIA

# Cache corrotta
uv cache clean
uv sync

Problemi Specifici Servizi

Keycloak non si avvia

# Verifica se il database è pronto
docker compose exec postgres pg_isready

# Reset Keycloak (perde configurazioni!)
docker compose stop keycloak
docker volume rm emblema-keycloak-data
./install/setup-keycloak.sh

Milvus errori di memoria

# Milvus richiede almeno 8GB RAM liberi
# Modifica in docker-compose-base.yaml:
# deploy:
#   resources:
#     limits:
#       memory: 4g  # Riduci se necessario

MinIO permission denied

# Fix permessi volume MinIO
docker compose exec -u root minio chown -R 1001:1001 /data

Permissions Linux

# Fix permissions Docker
sudo chown -R $USER:$USER ~/.docker

# Fix permissions progetto
sudo chown -R $USER:$USER .

📝 Next Steps

Dopo aver completato il setup:

Architettura Codice - Comprendi la struttura del progetto
Sviluppo Frontend - Inizia con lo sviluppo frontend
Sviluppo Backend - Lavora sui servizi backend
Testing e Debugging - Setup testing e debugging

💡 Suggerimenti Pro

Alias Utili

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

# Emblema aliases
alias e-dev="pnpm --filter=www-emblema dev"
alias e-build="pnpm build"
alias e-logs="docker compose logs -f"
alias e-restart="docker compose restart"
alias e-clean="docker compose down && docker system prune -f"

Git Hooks

# Setup pre-commit hooks (opzionale)
pnpm dlx husky install
echo "pnpm lint" > .husky/pre-commit
chmod +x .husky/pre-commit

Il tuo ambiente di sviluppo è ora pronto! 🎉

🛠️ Prerequisiti di Sistema​

Sistema Operativo​

Strumenti Base Richiesti​

1. Docker e Docker Compose​

2. Node.js (tramite nvm)​

3. pnpm (Package Manager)​

4. Python e uv (raccomandato)​

5. Git e Strumenti Sviluppo​

📦 Clone e Setup Progetto​

1. Clone Repository​

2. Installazione Dipendenze​

Frontend (pnpm workspace)​

Backend Python (per ogni servizio)​

3. Configurazione Ambiente​

File .env​

🐳 Setup Docker​

1. Inizializzazione Infrastruttura​

Installazione Automatica​

2. Creazione Rete Docker​

3. Avvio Servizi Base​

Stack Completo​

Avvio Selettivo​

4. Verifica Servizi​

Porte e Servizi Disponibili​

Verifica Health​

🚀 Sviluppo​

1. Sviluppo Frontend​

Applicazione Principale​

Libreria UI Componenti​

Documentazione​

2. Sviluppo Backend Python​

Background Task Service​

Document Render Service​

3. Hot Reload e Watch Mode​

Frontend con Turbo​

Backend con Auto-reload​

🔧 Strumenti Sviluppo Raccomandati​

Editor / IDE​

Browser Extensions​

Terminale​

📊 Monitoraggio Sviluppo​

Logs in Tempo Reale​

Health Checks​

Monitoring Resources​

🐛 Troubleshooting Comune​

Port Già in Uso​

Problemi Docker​

Servizi che non si avviano​

Pulizia Volumi (ATTENZIONE: cancella dati!)​

Problemi di Rete​

Problemi Node/pnpm​

Problemi Python/uv​

Problemi Specifici Servizi​

Keycloak non si avvia​

Milvus errori di memoria​

MinIO permission denied​

Permissions Linux​

📝 Next Steps​

💡 Suggerimenti Pro​

Alias Utili​

Git Hooks​

Questa pagina ti è stata utile?