Developer Onboarding

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Playground workspace: After completing setup, run make playground-seed to provision sample data for the interactive tutorials.

Prerequisites

Quick Start

1. Clone and install

git clone https://github.com/vdoganAnalytixPower/orqestra.git
cd Orqestra
make install

Expected output: pnpm installs portal dependencies, uv syncs control-plane and runtime-gateway Python environments.

2. Generate local credentials and start infrastructure

make bootstrap
make dev-infra

make bootstrap creates or reuses the private, ignored .tools/local-compose bundle. It is the only source of local database, Redis, object-store, identity, and service-authority credentials; do not copy .env.example or export known defaults. The bundle is reused across restarts and a reset/recovery is required before rotating credentials while persistent volumes exist.

A bundle generated before per-role service-credential signing keys were introduced needs a one-time migration before make dev will start: run scripts/bootstrap-local-compose.sh add-role-signing-keys --root "$PWD" once. It adds the new key files and compose.env entries in place (refusing any other drift) and is a no-op if the bundle is already migrated. A fresh bundle created by make bootstrap already includes the seven keys and needs no migration. A bundle with the dedicated runtime-gateway signing key and the older two-key gateway verifier set is upgraded automatically by make bootstrap or make dev: it reuses the existing load-gate public key and preserves the bundle generation. Other bundle drift still fails closed; a bundle that predates the dedicated runtime-gateway signing key requires an explicit reset.

Expected output: PostgreSQL (5432), PgBouncer (6432), four Redis services (6379-6382), MinIO (9000/9001) containers start on loopback.

3. Initialize the database

make db-upgrade
make db-seed

Expected output: Alembic applies the migrations and seed data loads.

Pre-live reset/reseed recovery

Migration 255 adds the required server-owned release-origin row and refuses to run when release_record already contains rows. It does not delete or infer origins. On a disposable local database, reset the Docker volumes before retrying. This is local-only and permanently deletes the local Postgres, Vault, and MinIO volumes; never run it against shared or production data:

printf 'yes\n' | make reset
make dev

If you only need infrastructure, use make dev-infra, then rerun make db-upgrade and make db-seed. If the database is not disposable, stop and use the migration’s bounded preflight error to coordinate an explicit data migration; do not bypass the check.

4. Run services

Option A — Docker (all services):

make dev

Option B — Local development (separate terminals):

Generate and load the protected local bundle before starting host-native processes. The bundle supplies the database, Redis, object-store, session, and service-signing values; do not copy .env.example or rely on repository defaults.

make bootstrap
eval "$(scripts/bootstrap-local-compose.sh host-env --root "$PWD")"
 
# Terminal 1: control-plane with the optional Estate surface
cd services/control-plane && uv run uvicorn orqestra_composition.app:app --reload --app-dir src --port 8000
 
# Terminal 2: runtime-gateway
cd services/runtime-gateway && uv run uvicorn orqestra_runtime_gateway.main:app --reload --app-dir src --port 8001
 
# Terminal 3: portal
cd apps/portal && pnpm dev
 
# Terminal 4: docs
cd apps/docs && pnpm dev

The control-plane composition includes the optional Estate overview. To run the core-only control plane without Estate routes, use:

cd services/control-plane && uv run uvicorn orqestra_control_plane.main:app --reload --app-dir src --port 8000

Expected output: Control-plane at http://localhost:8000/docs , runtime-gateway at http://localhost:8001/healthz , portal at http://localhost:3000 , docs at http://localhost:3002 

5. Verify

curl http://localhost:8000/healthz
# {"status": "ok"}
 
make check
# All quality gates pass

Environment Variables

Run make bootstrap in the repo root. Host-side Make targets source the generated bundle automatically; direct service processes must source .tools/local-compose/compose.env explicitly as shown above. Key variables:

Docker Compose Profiles

Different profiles activate different services and require different env vars:

• default (no --profile flag): PostgreSQL 17 with pgvector + PgBouncer (transaction-mode pooler), four typed Redis services (queue / cache / coordination / signals), MinIO. Requires ORQESTRA_POSTGRES_DSN (app traffic via PgBouncer), ORQESTRA_POSTGRES_DSN_DIRECT (admin/migration via direct Postgres), and the four ORQESTRA_REDIS_*_URL variables (defaults point at the bundled compose services).
• full: All default services plus control-plane, retrieval-service, LiteLLM, runtime-gateway, and portal. Additionally requires CONTROL_PLANE_URL, RUNTIME_GATEWAY_URL, and RETRIEVAL_SERVICE_URL for portal proxying and system-health readiness checks. NEXT_PUBLIC_GRAFANA_URL and NEXT_PUBLIC_JAEGER_URL control Monitoring drilldown links when the monitoring profile is also running. OPENAI_API_KEY is optional and only needed if you want a LiteLLM-routed model (see Governed Providers) to work.
• auth: Default services plus Keycloak and OpenLDAP. Auth-related env vars apply.
• llm: Default services plus LiteLLM. Requires LITELLM_MASTER_KEY. OPENAI_API_KEY remains optional.

Project Layout

Orqestra/
  apps/portal/           # Next.js operator and consumer portal (pnpm)
  services/
    control-plane/       # FastAPI central API service (uv)
    runtime-gateway/     # FastAPI execution gateway (uv)
  packages/contracts/    # Shared type contracts
  infrastructure/local/  # Docker Compose and local infra config
  docs/                  # Architecture, ADRs, reviews
  tests/                 # Cross-service test suites

Common Workflows

Troubleshooting

• Port conflict: Check for existing services on 5432, 6379, 3000, 8000 (lsof -i :<port>).
• uv not found: Install from https://docs.astral.sh/uv/ 
• pnpm not found: npm install -g pnpm
• Docker permission denied: Ensure the Docker daemon is running and your user has access.
• Database connection refused: Ensure make dev-infra is running and PostgreSQL is healthy (docker compose ps).
• Portal shows “fetch failed”: Ensure control-plane is running at the URL specified in CONTROL_PLANE_URL.

Further Reading

• DEVELOPMENT.md  — development conventions and command ownership
• Architecture docs  — architecture documentation index
• Project brief  — project vision and goals