EchoDom

EchoDom is a self-hostable session replay and RUM telemetry stack: a browser SDK sends batched events to a Go ingestion server, which stores them in PostgreSQL. A web dashboard lists projects and sessions and plays back recordings.

Licensed under the MIT License.

Demo

Screen.Recording.2026-04-14.at.11.20.22.PM.mp4

Repository layout

Path	Role
apps/ingest/	Go Fiber HTTP server: /v1/ingest, Postgres, worker pool, migrations
sdk/	TypeScript browser SDK (echodom on npm when published), rrweb-based recording, Vitest
apps/dashboard/	React dashboard: projects, sessions, replay, telemetry panels

Authoritative run commands and API details for ingest live in apps/ingest/README.md. Dashboard setup is in apps/dashboard/README.md.

Prerequisites

• PostgreSQL 14+ (or compatible)
• Go 1.26+ (see apps/ingest/go.mod)
• Node.js 20+ (for SDK and dashboard)

Quickstart (Docker)

From the repo root:

# Start Postgres + ingest + dashboard (dev server)
docker compose up --build

• Dashboard: http://localhost:3000
• Ingest health: http://localhost:8080/health

Dashboard API key (optional)

If you set DASHBOARD_API_KEY, the ingest server will require it for /v1/dashboard/* routes, and the dashboard will send it as Authorization: Bearer ....

export DASHBOARD_API_KEY=your_key_here
docker compose up --build

Seed a dev project (manual)

docker compose exec -T postgres psql -U echodom -d echodom -f /dev/stdin < apps/ingest/scripts/seed.sql

Quickstart (local)

1. Ingest server

From apps/ingest/:

1. Copy .env.example to .env and set DATABASE_URL.

2. Start Postgres and create a database if needed.

3. Run the server (migrations run on startup):

   cd apps/ingest
   go run main.go

4. Optional: seed a dev project (see ingest README for the project ID and origins):

   psql "$DATABASE_URL" -f scripts/seed.sql

2. SDK (build and test)

From sdk/:

cd sdk
npm install
npm run build
npm test

Wire the SDK in your app against the ingest base URL and project credentials as documented in the SDK source and ingest API.

2a. SDK (npm package)

Install from npm (@echodom/sdk):

npm install @echodom/sdk

Minimal usage:

import EchoDom from '@echodom/sdk';

EchoDom.init({
  projectId: '<your-project-id>',
  endpoint: 'http://localhost:8080/v1/ingest',
});

3. Dashboard

From apps/dashboard/:

1. Copy .env.example to .env.

2. Set PUBLIC_API_URL to your ingest server (for example http://localhost:8080). If your ingest dashboard API requires a key, set PUBLIC_DASHBOARD_API_KEY.

3. Run the dev server:

   cd apps/dashboard
   npm install
   npm run dev

Contributing

See CONTRIBUTING.md. Please follow SECURITY.md for vulnerability reports.

Code of conduct

This project adopts the Contributor Covenant; see CODE_OF_CONDUCT.md.