Installazione Locale

Guida step-by-step per l'installazione completa dell'ambiente di sviluppo Emblema in locale.

📋 Overview

Emblema utilizza un approccio containerizzato per semplificare l'installazione locale. Tutto l'ambiente di sviluppo viene orchestrato tramite Docker Compose con configurazione modulare, garantendo consistenza tra ambienti diversi.

🔄 Processo di Installazione Completo

1. Clone Repository

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

# Verifica branch corrente
git branch
git status

# Se necessario, switch al branch di sviluppo
git checkout develop

Alternative per Contributor

# Fork e clone (per contributor)
# 1. Fai fork su GitHub
# 2. Clone del tuo fork
git clone https://github.com/TUO_USERNAME/emblema.git
cd emblema

# 3. Aggiungi upstream
git remote add upstream https://github.com/emblema-ai/emblema.git
git remote -v

# 4. Mantieni sincronizzato
git fetch upstream
git checkout main
git merge upstream/main

2. Verifica Prerequisiti

Prima di iniziare, eseguiamo un controllo dei prerequisiti:

# Verifica Docker e Docker Compose
docker --version
docker compose version

# Verifica spazio disco disponibile (minimo 50GB raccomandati)
df -h .

# Verifica memoria disponibile (minimo 16GB raccomandati)
free -h

# Su macOS: system_profiler SPHardwareDataType | grep "Memory:"

3. Configurazione Environment

Copia e Configura Environment Variables

# Copia il template delle variabili d'ambiente
cp .env.example .env

# Modifica il file .env per il tuo setup
nano .env  # o vim .env, code .env

Variabili Critiche da Configurare

# === PERCORSI VOLUMI ===
# Opzione 1: Usa Docker volumes (raccomandato per sviluppo)
# Lascia vuoto per usare Docker volumes
EMBLEMA_VOLUME_PATH=

# Opzione 2: Usa percorso custom (per produzione o storage specifico)
# EMBLEMA_VOLUME_PATH=/data/emblema

# === NETWORKING ===
EMBLEMA_DOMAIN=localhost
EMBLEMA_WEB_HOSTNAME=localhost

# === SECURITY ===
# Genera password sicure
POSTGRES_PASSWORD=$(openssl rand -base64 32)
HASURA_ADMIN_SECRET=$(openssl rand -base64 32)
AUTH_SECRET=$(openssl rand -base64 32)
CRON_SECRET=$(openssl rand -base64 32)

# === API KEYS (opzionali per sviluppo) ===
# Lascia vuoto se non hai API keys
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
LITELLM_MASTER_KEY=$(openssl rand -base64 32)
LITELLM_SALT_KEY=$(openssl rand -base64 32)

# === AI MODELS ===
DEFAULT_CHAT_MODEL=llama3.3-70b-instruct
DEFAULT_EMBEDDING_MODEL=bge-m3

Script di Configurazione Automatica

#!/bin/bash
# scripts/setup-local-env.sh

set -e

echo "🔧 Configurando ambiente locale Emblema..."

# Verifica se .env esiste
if [ ! -f .env ]; then
    if [ -f .env.example ]; then
        cp .env.example .env
        echo "✅ File .env creato da template"
    else
        echo "❌ .env.example non trovato!"
        exit 1
    fi
fi

# Genera segreti se non esistono
if ! grep -q "POSTGRES_PASSWORD=" .env || [ -z "$(grep POSTGRES_PASSWORD .env | cut -d'=' -f2)" ]; then
    POSTGRES_PASS=$(openssl rand -base64 32)
    sed -i "s/POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$POSTGRES_PASS/" .env
    echo "✅ Password PostgreSQL generata"
fi

if ! grep -q "HASURA_ADMIN_SECRET=" .env || [ -z "$(grep HASURA_ADMIN_SECRET .env | cut -d'=' -f2)" ]; then
    HASURA_SECRET=$(openssl rand -base64 32)
    sed -i "s/HASURA_ADMIN_SECRET=.*/HASURA_ADMIN_SECRET=$HASURA_SECRET/" .env
    echo "✅ Hasura admin secret generato"
fi

if ! grep -q "AUTH_SECRET=" .env || [ -z "$(grep AUTH_SECRET .env | cut -d'=' -f2)" ]; then
    AUTH_SECRET=$(openssl rand -base64 32)
    sed -i "s/AUTH_SECRET=.*/AUTH_SECRET=$AUTH_SECRET/" .env
    echo "✅ Auth secret generato"
fi

if ! grep -q "CRON_SECRET=" .env || [ -z "$(grep CRON_SECRET .env | cut -d'=' -f2)" ]; then
    CRON_SECRET=$(openssl rand -base64 32)
    sed -i "s/CRON_SECRET=.*/CRON_SECRET=$CRON_SECRET/" .env
    echo "✅ Cron secret generato"
fi

echo "🎯 Ambiente locale configurato!"
echo "📝 Modifica .env per personalizzazioni aggiuntive"

4. Installazione Automatica

Il modo più semplice per iniziare è usare lo script di installazione automatica:

# Esegui installazione completa
./install.sh

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

Cosa fa lo Script install.sh

# Lo script install.sh esegue automaticamente:

# 1. Verifica prerequisiti
echo "Verificando Docker e Docker Compose..."

# 2. Configura network Docker
docker network create emblema 2>/dev/null || true

# 3. Importa immagini Docker (se disponibili)
if [ -f "docker-images.tar.gz" ]; then
    echo "Importando immagini Docker pre-build..."
    pnpm import-docker-images
fi

# 4. Setup volumi e permessi
echo "Configurando volumi di storage..."

# 5. Avvia servizi base (database, cache, etc.)
docker compose up -d postgres redis minio

# 6. Aspetta che i servizi siano pronti
echo "Aspettando che i servizi base siano pronti..."

# 7. Inizializza database
docker compose up -d hasura
# Hasura applica automaticamente migrazioni

# 8. Avvia tutti i servizi
docker compose up -d

5. Installazione Manuale Step-by-Step

Se preferisci un controllo completo del processo:

Step 5.1: Network Docker

# Crea network condivisa per tutti i servizi
docker network create emblema

Step 5.2: Installazione Dependencies Node.js

# Installa pnpm (se non presente)
npm install -g pnpm@latest

# Installa dependencies del monorepo
pnpm install

# Verifica installazione
pnpm --version
node --version

Step 5.3: Build delle Immagini Docker

# Opzione A: Build tutte le immagini localmente (può richiedere 30-60 minuti)
docker compose build

# Opzione B: Import immagini pre-build (se disponibili)
# Scarica docker-images.tar.gz dal release
pnpm import-docker-images

# Verifica immagini
docker images | grep emblema

Step 5.4: Avvio Sequenziale dei Servizi

# 1. Avvia servizi di base (database, storage, cache)
docker compose up -d postgres redis minio

# Aspetta che siano ready
docker compose exec postgres pg_isready -U postgres
docker compose exec redis redis-cli ping

# 2. Avvia servizi infrastrutturali
docker compose up -d hasura keycloak traefik litellm

# 3. Avvia servizi backend AI
docker compose up -d background-task document-render

# 4. Avvia applicazione web
docker compose up -d www-emblema

# 5. Avvia servizi di monitoring (opzionali)
docker compose up -d grafana prometheus flower

Step 5.5: Verifica Installazione

# Controlla status di tutti i servizi
docker compose ps

# Verifica logs per errori
docker compose logs -f --tail=50

# Test endpoint principali
curl http://localhost:3000  # Frontend
curl http://localhost:8080/healthz  # Hasura
curl http://localhost:8000/health  # Background Task Service

🔧 Configurazioni Avanzate

Storage Personalizzato

# Configura percorso custom per volumi persistenti
export EMBLEMA_VOLUME_PATH=/data/emblema

# Crea struttura directory
mkdir -p $EMBLEMA_VOLUME_PATH/{postgres,milvus,minio,shared}

# Imposta permessi corretti
chmod 755 $EMBLEMA_VOLUME_PATH
chown -R 1001:1001 $EMBLEMA_VOLUME_PATH/minio  # MinIO user
chown -R 70:70 $EMBLEMA_VOLUME_PATH/postgres   # PostgreSQL user

# Riavvia con nuovo percorso
docker compose down
docker compose up -d

Configurazione GPU per AI Locale

# Installa NVIDIA Container Toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

# Verifica GPU access nei container
docker run --rm --gpus all nvidia/cuda:11.8-base-ubuntu20.04 nvidia-smi

# Abilita GPU in .env
echo "ENABLE_GPU=true" >> .env

# Riavvia background-task service
docker compose up -d background-task

Development con Code Reload

# Per sviluppo frontend con hot reload
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d

# Oppure usa il comando dedicato
pnpm dev

# Per backend Python con reload
cd apps/background-task
uv sync
uv run fastapi dev

🧪 Testing dell'Installazione

Verifica Servizi Base

#!/bin/bash
# scripts/test-installation.sh

echo "🧪 Testing installazione Emblema..."

# Test database connectivity
echo "📊 Testing PostgreSQL..."
docker compose exec postgres psql -U postgres -d emblema -c "SELECT version();"

# Test Redis
echo "📦 Testing Redis..."
docker compose exec redis redis-cli ping

# Test MinIO
echo "🗄️ Testing MinIO..."
curl -I http://localhost:9001/minio/health/live

# Test Hasura
echo "🔗 Testing Hasura GraphQL..."
curl -X POST http://localhost:8080/v1/graphql \
  -H "Content-Type: application/json" \
  -H "x-hasura-admin-secret: $(grep HASURA_ADMIN_SECRET .env | cut -d'=' -f2)" \
  -d '{"query": "{ __schema { types { name } } }"}'

# Test Frontend
echo "🌐 Testing Frontend..."
curl -I http://localhost:3000/

# Test Background Task API
echo "🤖 Testing Background Task Service..."
curl http://localhost:8000/health

echo "✅ Test completati!"

Verifica Funzionalità AI

# Test upload e processamento documento
curl -X POST http://localhost:3000/api/v1/documents/upload \
  -F "file=@test-document.pdf" \
  -F "knowledge_base_id=default"

# Monitora task Celery
open http://localhost:5555  # Flower UI

# Test embedding generation
docker compose exec background-task python -c "
from app.handlers.embeddings import EmbeddingHandler
handler = EmbeddingHandler()
embeddings = handler.generate_embeddings(['Test document'])
print(f'Generated {len(embeddings)} embeddings of dimension {len(embeddings[0])}')
"

🐛 Troubleshooting

Problemi Comuni

Problema	Sintomi	Soluzione
Port già in uso	port is already allocated	docker compose down && pkill -f "docker-proxy"
Spazio disco insufficiente	no space left on device	docker system prune -a --volumes
Servizi non si avviano	Container exit con errore	docker compose logs [service-name]
GPU non rilevata	CUDA errors	Verificare NVIDIA drivers e container toolkit
Permissions errors	Access denied su volumi	Verificare ownership e permessi directory volumi
Database connection failed	App non si connette a DB	Verificare POSTGRES_* variables in .env
Frontend non carica	Pagina bianca o errori	Verificare build frontend e environment variables

Script di Diagnosi

#!/bin/bash
# scripts/diagnose-installation.sh

echo "🔍 Diagnosticando installazione Emblema..."

# System info
echo "=== SYSTEM INFO ==="
uname -a
docker --version
docker compose version

# Disk space
echo "=== DISK SPACE ==="
df -h

# Memory usage
echo "=== MEMORY USAGE ==="
free -h

# Docker info
echo "=== DOCKER INFO ==="
docker system df
docker network ls | grep emblema
docker volume ls | grep emblema

# Container status
echo "=== CONTAINER STATUS ==="
docker compose ps

# Recent logs
echo "=== RECENT LOGS ==="
docker compose logs --tail=10 www-emblema
docker compose logs --tail=10 background-task
docker compose logs --tail=10 postgres

# Port usage
echo "=== PORT USAGE ==="
netstat -tulpn | grep -E ':(3000|8000|8080|5432|6379|9000|19530|8180)'

# Environment check
echo "=== ENVIRONMENT CHECK ==="
[ -f .env ] && echo "✅ .env file exists" || echo "❌ .env file missing"
[ -n "$POSTGRES_PASSWORD" ] && echo "✅ POSTGRES_PASSWORD set" || echo "⚠️ POSTGRES_PASSWORD not set"
[ -n "$HASURA_ADMIN_SECRET" ] && echo "✅ HASURA_ADMIN_SECRET set" || echo "⚠️ HASURA_ADMIN_SECRET not set"

echo "🏁 Diagnosi completata!"

Reset Completo

#!/bin/bash
# scripts/reset-installation.sh

echo "🔄 Reset completo installazione..."

# Stop e rimuovi tutti i container
docker compose down -v --remove-orphans

# Rimuovi immagini Emblema
docker rmi $(docker images | grep emblema | awk '{print $3}')

# Pulisci volumi
docker volume prune -f

# Pulisci network
docker network rm emblema 2>/dev/null || true

# Reset .env
rm -f .env
cp .env.example .env

echo "✅ Reset completato! Puoi ora rifare l'installazione"

Logs e Monitoring

# Segui logs in tempo reale
docker compose logs -f

# Logs specifici per servizio
docker compose logs -f www-emblema
docker compose logs -f background-task
docker compose logs -f postgres

# Export logs per debug
docker compose logs > emblema-logs-$(date +%Y%m%d-%H%M%S).log

# Monitoring risorse
watch docker stats

# Inspect container specifico
docker compose exec www-emblema /bin/sh

🚀 Ottimizzazioni per Development

Configurazione IDE

# VS Code settings per Emblema
mkdir -p .vscode
cat > .vscode/settings.json << 'EOF'
{
  "typescript.preferences.importModuleSpecifier": "relative",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
    "source.organizeImports": true
  },
  "docker.dockerComposeBuild": false,
  "docker.dockerComposeDetached": true,
  "python.defaultInterpreterPath": "./apps/background-task/.venv/bin/python",
  "eslint.workingDirectories": [
    "./apps/www-emblema",
    "./apps/doc-emblema"
  ]
}
EOF

# Workspace extensions
cat > .vscode/extensions.json << 'EOF'
{
  "recommendations": [
    "ms-vscode-remote.remote-containers",
    "ms-azuretools.vscode-docker",
    "bradlc.vscode-tailwindcss",
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "ms-python.python",
    "ms-python.flake8",
    "charliermarsh.ruff"
  ]
}
EOF

Git Hooks per Development

# Setup pre-commit hooks
pnpm dlx husky install

# Lint prima del commit
echo "pnpm lint-staged" > .husky/pre-commit
chmod +x .husky/pre-commit

# Install lint-staged config
cat >> package.json << 'EOF'
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{md,json}": [
      "prettier --write"
    ]
  }
EOF

📚 Next Steps

Dopo aver completato l'installazione:

1. Esplora l'Interfaccia: Visita http://localhost:3000
2. Leggi la Documentazione: http://localhost:3001 (Docusaurus)
3. Monitora i Servizi: http://localhost:5555 (Flower), http://localhost:3030 (Grafana)
4. Configura IDE: Segui Configurazione IDE
5. Primo Upload: Testa caricando un documento PDF
6. Debug Setup: Usa Troubleshooting Setup se necessario

📋 Checklist Post-Installazione

• ✅ Tutti i servizi Docker sono running (docker compose ps)
• ✅ Frontend accessibile su http://localhost:3000
• ✅ Hasura GraphQL Explorer su http://localhost:8080
• ✅ Flower UI (Celery monitoring) su http://localhost:5555
• ✅ Upload di un documento test funziona
• ✅ Background task processing funziona
• ✅ Database PostgreSQL connesso e migrazioni applicate
• ✅ Redis cache funzionante
• ✅ Milvus vector database ready
• ✅ Storage MinIO configurato
• ✅ Environment variables configurate correttamente
• ✅ GPU access configurato (se applicabile)
• ✅ IDE configurato con extensions
• ✅ Git hooks configurati per development quality