Guida introduttiva

Simmetric Chat è una piattaforma di chat AI local-first e air-gap capable: funziona senza connessione a servizi cloud esterni, con LLM locale (Ollama), embedding locale (Xenova) e vector DB locale (LanceDB). Può però usare provider cloud (OpenAI, Anthropic, OpenRouter) e vector DB remoto (Qdrant) quando configurato.

Prerequisiti

• Node.js ≥ 24 e pnpm 12.8.1 (gestore del monorepo, pinnato via packageManager; corepack enable && corepack prepare [email protected] --activate)
• PostgreSQL 16 (database principale)
• Ollama (opzionale ma raccomandato per LLM locale) - https://ollama.com
• Docker + Docker Compose (per il deployment containerizzato, vedi 09 - Deployment)

Verifica:

node -v && pnpm -v && psql --version

Installazione (sviluppo locale)

git clone <repo> simmetric-chat
cd simmetric-chat
pnpm install

Il monorepo usa pnpm workspaces + Turborepo. I package sono in packages/: shared, server, frontend, collector, widget, più l'app desktop src-tauri/.

Variabili d'ambiente

Tutti i package leggono il `.env` alla radice del repo (l'unico file di configurazione runtime; la vecchia layer di .env per-package è stata rimossa: precedenza process.env > .env radice > default del codice). Crea il file minimo:

cp .env.example .env

Segreti obbligatori (JWT_SECRET, COLLECTOR_SECRET) e chiave widget:

JWT_SECRET=$(openssl rand -hex 32)
COLLECTOR_SECRET=$(openssl rand -hex 32)
WIDGET_API_KEY=$(openssl rand -hex 32)
DATABASE_URL=postgresql://simmetricchat:simmetricchat@localhost:5432/simmetricchat
LLM_PROVIDER=ollama
LLM_MODEL=gemma4:latest
OLLAMA_BASE_URL=http://localhost:11434

WIDGET_API_KEY è richiesta dal service widget (lo schema Zod proprio fa uscire il processo senza); il server la registra come API key dell'account widget-service al boot (idempotente). Opzionali in sviluppo: API_KEY_HMAC_SECRET (le API key sk- restano inutilizzabili finché non è impostata) ed ENCRYPTION_KEY (fallback scryptSync(JWT_SECRET); obbligatoria in produzione). LICENSE_KEY assente = build Community.

Tabella completa delle env var: 03 - Configuration.

Database

Crea il database PostgreSQL (es. docker compose -f docker/docker-compose.infra.yml up -d postgres), poi genera il client Prisma, applica le migrazioni e il seed:

pnpm db:generate                  # genera il client Prisma (+ fix symlink Prisma 7/pnpm)
pnpm --filter server db:migrate   # applica le migrazioni (interattivo)
pnpm --filter server db:seed      # ruoli di default (Admin, Superuser, User), permessi, config, template

In alternativa al seed manuale: su un DB vuoto il frontend mostra il setup wizard in 4 step (admin, provider LLM, vector DB) - oppure il server auto-seeda l'admin bootstrap (SEED_BOOTSTRAP_ADMIN=true di default, configurabile via SEED_ADMIN_USERNAME / SEED_ADMIN_PASSWORD / SEED_ADMIN_EMAIL, default admin / admin123 / [email protected] con mustChangePassword=true). La self-registration è chiusa di default (ALLOW_REGISTRATION=false): gli utenti li crea un admin da Settings o via POST /api/auth/admin-register.

Avvio in sviluppo

Un singolo comando avvia tutti i service tramite Turborepo:

pnpm dev

Porte di default:

Apri http://localhost:5173, accedi con admin / admin123, cambia la password.

Se Ollama non è in esecuzione, le chat falliranno con errore di connessione. Avvia un

modello con ollama pull gemma4:latest && ollama serve, oppure configura un provider cloud

in Settings → Providers.

Tour rapido dell'UI

• Sidebar - gruppi filtrati per ruolo: Overview (dashboard), Chat (chat, projects, workspaces), Knowledge (documents, knowledge base, uploads), Platform (widgets, marketplace, analytics - admin), System (event log, SSO - admin/enterprise). Le voci seguono le 15 menu sections RBAC (le due novità v0.28.1: skills, plugins).
• Chat - streaming token-per-token, selezione modello per-chat (Cmd+K palette), confronto affiancato (Cmd+Shift+M), citazioni RAG, /model slash command.
• Documents - upload drag&drop (PDF, DOCX, XLSX, PPTX, TXT, MD, CSV, immagini con OCR), stato pending → processing → completed → failed.
• Settings - 5 tab principali (Profilo, Provider LLM, Aspetto, Sicurezza, Avanzate) che annidano le sotto-sezioni: Providers, LLM & Embedding, Vector DB, API Keys, Roles, Users, MCP Connections, Maintenance, Backups, DLP, Widget (pagina dedicata), OCR, ecc.
• Maintenance - reindex RAG one-click dopo cambio modello di embedding.

Primi passi consigliati

1. Configura un provider - Settings → Providers: aggiungi Ollama (locale) o OpenAI/Anthropic.
2. Crea un workspace e un progetto - i documenti e le chat sono workspace-scoped.
3. Carica un documento - Documents → upload; attendi lo stato completed.
4. Chatta - apri una chat nel workspace e fai domande sul documento (RAG ibrido).
5. (Admin) Esplora il marketplace - installa un MCP server per estendere l'agente con tool.

Le nuove guide v0.28.1

Il guide si è esteso con sei nuove pagine tecniche: 13 - Connectors, 14 - Wiki Knowledge Engine, 15 - Custom Skills, 16 - Document DLP Pipeline, 17 - Quotas & Costs, 18 - Synthesis Pipeline.

Provenienza v0.28.1

Riferimento operativo - Simmetric Chat v0.28.1 (docs aggiornate 2026-10-02, census SHA `aca5b8ff`).

Prossimi passi

• Capire come funziona sotto: 02 - Architecture
• Tutte le env var e i feature flag: 03 - Configuration
• Embeddare la chat sul tuo sito: 06 - Widget Integration