Developer FAQ

Answers to the most common questions about installing, configuring, and developing with Synaplan.

Installation

New to self-hosting? Start with the Quickstart & Self-Hosting walkthrough — it covers the smooth install path and the common pitfalls (the local-AI model download, Qdrant, TTS, and the production Galera cluster). The answers below are the detailed reference.

How do I install Synaplan?

Clone the repository and start the Docker services:

git clone https://github.com/metadist/synaplan.git
cd synaplan
docker compose up -d

Open http://localhost:5173 — the app should be ready in about 2 minutes.

What are the install options?

The minimal install skips the Ollama container and is ideal if you only plan to use cloud providers like OpenAI, Anthropic, Google Gemini, Groq, Mistral, or TrustedTokens.

What are the default login credentials?

What services are available after startup?

What runs under the hood?

Besides the URLs above, the stack starts several internal services with no host ports: Redis (cache, sessions, locks, job queues, realtime engine), Centrifugo (WebSocket gateway for live support), a background worker (async AI/indexing jobs), Qdrant (vector database), and Tika (document text extraction). They need zero configuration locally — see Architecture & Realtime for what each one does.

Configuration & the .env File

What is the .env file?

The file backend/.env is where the infrastructure configuration lives: database connections, email settings, authentication, realtime secrets, and more. (AI provider API keys are best managed in the UI under Admin → AI Providers — env keys are supported as a bootstrap and imported into the encrypted store on first use.)

A fully documented template is provided at backend/.env.example. To get started:

cp backend/.env.example backend/.env

Then edit backend/.env with your own values. The file is git-ignored, so your credentials stay local.

What are the main sections in .env?

Do I need to set all variables?

No. The only things required for a working local install are the defaults already in .env.example. Everything else is opt-in — add API keys for the providers you want to use, and leave the rest empty.

Adding Your Own API Keys

What's the easiest way to add a key?

Use the UI: log in as an admin and open Admin → AI Providers. Paste the key and it is validated live against the provider, stored AES-256 encrypted in the database, and active immediately — no restart, no .env editing. The same page can set the provider's recommended models as the install-wide defaults in one click.

The env variables below still work and are the right tool for scripted or orchestrated deploys: a key found in the environment is imported into the encrypted store on first use. Rotating the env value rotates the stored copy; a key saved through the UI permanently wins over the env var, so you can remove it from .env afterwards.

Which providers can I plug in?

Every key is optional and independent: add only the ones you want (via Admin → AI Providers or the env variable), and the matching models appear in the selector.

How do I add an OpenAI key?

Paste it under Admin → AI Providers, or set it in backend/.env:

OPENAI_API_KEY=sk-your-openai-key-here

The GPT-5.6 family (Sol, Terra, Luna), GPT-5.5 / GPT-5.5 Pro, the GPT-5.4 family, GPT-4o mini, GPT Image 1.5, Whisper, and the text-embedding-3 models will become available in the model selector.

How do I add an Anthropic key?

ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here

Claude Opus 5, Claude Sonnet 5, Claude Fable 5, Claude Opus 4.8, and Claude Haiku 4.5 will appear (chat + vision).

Older generations (Claude Opus 4.1 / 4.5 / 4.6 / 4.7 and Sonnet 4.5 / 4.6) were retired from the catalog in July 2026. On an existing install, a migration deactivates those rows and repoints any default that still used them to the current equivalent — Sonnet 5 for the Sonnet line, Opus 4.8 for the Opus line. Nothing is deleted, so past messages keep their model reference.

How do I add a Google Gemini key?

GOOGLE_GEMINI_API_KEY=your-gemini-key-here

Enables Gemini 3.1 Pro, Gemini 3.5 / 3 Flash, Gemini 3.1 Flash-Lite, the Gemini 2.5 family, plus Google's media models (Imagen 4 including Fast and Ultra, Nano Banana / 2 / Pro, Veo 3.1 video, Gemini Flash TTS).

How do I add a Groq key?

GROQ_API_KEY=gsk_your-groq-key-here

Groq provides ultra-fast inference for open models like Llama 3.3 70B, Llama 3.1 8B Instant, Qwen3 32B, and GPT-OSS 20B/120B, plus Llama 4 Scout vision and Whisper Large v3 transcription.

How do I add a Mistral key?

MISTRAL_API_KEY=your-mistral-key-here

French/EU-hosted models: Mistral Medium 3.5 (chat + vision), Mistral Large 3, and the Voxtral audio pair (Mini Transcribe for speech-to-text, Voxtral TTS for voice output).

How do I add an xAI (Grok) key?

XAI_API_KEY=your-xai-key-here

Enables Grok 4.5 chat and image understanding with a 500K-token context window, Grok Imagine for image and video generation, and Grok voice (TTS + transcription). Get a key at console.x.ai under Team → API Keys.

How do I add a TrustedTokens key? 🇩🇪

TRUSTEDTOKENS_API_KEY=your-trustedtokens-key-here

TrustedTokens is TNG Technology Consulting's sovereign inference platform: open-weight models served from GPUs in Munich, under German jurisdiction, with zero data retention and no CLOUD Act exposure. Synaplan talks to it through its OpenAI-compatible API at https://api.trustedtokens.eu/v1, so it behaves like any other cloud provider — but the tokens never leave Germany.

Enabling the key adds:

Get a key at trustedtokens.eu under Account → API Access.

How do I add a HuggingFace key?

HUGGINGFACE_API_KEY=hf_your-token-here

Routes the Kimi K2.5, K2.6 and K2.7 Code models (chat + vision) through HF Inference.

How do I add image and video generation?

THEHIVE_API_KEY=your-thehive-key-here
HIGGSFIELD_API_KEY=your-higgsfield-key-here
HIGGSFIELD_API_SECRET=your-higgsfield-secret-here

TheHive adds Flux Schnell and SDXL image models; Higgsfield adds Soul and Reve images plus DoP and Kling 2.1 video. Higgsfield needs both halves of the credential — the key alone will not authenticate. Google's Imagen / Nano Banana / Veo models come with the Gemini key instead.

How do I use Ollama (local models)?

Ollama runs as a Docker service in the standard install — no API key needed. It's available at http://ollama:11435 inside the Docker network.

To change the Ollama URL (e.g., if running Ollama on the host):

OLLAMA_BASE_URL=http://host.docker.internal:11434

Models are downloaded automatically when first selected. The standard install pre-pulls gpt-oss:20b (chat) and bge-m3 (embeddings). You can also pull others manually:

docker compose exec ollama ollama pull gpt-oss:20b

Can I use multiple providers at the same time?

Yes. Set as many API keys as you like. Each user can choose their preferred model per task (chat, vision, embeddings, image generation) in the admin panel under System Config → AI Models.

Model Pricing & Cost Transparency

What does each model cost?

Every model in the catalog carries its provider price — input and output, in USD per 1M tokens (or per generated image / video / minute for media models). Nothing is hidden behind a proprietary "credit" unit: the number Synaplan bills against is the provider's own rate.

You can see it in three places:

• In the app — the model selector puts a cost badge (Free / Low / Mid / High) next to every option, computed from the real in/out prices of the models offered alongside it, so a cheaper alternative is visible at the moment you choose. The same badge sits on each answer, next to the model that produced it.
• On the Statistics page — every call is logged with its model, provider, tokens and computed cost, so you can trace consumption per day and per model.
• Over the API — GET /api/v1/config/models returns priceIn and priceOut per model, and admins get the full catalog with editable prices under System Config → AI Models.

On the hosted instance at web.synaplan.com, that same catalog is what the free and paid tiers meter against, so the price you read in the selector is the price you pay for.

Which models are the cheapest?

Prices span three orders of magnitude, so model choice matters more than anything else you can tune:

Self-hosting with Ollama removes the per-token cost entirely — you trade it for GPU capacity. A common setup routes everyday chat to a low-cost or local model and reserves a frontier model for the tasks that actually need it.

Does self-hosting cost anything?

Synaplan itself is Apache-2.0 licensed and free to run. Your only AI cost is what your chosen providers charge — and with Ollama on your own GPU, that can be zero. The cost tracking, budgets and markup machinery described in Hosting Platform is there for operators who resell capacity; it does nothing on a private install.

Docker & Development

How do I view logs?

docker compose logs -f backend     # Backend logs
docker compose logs -f frontend    # Frontend dev server
docker compose logs -f worker      # Background jobs (Messenger consumer)
docker compose logs -f centrifugo  # Realtime WebSocket gateway
docker compose logs -f             # All services

How do I restart a service?

docker compose restart backend
docker compose restart frontend

How do I reset the database?

docker compose down -v    # Removes all volumes (data)
docker compose up -d      # Fresh start with seed data

How do I run tests?

make test                          # All tests (backend + frontend)
make -C backend test               # Backend only (PHPUnit)
make -C frontend test              # Frontend only (Vitest)

How do I run linting and static analysis?

make lint                          # Backend + frontend lint
make -C backend phpstan            # PHP static analysis
docker compose exec -T frontend npm run check:types   # TypeScript check

How do I build the frontend for production?

make -C frontend build             # Build the Vue SPA
make -C frontend build-widget      # Build the embeddable widget

Qdrant & Vector Search

What is Qdrant used for?

Qdrant is a vector database that powers three features:

1. RAG Document Search — Semantic search over indexed documents
2. AI Memories — User profiling and long-term context
3. Feedback System — False-positive detection and learning

Do I need Qdrant?

No. Qdrant starts automatically with docker compose up -d, but Synaplan works fully without it. If Qdrant is unavailable, memories and vector search are simply disabled. MariaDB VECTOR can serve as an alternative for basic vector operations.

Common Issues

Project Structure

synaplan/
├── backend/          # Symfony 7 PHP API
│   ├── src/          # Controllers, Services, Repositories
│   ├── .env.example  # Configuration template
│   └── tests/        # PHPUnit tests
├── frontend/         # Vue 3 + TypeScript SPA
│   ├── src/          # Components, stores, services
│   └── tests/        # Vitest tests
├── docs/             # Internal documentation
├── _docker/          # Docker build configs
└── plugins/          # Installed plugins (synaads, synaform, …)

More Resources

• Architecture & Realtime — Service map, Redis, Centrifugo, clustering
• Plugins & Integrations — Synaads, Synaform 4.x, TTS, Synasort, Nextcloud, OpenCloud, ownCloud.online
• Widget Integration — Embed the chat widget on any website
• Outlook Add-in (Synamail) — Generally available Outlook add-in
• Code Examples — cURL, Node.js, PHP snippets
• GitHub: synaplan — Main repository
• GitHub: Synaads — AI marketing campaign plugin
• GitHub: Synaform — AI document-merge plugin (4.x)
• GitHub: synaplan-tts — Text-to-Speech service
• GitHub: synaplan-nextcloud — Nextcloud integration
• GitHub: synaplan-opencloud — OpenCloud / oCIS integration
• GitHub: synaplan-owncloud-online — ownCloud.online integration
• GitHub: synaplan-charts — Helm charts for Kubernetes
• All repositories — Everything we maintain and support