Simmetric Chat
Retour à la documentation
Guide 01

Guide de démarrage

Simmetric Chat est une plateforme de chat IA local-first et capable de fonctionner hors connexion (air-gap) : elle fonctionne sans accès aux services cloud externes, avec un LLM local (Ollama), des embeddings locaux (Xenova) et une base vectorielle local…

4 min de lecture

Simmetric Chat est une plateforme de chat IA local-first et capable de fonctionner hors connexion (air-gap) : elle fonctionne sans accès aux services cloud externes, avec un LLM local (Ollama), des embeddings locaux (Xenova) et une base vectorielle locale (LanceDB). Elle peut toutefois utiliser des fournisseurs cloud (OpenAI, Anthropic, OpenRouter) et une base vectorielle distante (Qdrant) lorsqu'ils sont configurés.

Prérequis

  • Node.js ≥ 24 et pnpm 11.24.0 (le gestionnaire du monorepo ; `corepack enable && corepack prepare [email protected] --activate`)
  • PostgreSQL 16 (base de données principale)
  • Ollama (optionnel mais recommandé pour le LLM local) - https://ollama.com
  • Docker + Docker Compose (pour le déploiement conteneurisé, voir 09 - Deployment)

Vérification :

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

Installation (développement local)

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

Le monorepo utilise pnpm workspaces + Turborepo. Les packages sont dans packages/ : shared, server, frontend, collector, widget, plus l'application desktop src-tauri/.

Variables d'environnement

Tous les packages lisent le `.env` à la racine du dépôt (le fichier de configuration runtime unique ; l'ancien niveau de .env par package a été supprimé : précédence process.env > .env racine > valeurs par défaut du code). Créez le fichier minimal :

bash
cp .env.example .env

Secrets obligatoires (JWT_SECRET, COLLECTOR_SECRET) et clé widget :

env
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 est requise par le service widget (son propre schéma Zod fait sortir le processus sans elle) ; le serveur l'enregistre comme clé API du compte widget-service au démarrage (idempotent). Optionnels en développement : API_KEY_HMAC_SECRET (les clés API sk- restent inutilisables tant qu'il n'est pas défini) et ENCRYPTION_KEY (repli scryptSync(JWT_SECRET) ; requis en production). LICENSE_KEY absent = build Community.

Tableau complet des variables d'environnement : 03 - Configuration.

Base de données

Créez la base PostgreSQL (ex. docker compose -f docker/docker-compose.infra.yml up -d postgres), puis générez le client Prisma, appliquez les migrations et le seed :

bash
pnpm db:generate                  # génère le client Prisma (+ correctif symlink Prisma 7/pnpm)
pnpm --filter server db:migrate   # applique les migrations (interactif)
pnpm --filter server db:seed      # rôles par défaut (Admin, Superuser, User), permissions, config, templates

Alternative au seed manuel : sur une base vide, le frontend affiche l'assistant de configuration en 4 étapes (admin, fournisseur LLM, base vectorielle) - ou le serveur auto-seede l'admin de bootstrap (SEED_BOOTSTRAP_ADMIN=true par défaut, configurable via SEED_ADMIN_USERNAME / SEED_ADMIN_PASSWORD / SEED_ADMIN_EMAIL, valeurs par défaut admin / admin123 / [email protected] avec mustChangePassword=true). L'auto- enregistrement est désactivé par défaut (ALLOW_REGISTRATION=false) : un admin crée les utilisateurs depuis Settings ou via POST /api/auth/admin-register.

Démarrage en développement

Une seule commande lance tous les services via Turborepo :

bash
pnpm dev

Ports par défaut :

ServicePortDescription
frontend5173SPA Vite (React 19), proxy /api → server
server3000API Express + Swagger sur /api-docs
collector3210Microservice d'ingestion de documents
widget3211Service widget embarquable (Preact)

Ouvrez http://localhost:5173, connectez-vous avec admin / admin123, changez le mot de passe.

Si Ollama n'est pas en cours d'exécution, les conversations échouent avec une erreur de
connexion. Téléchargez un modèle avec ollama pull gemma4:latest && ollama serve, ou
configurez un fournisseur cloud dans Settings → Providers.

Visite rapide de l'interface

  • Sidebar - groupes filtrés par rôle : Overview (dashboard), Chat (chat, projects, workspaces), Knowledge (documents, base de connaissances, uploads), Platform (widgets, marketplace, analytics - admin), System (journal d'événements, SSO - admin/enterprise). Les entrées suivent les 13 sections de menu RBAC.
  • Chat - streaming token par token, sélection de modèle par conversation (Cmd+K palette), comparaison côte à côte (Cmd+Shift+M), citations RAG, commande /model.
  • Documents - upload par glisser-déposer (PDF, DOCX, XLSX, PPTX, TXT, MD, CSV, images avec OCR), statut pending → processing → completed → failed.
  • Settings - 5 onglets principaux (Profil, Fournisseurs LLM, Apparence, Sécurité, Avancé) imbriquant les sous-sections : Providers, LLM & Embedding, Vector DB, API Keys, Roles, Users, MCP Connections, Maintenance, Backups, DLP, Widget (page dédiée), OCR, etc.
  • Maintenance - réindexation RAG en un clic après un changement de modèle d'embedding.

Premiers pas recommandés

  1. Configurez un fournisseur - Settings → Providers : ajoutez Ollama (local) ou OpenAI/Anthropic.
  2. Créez un workspace et un projet - les documents et conversations sont limités au workspace.
  3. Chargez un document - Documents → upload ; attendez le statut completed.
  4. Discutez - ouvrez une conversation dans le workspace et posez des questions sur le document (RAG hybride).
  5. (Admin) Explorez le marketplace - installez un serveur MCP pour étendre l'agent avec des outils.

Prochaines étapes