Getting Started¶

Everything you need to go from clone → running authenticated app in minutes.

Prerequisites¶

Docker is required — it runs MongoDB (app database), PostgreSQL (Keycloak user database), and Keycloak (identity provider). All three start with a single docker compose up.

Repo layout¶

mozaiks/
├── app/                        # Frontend app (Vite + React) — brand & customize this
│   ├── brand/public/           # brand.json, ui.json, navigation.json, auth.json, assets, fonts
│   ├── App.jsx                 # App shell (Keycloak auth built-in)
│   ├── main.jsx                # Entry point
│   └── vite.config.js          # Pre-wired — update proxy once backend is live
│
├── app.json                    # App name + API URL
│
├── chat-ui/src/                # UI library — do not modify
│   └── workflows/              # Workflow frontend component registry
│       └── HelloWorld/         # Example — copy for your own workflows
│
├── workflows/                  # Backend AG2 workflow definitions
│   └── HelloWorld/             # Example workflow — copy for your own
│
├── mozaiksai/                  # Runtime engine — do not modify
├── shared_app.py               # FastAPI server entry
├── run_server.py               # Start the server
├── requirements.txt            # Python dependencies
├── .env.example                # Secrets & config template (copy to .env)
│
└── infra/
    ├── compose/                # Docker Compose (Mongo + Keycloak + Postgres + app)
    │   ├── docker-compose.yml      # Development (hot-reload)
    │   └── docker-compose.prod.yml # Production
    └── keycloak/
        └── realm-export.json   # Auto-imported Keycloak realm config

Step 1 — Configure .env¶

# Windows
Copy-Item .env.example .env

# macOS / Linux
cp .env.example .env

Open .env and set your OpenAI API key:

OPENAI_API_KEY=sk-...

That's the only required edit. Everything else has working defaults:

See .env.example for the full list with inline comments.

Step 2 — Start the databases + auth¶

docker compose -f infra/compose/docker-compose.yml up -d

This starts three services automatically:

Verify databases are healthy¶

docker compose -f infra/compose/docker-compose.yml ps

All services should show healthy. Keycloak takes ~30 seconds on first boot.

Keycloak admin console¶

Once healthy, open http://localhost:8080/admin:

• Username: admin
• Password: admin

From here you can manage users, roles, and login settings. The mozaiks realm is pre-configured with:

Step 3 — Start the app¶

# Create a virtual environment (first time only)
python -m venv .venv

# Activate it
# Windows:
.\.venv\Scripts\Activate.ps1
# macOS / Linux:
source .venv/bin/activate

# Install Python deps
pip install -r requirements.txt

# Start backend (http://localhost:8000)
python run_server.py

# Start frontend (http://localhost:5173)
cd app
npm install   # first time only
npm run dev

docker compose -f infra/compose/docker-compose.yml up --build

cd app
npm install   # first time only
npm run dev

Step 4 — Verify¶

First login¶

When you open the frontend, you'll be redirected to Keycloak's login page. Use the test user:

• Username: dev
• Password: dev

After login, you're redirected back to the app with a valid JWT session.

Step 5 — Configure app.json¶

{
  "appName": "My App",
  "appId": "my-app",
  "defaultWorkflow": "HelloWorld",
  "defaultUserId": "local-dev-user",
  "apiUrl": "http://localhost:8000",
  "wsUrl": "ws://localhost:8000"
}

appName appears in the browser tab. Set apiUrl and wsUrl to your deployed backend URL when going to production.

Database reference¶

MongoDB (your app data)¶

No migrations needed — collections are created automatically on first use. To inspect data, connect with any MongoDB client:

mongodb://localhost:27017/MozaiksAI

PostgreSQL (Keycloak's data)¶

You never interact with this directly. Keycloak manages its own schema (100+ tables for users, realms, sessions, credentials, etc.). It's internal to the keycloak-db container and not exposed on a host port.

To reset Keycloak to factory defaults:

docker compose -f infra/compose/docker-compose.yml down -v
docker compose -f infra/compose/docker-compose.yml up -d

This re-creates all volumes and re-imports the realm from realm-export.json.

Troubleshooting¶

Next steps¶