Developer FAQ

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

Installation

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?

Mode Command Size Best For
Standard docker compose up -d ~9 GB Full features including local AI (Ollama)
Minimal docker compose -f docker-compose-minimal.yml up -d ~5 GB Cloud AI only (no Ollama)

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

What are the default login credentials?

Email Password Level
[email protected] admin123 ADMIN
[email protected] demo123 PRO
[email protected] test123 NEW (unverified)

What services are available after startup?

Service URL
App (Vue SPA) http://localhost:5173
API (Symfony) http://localhost:8000
API Docs (Swagger) http://localhost:8000/api/doc
phpMyAdmin http://localhost:8082
MailHog (email testing) http://localhost:8025

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 all Synaplan configuration lives. It controls database connections, AI provider API keys, email settings, authentication, and more.

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?

Section Key Variables Purpose
Application APP_SECRET, FRONTEND_URL, APP_URL Core app settings, URLs
AI Services OLLAMA_BASE_URL, OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, GOOGLE_GEMINI_API_KEY AI provider connections
Database DATABASE_WRITE_URL, DATABASE_READ_URL MariaDB connection strings
Email MAILER_DSN, APP_SENDER_EMAIL Outgoing email transport
Auth reCAPTCHA, OAuth (Google/GitHub), OIDC Login and registration settings
Channels WhatsApp, Gmail External messaging integrations
Redis REDIS_DSN, LOCK_DSN Cache, sessions, locks, job queues (required)
Realtime REALTIME_ENABLED, REALTIME_TOKEN_SECRET, REALTIME_API_KEY Centrifugo WebSocket gateway for live support
Vector DB QDRANT_URL Qdrant vector database for RAG and memories
Payments STRIPE_* Stripe subscription management

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

How do I add an OpenAI key?

Edit backend/.env and set:

OPENAI_API_KEY=sk-your-openai-key-here

Then restart the backend:

docker compose restart backend

The GPT-5.5 / 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

Restart the backend. Claude Opus 4.8 / 4.7 / 4.6, Claude Sonnet 4.6, and Claude Haiku 4.5 will appear (chat + vision).

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 Whisper Large v3 transcription.

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, the Gemini 2.5 family, plus Google's media models (Imagen 4, Nano Banana, Veo 3.1 video).

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.

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

Problem Cause Solution
AUTH_FAILED from API Wrong auth header format Use X-API-Key: ... header, not Authorization: Bearer
Models not appearing Missing API key Add the provider's key to backend/.env and restart
Ollama models slow to start First download in progress Wait for the model to download, check logs with docker compose logs ollama
Frontend not loading Vite dev server not ready Wait ~30 seconds, or check docker compose logs frontend
Database connection refused MariaDB not yet started Wait for all services: docker compose up -d && sleep 10
Widget CORS errors Cross-origin not configured Widget handles CORS automatically; check your APP_URL matches the actual host
Background jobs never finish Worker not running Check docker compose logs worker — it must show messenger:consume activity
Live takeover / typing not working Realtime layer unavailable Check docker compose logs centrifugo and docker compose exec redis redis-cli ping; in production replace the changeme_* realtime secrets (token minting is refused otherwise)
/api/health returns 503 Redis unreachable Redis is mandatory; verify the redis container is up and REDIS_DSN is correct

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