01 / Getting started

Getting Started

On this page 7

We produce AI freedom. Chat, knowledge, media and agents — on a machine you control. Apache-2.0. Self-hosted is the same software as web.synaplan.com.

This page is the short path to a first answer. Pitfalls and optional services are in Quickstart & Self-Hosting.

You need: Docker + Docker Compose v2, Git, 8 GB RAM, and about 4 GB of disk. No AI weights are downloaded unless you ask. File work and spoken answers start with the stack.


Clone and start#

shell
git clone https://github.com/metadist/synaplan.git
cd synaplan
make up

Open the status screen#

Open http://localhost:5173 immediately. It lists every boot step — database, backend, interface — then becomes the app when it is ready. First start: 5–15 minutes on a cold cache, about 2 minutes warm. Later starts: seconds.

make up binds that page before the rest of the images finish pulling. docker compose up -d starts the same stack; :5173 stays quiet until those pulls finish.

The same notes are in the terminal:

shell
docker compose logs -f startup-notes

It prints READY when the app answers.

Sign in and add a key#

  1. Log in as [email protected] / admin123.
  2. You land in chat. Above the input, a note says your first message starts the Synaplan Demo (no API key — 40 messages/day for 14 days via web.synaplan.com). The same note says where that message will go. Type a message and send it. Prefer your own AI? Use Set up Ollama or add your own key right there (local Ollama, your own key, free: Groq). You do not edit a config file for that.

Closed network#

Leave this off when everyone uses http://127.0.0.1:8000 or a public name that already has HTTPS.

When the network has no route to the public internet, chat needs https://<address>/. From the checkout:

shell
cp deploy/selfhost.env.example deploy/.env
deploy/scripts/local-tls.sh 10.0.0.15

Replace 10.0.0.15 with the address people will type. Full steps: Local network.


The first-run wizard, in short#

  • The first-run screen is the setup. An empty install blocks chat with a single Open AI provider setup button. The same cards live on Operate → AI infrastructure → Models & keys (/admin/setup) later.
  • Tested before it's saved. The key is validated against the live provider API, so a typo fails immediately instead of at your first chat.
  • Encrypted at rest. Keys live encrypted in your own database, not in a plaintext file on disk.
  • Active instantly. No restart and no rebuild — the next message already uses the new key.
  • .env still works. Keys already in backend/.env are imported into the encrypted store on first use.

No cloud key at all? Local AI is an opt-in Compose profile. COMPOSE_PROFILES=local-ai make up adds Ollama with the bge-m3 embedding model (~1 GB) for document search; COMPOSE_PROFILES=local-ai ENABLE_LOCAL_GPT_OSS=true make up also pulls a local chat model (gpt-oss:20b, ~14 GB — GPU or a strong CPU recommended). Chat begins working when the download finishes; the status screen shows the progress.


Default logins (development stack)#

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

These seeded accounts exist in the local development stack only. A production install creates its own first administrator — see Production Deployment.


Where to go next#

Goal Page
Understand what the 14-day onboarding Demo sends and includes Synaplan Demo
Get a free or paid API key from Groq, Cerebras, Gemini, Mistral, OpenAI or Anthropic Get your own AI keys
Run models locally on your own hardware with Ollama Local AI (Ollama)
Understand install options and avoid pitfalls Quickstart & Self-Hosting
Run it on a real server Production Deployment
Let the assistant run short file work (Python / Node) Run the compute sidecar
Learn the day-to-day features Using Synaplan
Put a chat widget on your website Widget Integration
Connect Outlook, WhatsApp, Telegram, clouds and more WhatsApp, Telegram & Email
Manage providers, users and models Administration