Installation

This page is the shortest install path. For a guided decision tree across runtime and data options, start with Getting started. If you only want to instrument a service with an SDK, jump to SDKs.

Prerequisites

• Docker for the all-in-one local image and the Astronomy Shop demo.
• Node.js 22+ and pnpm 10+ for local repo development and scripts.
• A POSIX shell such as bash or zsh.

Fastest first run: prebuilt image

The release image is published to GitHub Container Registry as ghcr.io/dev-sawan-ruparel/obs-unified. It packages the Node collector, the dashboard, embedded Postgres, and filesystem blob storage in one container. No clone or Node.js toolchain is needed.

The image fails closed: it refuses to start unless you supply your own ingest key and dashboard password.

export INGEST_KEY="pick-a-long-random-ingest-key"
export DASHBOARD_PASSWORD="pick-a-dashboard-password"
export DASHBOARD_TOKEN="pick-a-read-token-for-mcp-and-cli"

docker run --rm \
  -p 5173:5173 \
  -p 8790:8790 \
  -e INGEST_KEY \
  -e DASHBOARD_PASSWORD \
  -e DASHBOARD_TOKEN \
  -e OBS_LOCAL_SEED=true \
  -v obs-unified-db:/var/lib/postgresql \
  -v obs-unified-blobs:/data \
  ghcr.io/dev-sawan-ruparel/obs-unified:latest

Log in to the dashboard with DASHBOARD_PASSWORD, point SDKs or OTLP exporters at http://localhost:8790 with INGEST_KEY, and pass DASHBOARD_TOKEN to @obsunified/mcp-server or @obsunified/cli. Scripted login (POST /auth/login) and logout semantics are in Identity and external access.

To check the image without a browser, pull it or inspect its manifest (both work anonymously):

docker pull ghcr.io/dev-sawan-ruparel/obs-unified:latest
docker manifest inspect ghcr.io/dev-sawan-ruparel/obs-unified:latest

Tags: latest, a version tag that tracks the collector release (for example 2.2.0), and an immutable sha-<commit> tag. Pin a version or sha tag for anything you intend to keep running. Omit -e OBS_LOCAL_SEED=true (the default is false) when you want a clean database before sending your own telemetry. Runtime variables, volumes, and rollback notes are in the Docker release guide.

Local image with sample data

Build and run the local image from a clone:

pnpm local:image
pnpm local:run

This starts Postgres, the collector, the dashboard, a filesystem blob store, and seeded sample data in one container. It uses fixed development credentials, so keep it on your own machine.

Credentials for the locally built image (pnpm local:run only; the prebuilt GHCR image rejects these values and requires your own, see the prebuilt image section above):

Tokens and env vars

Run the local image smoke test when you want a full outside-the-container verification:

pnpm smoke:local-image

Editable local install

Use this when you are changing collector, dashboard, or SDK code.

git clone https://github.com/dev-sawan-ruparel/obs-unified.git
cd obs-unified
pnpm install
pnpm run setup
pnpm run dev

pnpm run setup creates apps/collector/.dev.vars from apps/collector/.dev.vars.example if needed, then runs local migrations. The sample-data seeder reads that same file, so custom local credentials do not need to be exported in every shell.

The local dev stack exposes:

Seed sample data

The Docker image seeds sample data automatically. For the editable local install, run:

pnpm run seed

This populates traces, logs, AI calls, usage events, issues, users, and alert rules. Replays require a real browser interaction, so use the dashboard Playground tab to capture one.

Astronomy Shop demo

For realistic microservice traffic and service-map edges:

pnpm demo:setup
pnpm demo:preflight
pnpm demo:up

Open the demo shop at http://localhost:8080 and the dashboard at http://localhost:5173.

Stop it with:

pnpm demo:down

Standalone Node collector

If you only want the collector service with Postgres and RustFS/S3:

cd apps/collector-node
docker compose up -d
docker compose logs -f collector

Packages and registries

Everything a client needs is published; cloning the repo is only required for the editable install and the seeded local image.

All npm packages live under the @obsunified organization.

Production deployment

For production deployment details, see Production operations. At minimum, set a real INGEST_KEY, set DASHBOARD_PASSWORD, point VITE_OBS_COLLECTOR_URL at your collector, configure CORS for browser origins, and run migrations before accepting traffic.