Installation

Boidra Platform has two processes: a backend (OTLP ingest + data API) and the React dashboard (the UI). In development you run both; in production the backend serves the built dashboard from a single origin.

The backend stores spans and app state in a relational database:

• Non-production (local, dev, staging) → PostgreSQL
• Production on SAP BTP → SAP HANA Cloud

The schema is identical across both; only the connection target changes.

Prerequisites

• Node.js 18+ and npm
• A PostgreSQL instance for local/non-production (a local install, a Docker container, or a hosted dev database)
• For production: an SAP HANA Cloud instance in your SAP BTP account

Local setup

Clone the repository and note its two app folders (names are illustrative — use whatever your checkout calls them):

• the backend folder — the Express ingest + API server
• the dashboard folder — the Vite/React front end

1. Provide a Postgres database

Any Postgres 14+ works. The quickest local option is Docker:

docker run --name boidtelemetry-db \
  -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=boidtelemetry \
  -p 5432:5432 -d postgres:16

Point the backend at it with a connection string:

# non-production → Postgres
export DATABASE_URL="postgres://postgres:postgres@localhost:5432/boidtelemetry"

The backend creates its tables on first start — no manual migration step.

2. Start the backend (port 3010)

cd <backend-folder>
npm install
npm run server        # API + OTLP ingest on http://localhost:3010

Want demo data to explore the UI before you wire up real telemetry?

npm run seed          # insert mock spans (safe to re-run)

3. Start the dashboard (port 5173)

cd <dashboard-folder>
npm install
npm run dev           # http://localhost:5173

Open http://localhost:5173.

The Vite dev server proxies these paths to the backend on :3010, so the app calls same-origin URLs exactly like production:

Path	Purpose
/api	Dashboard data API
/otel	OTLP trace ingest
/aicore	SAP AI Core proxy (LLM)

Reach it from other devices

To open the dashboard from another machine on your network, start the dev server bound to all interfaces and browse to http://<your-machine-ip>:5173. The API stays same-origin — it's proxied through the dev server, so the backend doesn't need to be exposed.

Production build (SAP BTP + HANA)

Point the backend at SAP HANA Cloud instead of Postgres:

# production → HANA (from your HANA Cloud service key / BTP binding)
export DATABASE_URL="hana://<user>:<password>@<host>:<port>"

On BTP the binding is normally supplied by the bound HANA service instance rather than a hand-set variable. Then build the dashboard and let the backend serve it:

cd <dashboard-folder>
npm run build         # emits static assets the backend serves with an SPA fallback

cd <backend-folder>
npm run start:prod    # single origin: API + UI + ingest

Because the build is static assets served by the existing backend, the whole app runs from a single origin with no separate web server.

Configuration

Setting	Where	Purpose
DATABASE_URL	env var (or HANA binding)	Postgres (non-prod) or HANA (prod) connection.
PORT	env var	Backend port (default 3010).
XSUAA	BTP service binding	Sign-in, roles and approvals. Without it the app runs in local-development mode.
Destination service	BTP service binding	How the platform reaches SAP AI Core.
AI Core destination + resource group	dashboard Settings page	Used by Judges, Reporting, and Detect Issues.
Model price table	dashboard Settings page	Cost per agent, model and use case.
Judge prompts	dashboard Settings page	What the LLM judges check.
Environments	dashboard Landscape page	Dev → QA → Prod and production guardrails.

Nothing beyond the database connection is required just to ingest and view traces — the AI Core settings only power the LLM-assisted features.

Administration

Connecting SAP AI Core, XSUAA roles, Joule, prices and environments is covered step by step in Admin setup: connect SAP services.

Next

• Admin setup — connect AI Core, XSUAA, Joule and more.
• Quickstart — send your first trace.
• Connect AI assets — real telemetry from your agents.