2026-10-25 16:35:47 +01:00
# OpenVidu Dashboard
Web application bundled with every OpenVidu deployment that gives administrators live monitoring and usage
analytics of rooms, participants, tracks, egress and ingress. It reads the MongoDB analytics database written
by the OpenVidu server (`openvidu-livekit`).
This workspace holds the Community edition (CE, `dashboard-ce/` ). OpenVidu PRO deployments run a commercial edition
built on these packages, whose features CE shows locked.
## Layout
| Path | Package | Role |
| ----------------------------------- | ------------------------------------ | -------------------------------------------------- |
| `dashboard-ce/typings` | `@openvidu-dashboard/typings` | Contracts shared by backend and frontend |
| `dashboard-ce/backend` | `@openvidu-dashboard/backend` | REST API; serves the built single-page application |
| `dashboard-ce/frontend` | `@openvidu-dashboard/frontend` | Angular application shell and the UI library |
| `dashboard-ce/e2e` | `@openvidu-dashboard/e2e` | End-to-end tests (Playwright) |
| `dashboard-ce/tools/data-generator` | `@openvidu-dashboard/data-generator` | Analytics data for tests and the local demo |
| `openspec/` | | Specifications and in-progress changes (OpenSpec) |
## Requirements
- Node.js 24 (see `.node-version` )
- pnpm, enabled through Corepack (`corepack enable`); the version is pinned by `packageManager` in
`package.json`
## Browser support
Current Chrome, Edge, Firefox and Safari: the theme needs CSS `light-dark()` (Chrome and Edge 123, Firefox 120,
Safari 17.5).
## Commands
All tasks run through `./dashboard.sh` :
```bash
./dashboard.sh install # install dependencies
./dashboard.sh check # lint + format check + type check + spec validation + unit tests
2026-10-26 19:00:12 +01:00
./dashboard.sh dev # backend and frontend dev servers against openvidu-local-deployment
2026-10-25 16:35:47 +01:00
./dashboard.sh demo ce # local demo on generated data: http://localhost:4200, admin / admin
./dashboard.sh test-integration # integration tests against MongoDB (Docker required)
./dashboard.sh e2e # build the application and run the Playwright tests
./dashboard.sh build-image ce # build openvidu/openvidu-dashboard:dev
./dashboard.sh smoke-image ce # smoke test and size budget of that image
./dashboard.sh contract-check ../openvidu-livekit # data model contract check against the writer
./dashboard.sh help # list every command
```
2026-10-26 19:00:12 +01:00
## Development
`./dashboard.sh dev` runs the backend and frontend development servers against the MongoDB of an
[openvidu-local-deployment ](https://github.com/OpenVidu/openvidu-local-deployment ) running on this machine, both
reloading on changes: http://localhost:4200, `admin` / `admin` . Ctrl+C stops both. Without a deployment,
`./dashboard.sh demo ce` runs the same servers on generated data instead.
- Before starting, it checks the configuration and that MongoDB answers, and says what to do when it does not.
- The backend reads `dashboard-ce/backend/dev.env` , the defaults for the local deployment. A git-ignored
`dashboard-ce/backend/.env` overrides them, and the environment overrides both, for example
`DATABASE_URL` for another MongoDB or `LOG_LEVEL=debug` . The deployment's replica set advertises its member
as `mongo:27017` , which only Docker resolves, so a URL from the host needs `directConnection=true` .
- `DASHBOARD_DEV_PORT` (default 4200) and `DASHBOARD_DEV_BACKEND_PORT` (default 5000) move the servers, for
example off port 5000 where macOS runs AirPlay.
- The deployment needs a 3.10 OpenVidu server: data appears once it writes the analytics database, and an
older writer schema stops the check.
2026-10-25 16:35:47 +01:00
## Container image
`openvidu/openvidu-dashboard` , built from `dashboard-ce/docker/Dockerfile` on `node:24-trixie-slim`
(`node dist/server.js`).
- The build context is this directory. `IMAGE_TAG` (default `dev` ) and `BASE_HREF` (default `/` ; deployments use
`/dashboard/` ) apply.
- The image runs as uid 1000 and writes nothing to disk; mounted files (`DASHBOARD_CONFIG_PATH`,
`DATABASE_TLS_CA_FILE` ) must be readable by that user. The container listens on `SERVER_PORT` (5000) and its
`HEALTHCHECK` requests `GET /api/healthcheck` on that port.
- `./dashboard.sh smoke-image ce` checks `MONGO_ENABLED=false` , health, `GET /api/healthcheck` , `HEAD /` , uid 1000,
`SERVER_PORT` , `docker stop` and the 300 MB size budget.
## Configuration
Environment variables, optionally loaded from the file at `DASHBOARD_CONFIG_PATH` (the environment wins). New names
start with `DASHBOARD_` , or `DATABASE_` for database connection settings; the others keep their 3.9 meaning.
| Variable | Default | Meaning |
| ----------------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------- |
| `ADMIN_USERNAME` , `ADMIN_PASSWORD` | required | Administrator credentials |
| `SERVER_PORT` | `5000` | HTTP port |
| `LOG_LEVEL` | `info` | `error` , `warn` , `info` , `http` , `verbose` , `debug` or `silly` |
| `DASHBOARD_CONFIG_PATH` | | `KEY=value` file read at startup; a missing file logs a warning |
| `MONGO_ENABLED` | `true` | Anything but `true` stops the dashboard with exit code 0 |
| `DATABASE_URL` | | MongoDB connection string; otherwise composed from the `MONGO_*` variables |
| `MONGO_NODES` , `MONGO_PORT` , `MONGO_ADMIN_USERNAME` , `MONGO_ADMIN_PASSWORD` , `MONGO_REPLICA_SET_NAME` | | Parts of the composed connection string (`readPreference=primaryPreferred`) |
| `DATABASE_NAME` | `openvidu` | Analytics database |
| `DATABASE_TLS_CA_FILE` | | PEM file of a private certificate authority; enables TLS |
| `DASHBOARD_JWT_SECRET` | generated once | Signing key of the session tokens, at least 32 bytes |
| `DASHBOARD_REFRESH_TOKEN_TTL` | `604800` | Session lifetime without use, in seconds |
| `DASHBOARD_COOKIE_SECURE` | `auto` | `auto` , `true` or `false` |
| `DASHBOARD_TRUST_PROXY` | private networks | `false` , a hop count, or addresses, CIDRs, `loopback` , `linklocal` and `uniquelocal` ; `true` is refused |
| `DASHBOARD_BASE_PATH` | the SPA `<base href>` | Public path of the dashboard |
| `DASHBOARD_LIST_TOTAL_MAX_RANGE` | `7d` | Longest range for which lists count their total |
| `DASHBOARD_ANALYTICS_CACHE_TTL` | `60` | Seconds the analytics folds of completed rollup documents are kept; `0` disables it |
## Exit codes
| Code | Meaning |
| ---- | ---------------------------------------------------------------------------- |
| 0 | Stopped by a signal, or `MONGO_ENABLED` is not `true` |
| 1 | Invalid configuration or MongoDB unreachable |
| 3 | The OpenVidu server's analytics schema is older than this dashboard supports |
## Contributing
Read `AGENTS.md` , and the one of the package you change, before changing anything: they describe the edition model,
conventions and the spec-driven workflow used in this workspace.
