Installation & Configuration Guide

This is the canonical end-to-end install procedure for GENIE.AI. Choose the deployment model that matches your case before reading on — each model has a dedicated sibling guide with the platform-specific mechanics, while this doc is the universal prerequisite + configuration + verification backbone:

GPU profiles (T4 16 GB / RTX 6000 24 GB / A40 48 GB / H100) layer on top of any of the above via the env.t4 / env.rtx6000 overrides — see GPU Deployment.

Goal

Read this doc top-to-bottom on first install to learn every prerequisite, the environment-variable reference, and the post-deploy verification checklist; afterwards use the cross-linked deployer guides above for incremental changes. Provision a working GENIE.AI stack (NGINX → Kong → backend → OPEA services → ArangoDB) in one sitting, verify every service is healthy, and position yourself for knowledge-base population.

For data-curation guidance (which this guide does not cover) see Content Guidance and Labelling Taxonomy.

For mobile-app build and distribution see Mobile Deployment Guide.

Glossary

Architecture at a glance

flowchart LR
    User([End user]) -->|HTTPS 443| NGINX
    NGINX --> Kong[Kong API gateway]
    Kong -->|OIDC| Keycloak[Keycloak IdP]
    Kong -->|/api| Backend[Node.js BFF]
    Kong -->|/api| DocRepo[Document repository]
    Backend --> Arango[(ArangoDB<br/>graphs + vectors)]
    DocRepo --> Arango
    DocRepo --> ClamAV[ClamAV]
    DocRepo --> Dataprep
    Dataprep -->|LLM labeling| vLLM
    Dataprep --> Embedding[TEI Embedding]
    Backend --> ChatQnA[ChatQnA orchestrator]
    ChatQnA --> Retriever
    Retriever --> Arango
    ChatQnA --> Reranker[TEI Reranker]
    ChatQnA --> vLLM[vLLM LLM]
    ChatQnA -.optional streaming translation.-> vLLMTrans[vLLM Translation]
    Backend --> Redis[(Redis cache)]

NGINX is the only host-published port (80/443); everything else stays on the internal Docker network. The observability profile adds VictoriaMetrics, VictoriaTraces, tempo-proxy, and Grafana on top of the always-on OTel Collector

• VictoriaLogs log substrate.

Step 1: Hardware requirements

GENIE.AI needs significant computational resources for AI model inference. The solution will not run reliably without the resources below.

For the GPU-specific layer, see GPU Deployment.

Step 2: Software prerequisites

• Ubuntu Linux 22.04 — primary tested platform. Other Debian-based distributions work but may need package-name adjustments.
• Docker & Docker Swarm — required for orchestrating the containerized services. See Step 3.
• NVIDIA Drivers & CUDA — required only if using GPU services (vLLM, TEI). See GPU Deployment and NVIDIA A40 Install Guide.
• Node.js 22+ — required for JavaScript tooling. Docker images use node:22; CI lint+test jobs run on node:20-alpine.

Step 3: Install Docker on every host

3a. Update and install prerequisites

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

3b. Add Docker’s official GPG key

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

3c. Add the Docker repository

Note: Use https://download.docker.com/linux/ubuntu on Ubuntu (not /linux/debian) — the repo URL must match your distribution.

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

3d. Install Docker Engine

This also removes conflicting older versions like docker.io if present:

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
                        docker-buildx-plugin docker-compose-plugin

3e. Start and enable Docker

If the installer does not start the daemon automatically:

sudo systemctl start docker
sudo systemctl enable docker

3f. Grant your user Docker permissions

sudo usermod -aG docker $USER
newgrp docker

3g. Verify

docker run hello-world

Step 4: Install Node.js 22+

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
node -v   # v22.x
npm -v    # 10.x

Step 5: Clone the repository

git clone https://opensource.unicc.org/un/itu/genie-ai.git
cd genie-ai

If you plan to commit changes, clone from your fork; check with the administrator about which branch is current. The canonical mirror is at https://opensource.unicc.org/un/itu/genie-ai/.

Step 6: Environment configuration

cp env .env

The env template is the single source of truth for configuration. Three templates ship in the repository:

6a. Generate strong passwords

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Use this to generate every *_PASSWORD / *_SECRET value. All *_PASSWORD / *_SECRET variables in the .env file are required.

6b. LLM prompt customization (optional)

GENIE.AI uses a two-tier priority for LLM prompts:

1. ENV VAR (highest): override in .env for deployment-specific customization.
2. DEFAULT (lowest): built-in prompts in Python code (works out-of-the-box).

To customize, add the variable to .env. To change built-in defaults, edit the Python source listed above.

6c. Minimum required variables (TL;DR)

This is the short list a first-time deployer MUST set before running docker stack deploy. Section 6d below is the full reference (200+ vars with defaults, descriptions, and qualifications).

Generate each secret with: python3 -c "import secrets; print(secrets.token_urlsafe(32))"

6d. Required environment variables

The full variable reference follows. Variables not listed here use compose defaults.

Legend: Required (yes) = must be set in .env before first deploy. Sample <set-me> = replace with your own value; do not ship the example value in production.

General & proxy settings

Kong (API gateway) and PostgreSQL

Frontend (Vue.js)

Backend (Node.js)

Translation & Redis cache

ArangoDB (knowledge base)

Note: All GENIE.AI services (backend, frontend, document-repository, OPEA services) share a single ArangoDB database. The default name is genie-ai.

Document repository & virus scanning

OPEA & ChatQnA orchestration

Note: The DATAPREP_SERVICE_IP and DATAPREP_SERVICE_PORT env vars are consumed by the disabled chatqna-xeon-nginx-server service (replicas: 0); the active dataprep URL is http://dataprep-arango-service:5000 referenced from chatqna env. The guardrail service is part of the opea profile but is also disabled by default (replicas: 0).

Dataprep

Retriever

For tuning guidance see RAG → Retriever Configuration and the Retriever overview in the source code.

Network & external services

Keycloak

Observability (optional — ENABLE_OBSERVABILITY=1)

Step 7: Initialize Swarm and deploy

flowchart LR
    A[Step 6: edit .env] --> B[docker swarm init]
    B --> C[Label nodes<br/>gateway / genieai / gpu]
    C --> D[docker compose config<br/>resolves $VAR from .env]
    D --> E{Profiles?}
    E -->|opea| F[compose config picks up OPEA]
    E -->|gpu-models| G[compose config picks up GPU]
    E -->|observability| H[compose config picks up obs]
    F --> I[docker stack deploy]
    G --> I
    H --> I
    I --> J[Stack healthy?]
    J -->|no| K[Step 8 troubleshoot]
    J -->|yes| L[Step 9 KB population]

7a. Initialize Swarm

docker swarm init
docker node update --label-add gateway=true $(hostname)
docker node update --label-add genieai=true $(hostname)
docker node update --label-add gpu=true $(hostname)

For multi-node Swarm see Docker Swarm Setup → Step 2.

7b. Pre-resolve env into a flat YAML

Important: docker stack deploy does not substitute ${VAR} references from environment variables. Always run docker compose config first to produce a flat YAML, then deploy the resolved file.

set -a && source .env && set +a
docker compose config > docker-compose.resolved.yaml

With GPU-specific overrides (T4):

set -a && source .env && source env.t4 && set +a
docker compose config > docker-compose.resolved.yaml

7c. Deploy the stack

docker stack deploy -c docker-compose.resolved.yaml genieai

For a docker compose up single-host dev workflow see Docker Compose Setup → Step 6.

Step 8: Verify deployment is healthy

# Services should be 1/1 with (healthy)
docker service ls

# Kong configured
docker service logs genieai_kong-config --tail 20
# Look for: "Configuration restored successfully"

# Keycloak realm applied
docker service logs genieai_keycloak-config --tail 10

# Smoke tests
curl -sk https://localhost/api/health
curl -sk https://localhost/

GPU stack confirmation (with --profile opea --profile gpu-models):

docker service logs genieai_vllm -f | grep 'Application startup complete'
curl -sk https://localhost/api/health | python3 -m json.tool

Step 9: Knowledge-base population

The framework is empty until you ingest documents. The pipeline is:

1. Create the label taxonomy (categories + services) in the Admin Dashboard → Knowledge Hierarchy tab. For design principles see Labelling Taxonomy.
2. Upload documents through the Admin Dashboard → Document Management tab, or via the document-repository upload API. Supported formats and known issues are documented in Content Guidance.
3. Dataprep ingests each document: extracts text, splits into chunks, runs LLM-based labeling (or embedding / BM25 based on LABELING_STRATEGY), and stores everything in ArangoDB. Progress and failures land in the ingestion_log collection — visible in the Admin Dashboard.
4. Track per-chunk progress with the Ingestion Log (see also Ingestion pipeline).

Step 10: First-time user accounts

The genie-admin user is provisioned automatically during deployment by configs/keycloak/genie-realm.yaml. No script is required.

• Admin console: https://<NGINX_PUBLIC_DOMAIN>/auth/admin/ (username admin, password from KEYCLOAK_ADMIN_PASSWORD)
• GENIE realm admin: username genie-admin (configurable via GENIE_ADMIN_USERNAME), password from GENIE_ADMIN_PASSWORD, has the admin realm role

To change the admin password, log in to the Keycloak admin console, switch to the genie realm, then Users → genie-admin → Credentials → Set password.

For full user-management instructions (CRUD, role assignment, security considerations) see Keycloak Admin Operations Guide.

Step 11: Common post-deploy configuration

11a. NGINX

You do not need to configure NGINX manually — it auto-renders from default.conf.template at startup. Common customization knobs:

For custom TLS certificates (production / non-Let’s-Encrypt), drop the cert + key into the nginx_secrets Docker volume and restart genieai_nginx. The entrypoint detects the mounted files at startup and falls back to a self-signed cert only if none are mounted. See Security Hardening.

11b. Kong

Kong database migrations run automatically as part of stack deploy. Routes and plugins are applied by the kong-config one-shot service after Kong becomes healthy — no manual configuration is needed for the default routes.

• Custom routes → add YAML to api-gateway-solution/new-config/ (the restore script picks them up automatically).
• Custom plugins → enable via the Kong admin API or add to the declarative config alongside routes.
• Trusted proxies → KONG_TRUSTED_IPS (default 172.16.0.0/12); expand when Kong sits behind an additional reverse proxy.
• Tracing → KONG_TRACING_INSTRUMENTATIONS and KONG_TRACING_SAMPLING_RATE (observability profile).

For full Kong operations (route CRUD, plugin config, RBAC) see Docker Swarm Setup → Kong trusted IPs.

11c. Keycloak realm

The genie realm (clients, roles, mappers, the genie-admin user) is applied by keycloak-config. Common post-deploy knobs:

For full user/realm management (CRUD, role assignment, security considerations) see Keycloak Admin Operations Guide. For external IdPs (Google, Microsoft, SAML/OIDC) see External IdP Integration Guide.

11d. Branding & dashboard

To make the deployment look like your institution rather than upstream GENIE.AI, see Branding Customization and Admin dashboard customization to set the per-institution banner, splash image, logo, and dashboard tiles. Both live under the deployment’s flavors/<name>/ directory; see Deployment flavors for the full flavor layout (image overrides, locale whitelist, mobile OIDC client).

Troubleshooting

For environment-specific troubleshooting see:

• Docker Compose Setup → Troubleshooting
• Docker Swarm Setup → Troubleshooting
• GPU Deployment → Troubleshooting

Common first-deploy failures (deployer-oriented, not environment-specific):

Next steps

You now have GENIE.AI running. Continue with:

• Post-deploy checklist — first user, first knowledge base
• Knowledge Base — content design, labelling, ingestion
• Operations — backup, troubleshooting, monitoring
• Mobile Deployment Guide — building and distributing the mobile app