Simmetric Chat
Back to docs
Guide 01

Getting Started

Deploy Simmetric Chat in 60 seconds. pnpm or Docker Compose.

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 20+ e pnpm 9+ (gestore del monorepo)
  • 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

Ogni package legge il proprio .env (risolto via path.resolve(__dirname, "../../.env"), indipendente dalla cwd). Crea i file minimi:

packages/server/.env (obbligatori: JWT_SECRET, COLLECTOR_SECRET):

NODE_ENV=development
SERVER_PORT=3000
DATABASE_URL=postgresql://simmetricchat:simmetricchat@localhost:5432/simmetricchat
JWT_SECRET=cambia-questo-segreto-in-produzione
COLLECTOR_SECRET=cambia-questo-shared-secret
LLM_PROVIDER=ollama
LLM_MODEL=gemma4:latest
OLLAMA_BASE_URL=http://localhost:11434
ALLOW_REGISTRATION=true

packages/collector/.env:

COLLECTOR_PORT=3210
SERVER_URL=http://localhost:3000
COLLECTOR_SECRET=cambia-questo-shared-secret   # deve matchare il server
EMBEDDING_PROVIDER=local
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2
VECTOR_DB_PROVIDER=lancedb
STORAGE_PATH=./storage

packages/widget/.env (solo se usi il widget):

WIDGET_PORT=3211
SERVER_URL=http://localhost:3000
WIDGET_API_KEY=sk-<genera-un-token-casuale>

Tabella completa delle env var: 03 — Configuration.

Database

Crea il database PostgreSQL, poi genera il client Prisma, applica le migrazioni e il seed:

pnpm db:generate        # genera il client Prisma
pnpm db:migrate         # applica le migrazioni (interattivo)
pnpm db:seed            # ruoli di default (Admin, Superuser, User), permessi, config, template

Il seed crea anche un admin bootstrap (admin / admin123) con mustChangePassword=true, quindi al primo login ti verrà chiesto di cambiare la password. Puoi disabilitare l'auto-seed con SEED_BOOTSTRAP_ADMIN=false.

Avvio in sviluppo

Un singolo comando avvia tutti i service tramite Turborepo:

pnpm dev

Porte di default:

ServicePortaDescrizione
frontend5173SPA Vite (React 19), proxy /api → server
server3000API Express + Swagger su /api-docs
collector3210Microservice ingestion documenti
widget3211Service widget embeddabile (Preact)

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 — sezioni filtrate per ruolo: chat, documents, workspaces, projects, marketplace (admin), eventLog (admin), analytics (admin), settings, mcpConnections, archives, synthesis.
  • 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 — 11+ tab: General, Providers, LLM, Vector DB, API Keys, Users, Roles, Embed Widget, Widgets, MCP Connections, OCR, Maintenance.
  • 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.

Prossimi passi