Get started on GENIE.AI

Welcome to GENIE.AI

Mon, 01 Jan 0001 00:00:00 +0000

What GENIE.AI is

GENIE.AI is an open-source retrieval-augmented-generation framework built for the public sector. It bundles a multilingual chat UI, a self-hosted RAG pipeline, an admin dashboard, an identity layer, and a configurable observability stack — so a government or NGO can deploy a sovereign AI assistant without sending a single query to a third-party model API.

The pipeline is built on top of OPEA, the Open Platform for Enterprise AI, and integrates with the Digital Public Goods ecosystem.

Quickstart: User — chat in 10 minutes

Mon, 01 Jan 0001 00:00:00 +0000

Goal

In about 10 minutes you will have signed in to your organization’s GENIE.AI assistant, asked a real question, inspected the sources behind the answer, switched the chat to your preferred language, and submitted feedback on the response.

You only need a browser — GENIE.AI runs entirely in the cloud, there is nothing to install.

Prerequisites

The chat URL your organization gave you (for example https://genie.example.gov).
A valid SSO account. GENIE.AI delegates authentication to Keycloak, so the same username and password you use for other internal tools will work — including brokered identity providers (Microsoft Entra ID, Google Workspace, Okta) if your administrator has wired them up.
A modern browser with cookies enabled and JavaScript turned on (Chrome, Firefox, Edge, or Safari, current version).
Pop-ups allowed for the chat URL and the Keycloak URL (the sign-in page opens in a redirect you must allow on first visit).

Open the chat URL in your browser. The first time you visit, a splash screen shows for a few seconds, then the app loads.
You are redirected to your organization’s Keycloak login page. Enter your corporate credentials (or pick the federated identity provider your admin enabled — Google, Microsoft, Okta, etc.).
After successful authentication, you are redirected back to the chat. The user icon in the top-right corner is now active, indicating you are signed in.
If your account has the admin role, the Administration icon (grid) appears in the navbar. Regular users do not see this icon.

Verify — type a single character in the chat box and delete it. The placeholder text “Type your query here…” reappears. You are now signed in.

Quickstart: Deployer — single-host Compose deployment

Mon, 01 Jan 0001 00:00:00 +0000

Goal

Stand up a production-ready GENIE.AI stack on a single Linux host with docker compose. After this guide the chat UI is reachable at https://<your-host> and:

/api/health returns 200 OK,
an admin user can sign in via Keycloak and chat against a working RAG pipeline (when the OPEA profile is enabled),
/api/admin/system-health shows all dependencies green,
/grafana/ (when the observability profile is enabled) exposes logs, metrics, and traces.

For multi-node production deployment (Swarm, remote GPU, Ansible), skip ahead to Docker Swarm Setup.

Quickstart: Developer — ship a service change in 30 minutes

Mon, 01 Jan 0001 00:00:00 +0000

Goal

In 30 minutes you will have the GENIE.AI stack running in Docker Compose, edited one source file in the service you care about, rebuilt only that service’s image, hit the change through NGINX to confirm it works, and run the service’s test suite green inside the running container. No GPU services, no OPEA stack required.

The dev loop is service-agnostic — the same five commands work whether you touched components/gov-chat-backend (Node.js), gov-chat-frontend (Vue), gov-chat-document-repository, or genie-ai-overlay/dataprep (Python). The only thing that changes is which <service> name you pass to docker compose. Path B at the end covers the rarer case of adding a brand-new route.

Quickstart: Contributor — open your first MR in 10 minutes

Mon, 01 Jan 0001 00:00:00 +0000

Goal

In 10 minutes you will have forked the repo, opened a merge request that passes CI on a one-line change, and assigned it to a maintainer.

Prerequisites

A GitLab account (sign up at opensource.unicc.org).
git 2.40+ locally.
glab CLI authenticated (glab auth login --hostname opensource.unicc.org).
The repository cloned (see the deployer quickstart, step 1).

The contributor workflow is trunk-based with feature branches: every change lands through a merge request on the upstream un/itu/genie-ai project. Direct pushes to main or release/* are rejected by branch protection. See Contribute → How to open a MR.

Step 1 — Fork and clone

If you don’t already have a fork:

Concepts in 5 minutes

Mon, 01 Jan 0001 00:00:00 +0000

GENIE.AI at a glance

flowchart LR
 U[User] --> NG[NGINX<br/>TLS termination]
 NG --> FE[Frontend SPA<br/>Vue 3 / Flutter<br/>port 8090]
 NG --> KG[Kong<br/>API gateway<br/>CORS / rate limit]
 KG --> BE[Backend BFF<br/>Node.js]
 KG --> DR[Document Repository]
 BE --> KC[Keycloak<br/>OIDC]
 BE --> CQ[ChatQnA<br/>OPEA orchestrator]
 CQ --> EM[Embedding wrapper<br/>:6000]
 EM --> TEI[TEI]
 CQ --> RT[Retriever<br/>ArangoDB]
 CQ --> RR[Reranker<br/>TEI]
 CQ --> LM[vLLM<br/>LLM]
 DR --> ADB[(ArangoDB<br/>vectors + graph + docs)]
 RT --> ADB
 DP[Dataprep<br/>PDF / Word / etc.] --> ADB
 DR --> DP

Two paths converge at NGINX: the SPA (Vue / Flutter, served on location / via the frontend container port 8090) and the API (Kong proxies /api/* and /auth/* to the backend BFF). One request then travels: User → Nginx → Kong → Backend → ChatQnA → {Embedding wrapper → TEI, Retriever, Reranker, vLLM} → streamed response back. Documents are ingested through the Document Repository / Dataprep path into ArangoDB.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

The 12 most common questions

1. Do I need a GPU?

For a demo / pilot with 100s of documents and a handful of users, no — the backend works without OPEA, but the chat will say “I cannot answer” because the LLM is not running. For production, yes — a single 24 GB GPU (RTX 6000 ADA or A40) is enough for embedding + reranking + a 7B-chat LLM. The minimum for a 7B model is 16 GB. See Deploy → GPU profiles.

Where to next?

Mon, 01 Jan 0001 00:00:00 +0000

Pick the persona you came in as

I am an end user

You are done — sign in and chat. Two pages are worth bookmarking:

Glossary — for when the docs use an acronym you don’t recognise.
FAQ — for the 12 questions new users ask.

I am a deployer

You have a running stack. The next page to read is:

Deploy → Choose your deployment mode — promotes you from local Compose to production.
Deploy → Configuration reference — the single source of truth for every env-var.

Then move into day-to-day:

Get started on GENIE.AI

Welcome to GENIE.AI

What GENIE.AI is

Quickstart: User — chat in 10 minutes

Goal

Prerequisites

Step 1 — Open the chat and sign in

Quickstart: Deployer — single-host Compose deployment

Goal

Quickstart: Developer — ship a service change in 30 minutes

Goal

Quickstart: Contributor — open your first MR in 10 minutes

Goal

Prerequisites

Step 1 — Fork and clone

Concepts in 5 minutes

GENIE.AI at a glance

FAQ

The 12 most common questions

1. Do I need a GPU?

Where to next?

Pick the persona you came in as

I am an end user

I am a deployer