GitHub

Quickstart

Get Operyn running locally and send your first events in under 5 minutes.

Prerequisites

  • Bun >= 1.3.10
  • Docker + Docker Compose
  • Node.js >= 20 (for tooling compatibility)

1. Clone and Install

git clone https://github.com/your-org/operyn.git
cd operyn
bun install

2. Configure Environment

bun run setup

Running setup creates your .env file from the example and establishes a symbolic link to it within apps/dashboard, ensuring environment variables are synchronized across the entire monorepo for local development.

Minimum required for the dashboard sign-in (Better Auth):

  • BETTER_AUTH_SECRET (must be set; use a long random string)
  • BETTER_AUTH_URL (e.g. http://localhost:3000)
  • BETTER_AUTH_TRUSTED_ORIGINS (include your dashboard origin; for local dev you can keep the default)

Optional (only if you want SSO buttons):

  • GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
  • GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET

Optional (only if you enable billing flows):

  • STRIPE_SECRET_KEY and related STRIPE_* vars

Optional (Integrations): Configure notification channels (Slack, Discord, Jira, PagerDuty, Datadog, Grafana, Webhook) in the Dashboard at Console → Integrations after startup. See the Notification Channels Setup Guide.

The defaults work for local development. For AI diagnosis features, add an LLM provider key:

# In .env
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here

Or leave LLM_PROVIDER=mock to use the built-in simulated AI workflow.

3. Start Infrastructure

bun run infra:up

This starts PostgreSQL, Redis, OpenSearch, Jaeger, Prometheus, and the OpenTelemetry Collector via Docker Compose.

4. Start All Services

bun run dev

This launches the active local stack in watch mode:

ServiceURL
Ingestionhttp://localhost:3001
Core Platformhttp://localhost:3003
Dashboardhttp://localhost:3000

5. Send Your First Log Event

Open a terminal and send a sample log:

curl -X POST http://localhost:3001/events/logs \
  -H "Content-Type: application/json" \
  -H "x-organization-id: org_123456789" \
  -d '{
    "service": "billing-service",
    "level": "error",
    "message": "Payment gateway timeout after 30s — customer 42 affected",
    "metadata": {
      "region": "us-east-1",
      "env": "prod",
      "team": "payments"
    }
  }'

You should receive:

{
  "id": "a1b2c3d4-...",
  "queued": true
}

6. Send a Metric

curl -X POST http://localhost:3001/events/metrics \
  -H "Content-Type: application/json" \
  -H "x-organization-id: org_123456789" \
  -d '{
    "service": "billing-service",
    "name": "http_5xx_rate",
    "value": 0.45,
    "unit": "percent",
    "labels": {
      "region": "us-east-1",
      "env": "prod"
    }
  }'

7. View the Dashboard

Open http://localhost:3000 in your browser. If the core platform's detection rules match your events, you'll see an incident appear in the feed.

8. Verify Traces and SPM

Open Jaeger at http://localhost:16686.

  • Search tab: verify traces from operyn-dashboard, core-platform, and ingestion-service.
  • Monitor tab: verify RED metrics (requests, errors, duration) after you generate traffic.

If Monitor is empty, ensure your services are running with the OTEL env defaults and send a few requests to both backend services.

9. Explore the API Docs

The active backend services expose interactive API documentation:

What Happens Behind the Scenes

  1. The Ingestion Service receives your log/metric, validates it against a Zod schema, normalises fields, indexes it into OpenSearch, and enqueues it on BullMQ.
  2. Core Platform consumes the event from the queue, evaluates it against detection rules (error rate thresholds, anomaly patterns), and decides whether to create or update an incident.
  3. If an incident is created, the AI workflows inside core-platform analyse the context and produce a root cause hypothesis with suggested fixes.
  4. Suggested fixes flow into the remediation workflows inside core-platform, which can queue, simulate, or execute actions based on policy.
  5. The notifications workflows inside core-platform dispatch alerts to configured channels (Slack/Discord/Email/Webhook). Jira ticketing is handled by the incidents module in core-platform using per-org encrypted credentials.
  6. You see the full timeline on the Dashboard and can approve or reject remediation actions.

Next Steps