Simmetric Chat
Voltar para a documentação
Guia 01

Guia de início

Simmetric Chat é uma plataforma de chat de IA local-first e capaz de funcionar offline (air-gap): funciona sem conexão a serviços cloud externos, com LLM local (Ollama), embeddings locais (Xenova) e vector DB local (LanceDB). Pode, no entanto, usar prove…

4 min de leitura

Simmetric Chat é uma plataforma de chat de IA local-first e capaz de funcionar offline (air-gap): funciona sem conexão a serviços cloud externos, com LLM local (Ollama), embeddings locais (Xenova) e vector DB local (LanceDB). Pode, no entanto, usar provedores cloud (OpenAI, Anthropic, OpenRouter) e um vector DB remoto (Qdrant) quando configurado.

Pré-requisitos

  • Node.js ≥ 24 e pnpm 11.24.0 (o gerenciador do monorepo; `corepack enable && corepack prepare [email protected] --activate`)
  • PostgreSQL 16 (banco de dados principal)
  • Ollama (opcional, mas recomendado para o LLM local) - https://ollama.com
  • Docker + Docker Compose (para deploy conteinerizado, ver 09 - Deployment)

Verificar:

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

Instalação (desenvolvimento local)

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

O monorepo usa pnpm workspaces + Turborepo. Os pacotes ficam em packages/: shared, server, frontend, collector, widget, além do app desktop src-tauri/.

Variáveis de ambiente

Todos os pacotes leem o `.env` na raiz do repositório (o único arquivo de configuração runtime; a antiga camada de .env por pacote foi removida: precedência process.env > .env raiz > padrões do código). Crie o arquivo mínimo:

bash
cp .env.example .env

Segredos obrigatórios (JWT_SECRET, COLLECTOR_SECRET) e a chave do 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 é exigida pelo serviço widget (seu próprio schema Zod encerra o processo sem ela); o servidor a registra como chave de API da conta widget-service no boot (idempotente). Opcionais em desenvolvimento: API_KEY_HMAC_SECRET (as chaves de API sk- ficam inutilizáveis até serem definidas) e ENCRYPTION_KEY (fallback scryptSync(JWT_SECRET); obrigatória em produção). LICENSE_KEY ausente = build Community.

Tabela completa de variáveis de ambiente: 03 - Configuration.

Banco de dados

Crie o banco PostgreSQL (ex.: docker compose -f docker/docker-compose.infra.yml up -d postgres), depois gere o client Prisma, aplique as migrações e o seed:

bash
pnpm db:generate                  # gera o client Prisma (+ fix de symlink Prisma 7/pnpm)
pnpm --filter server db:migrate   # aplica as migrações (interativo)
pnpm --filter server db:seed      # papéis padrão (Admin, Superuser, User), permissões, config, templates

Alternativa ao seed manual: em um banco vazio, o frontend mostra o assistente de setup em 4 etapas (admin, provedor LLM, vector DB) - ou o servidor auto-seeda o admin de bootstrap (SEED_BOOTSTRAP_ADMIN=true por padrão, configurável via SEED_ADMIN_USERNAME / SEED_ADMIN_PASSWORD / SEED_ADMIN_EMAIL, padrões admin / admin123 / [email protected] com mustChangePassword=true). O auto-registro é fechado por padrão (ALLOW_REGISTRATION=false): um admin cria usuários a partir de Settings ou via POST /api/auth/admin-register.

Iniciando o desenvolvimento

Um único comando inicia todos os serviços via Turborepo:

bash
pnpm dev

Portas padrão:

ServicePortaDescrição
frontend5173SPA Vite (React 19), proxy /api → server
server3000API Express + Swagger em /api-docs
collector3210Microsserviço de ingestão de documentos
widget3211Serviço de widget incorporável (Preact)

Abra http://localhost:5173, entre com admin / admin123, troque a senha.

Se o Ollama não estiver em execução, os chats falham com erro de conexão. Baixe um modelo
com ollama pull gemma4:latest && ollama serve, ou configure um provedor cloud em
Settings → Providers.

Tour rápido da UI

  • Sidebar - grupos filtrados por papel: Overview (dashboard), Chat (chat, projects, workspaces), Knowledge (documents, base de conhecimento, uploads), Platform (widgets, marketplace, analytics - admin), System (event log, SSO - admin/enterprise). Os itens seguem as 13 seções de menu RBAC.
  • Chat - streaming token por token, seleção de modelo por chat (paleta Cmd+K), comparação lado a lado (Cmd+Shift+M), citações RAG, comando slash /model.
  • Documents - upload drag & drop (PDF, DOCX, XLSX, PPTX, TXT, MD, CSV, imagens com OCR), status pending → processing → completed → failed.
  • Settings - 5 abas principais (Perfil, Provedores LLM, Aparência, Segurança, Avançado) aninhando as subseções: Providers, LLM & Embedding, Vector DB, API Keys, Roles, Users, MCP Connections, Maintenance, Backups, DLP, Widget (página dedicada), OCR, etc.
  • Maintenance - reindexação RAG em um clique após mudança do modelo de embedding.

Primeiros passos recomendados

  1. Configure um provedor - Settings → Providers: adicione Ollama (local) ou OpenAI/Anthropic.
  2. Crie um workspace e um projeto - documentos e chats são restritos ao workspace.
  3. Carregue um documento - Documents → upload; aguarde o status completed.
  4. Converse - abra um chat no workspace e faça perguntas sobre o documento (RAG híbrido).
  5. (Admin) Explore o marketplace - instale um servidor MCP para estender o agente com ferramentas.

Próximos passos