openvidu-dashboard: analytics and the dashboard require MongoDB

On a database without updates with an aggregation pipeline, such as Amazon DocumentDB, the server starts with analytics disabled instead of refusing to start.

openvidu-dashboard/CHANGELOG.md

@@ -17,6 +17,8 @@ queried) and `Deployment` (running the service). One line per observable change,
   instead of `3000`.
 - The image runs as uid 1000: mounted configuration and certificate authority files must be readable by that user.
 - Client IP addresses are no longer stored by default; set `openvidu.analytics.anonymize_ip: false` to store them.
+- The analytics data and the dashboard require MongoDB: on Amazon DocumentDB the server starts with analytics disabled
+  and logs why.
 
 ### Breaking changes
 
@@ -86,8 +88,7 @@ queried) and `Deployment` (running the service). One line per observable change,
 - Analytics durations accept days (`7d`, `1d12h`), and the server refuses to start on a retention above the MongoDB TTL
   limit, an entity retention under 2 days or a daily rollup retention shorter than the hourly one, naming the key.
 - The server logs a warning when a full analytics queue drops entries, at most once per queue and batch interval.
-- `DATABASE_TLS_CA_FILE` trusts a private certificate authority for external MongoDB services such as Amazon
+- `DATABASE_TLS_CA_FILE` trusts a private certificate authority for external MongoDB services.
-  DocumentDB.
 - The dashboard refuses to start (exit code 3) against an OpenVidu server whose analytics schema is older than it
   supports, and reports a newer or uninitialized schema in `GET /api/v1/info`.
 - The image declares a Docker `HEALTHCHECK`, through the `healthcheck` argument of the backend entry.

openvidu-dashboard/openspec/changes/analytics-requires-mongodb/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-27

openvidu-dashboard/openspec/changes/analytics-requires-mongodb/design.md

@@ -0,0 +1,50 @@
+# Design
+
+## Context
+
+- `openvidu.Start` calls `analytics.InitializeAnalytics`, which connects, pings, renames the legacy events collection,
+  initializes collections, validators and indexes, and prepares the writer, the reconciler and the migration. Any error
+  stops the server ("An error means the server must not start").
+- Measured against Amazon DocumentDB 5.0.0 and 8.0.0: updates with an aggregation pipeline fail with "Wrong type for
+  parameter u", time-series collections, partial indexes with `$in`, `validationAction: warn`, `$facet`,
+  `$setWindowFields`, `$percentile` and `$median` are not supported, and collections cannot be created inside
+  transactions.
+
+## Goals / Non-Goals
+
+**Goals:**
+- An OpenVidu server configured with a DocumentDB URI starts and serves media, with analytics off and a log that says
+  why.
+
+**Non-Goals:**
+- Writing analytics to DocumentDB.
+- Changing how other startup failures behave (unreachable MongoDB, a newer schema, a bad configuration).
+
+## Decisions
+
+### Probe the capability, not the vendor
+
+The writer asks the database to explain an update with an aggregation pipeline on `schema_meta`. MongoDB plans it
+without writing; a database without pipeline updates rejects it. Only the rejection of the pipeline form disables
+analytics; any other error of the probe, such as a lost connection, is returned as before and stops the server.
+
+Alternative rejected: recognising DocumentDB by host name or `buildInfo`. Host names can be aliased and the build
+information is not a contract; the capability is what the writer needs.
+
+Alternative rejected: probing with a real update. It writes a document that the contract validators do not expect.
+
+### Disabled, not degraded
+
+Without pipeline updates no entity can be projected, so there is nothing useful to keep: no collections, indexes,
+reconciler or migration. The server keeps `analyticsEnabled` false, as when `openvidu.analytics.enabled` is false.
+
+### Data model
+
+- No collection, field, index or schema-version change; nothing is written to an unsupported database.
+- Migration from legacy events: not run on an unsupported database; legacy collections stay as they are.
+- Performance: one explain at startup.
+
+## Risks / Trade-offs
+
+- [A future MongoDB-compatible service accepts the explain but not the update] → Initialization would then fail as
+  today and stop the server; the log names the failing step.

openvidu-dashboard/openspec/changes/analytics-requires-mongodb/proposal.md

@@ -0,0 +1,49 @@
+# Proposal
+
+## Why
+
+The writer updates every entity with an aggregation pipeline, creates `track_stats` as a time-series collection when it
+can, uses partial indexes with `$in` and validators with `validationAction: warn`. Amazon DocumentDB (5.0 and 8.0)
+supports none of the first, third and fourth, so database initialization fails and the server refuses to start:
+`failed to start analytics: ... Feature not supported: validationAction:warn`. Deployments that use DocumentDB as their
+external database would lose the whole OpenVidu server on upgrade, not only analytics.
+
+## What Changes
+
+- Before initializing the database, the writer checks that it runs updates with an aggregation pipeline, without
+  writing. A database that does not (Amazon DocumentDB) disables analytics: the server logs an error that names the
+  reason and that analytics and the dashboard need MongoDB, then starts and runs without analytics. It writes nothing
+  to that database.
+- Every other analytics startup failure still stops the server.
+- The dashboard's private CA variable is no longer described as a way to use Amazon DocumentDB.
+
+Scope excludes the following:
+- A write path for databases without pipeline updates.
+- The dashboard against such a database, which reports an uninitialized writer schema as it already does.
+- The public documentation of external databases, updated with the release documentation.
+
+Edition: CE and PRO (writer). Repositories: openvidu-livekit (`openvidu/analytics`, `openvidu/openvidu.go`) and the
+dashboard (specs, CHANGELOG).
+
+CHANGELOG lines:
+- `openvidu-dashboard/CHANGELOG.md`, Upgrade notes: analytics and the dashboard require MongoDB; on Amazon DocumentDB the
+  server starts with analytics disabled. The `DATABASE_TLS_CA_FILE` line no longer names DocumentDB.
+- openvidu-livekit `CHANGELOG-openvidu.md`, Changed: the same behaviour of the server.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `server-analytics-writer`: a database without pipeline updates disables analytics instead of stopping the server.
+- `deployment-compatibility`: the private CA requirement names no DocumentDB.
+
+## Impact
+
+- Writer: `InitializeAnalytics` probes the database after the connection check; `openvidu.Start` treats the
+  unsupported database as analytics disabled. Unit tests of the probe classification and an integration test against
+  MongoDB.
+- Dashboard: specs and CHANGELOG only.

openvidu-dashboard/openspec/changes/analytics-requires-mongodb/specs/deployment-compatibility/spec.md

@@ -0,0 +1,16 @@
+## MODIFIED Requirements
+
+### Requirement: TLS certificate authority for external MongoDB
+Both editions. When `DATABASE_TLS_CA_FILE` is set, the dashboard SHALL connect with TLS and trust the PEM
+bundle at that path (for MongoDB services whose certificates a private CA signs).
+
+#### Scenario: Private CA accepted
+- **GIVEN** a MongoDB server presenting a certificate signed by a private CA and `DATABASE_TLS_CA_FILE`
+  pointing to that CA
+- **WHEN** the dashboard starts
+- **THEN** the connection succeeds
+
+#### Scenario: Unreadable CA file
+- **GIVEN** `DATABASE_TLS_CA_FILE` pointing to a missing or unreadable file
+- **WHEN** the dashboard starts
+- **THEN** it logs the path and exits with code 1

openvidu-dashboard/openspec/changes/analytics-requires-mongodb/specs/server-analytics-writer/spec.md

@@ -0,0 +1,17 @@
+## ADDED Requirements
+
+### Requirement: Database without pipeline updates
+Edition: CE and PRO. Before initializing the database, the writer SHALL check, without writing, that it runs updates
+with an aggregation pipeline. When it does not, the server SHALL log an error naming the reason and that analytics and
+the dashboard require MongoDB, write nothing to that database and start without analytics; any other analytics startup
+failure SHALL still stop the server.
+
+#### Scenario: Amazon DocumentDB as external database
+- **GIVEN** `openvidu.analytics.enabled: true` and `mongo_url` pointing to an Amazon DocumentDB cluster
+- **WHEN** the server starts
+- **THEN** it logs an error saying that the database does not support updates with aggregation pipelines and that analytics and the dashboard require MongoDB, accepts participants, and no analytics collection is created in the cluster
+
+#### Scenario: Unreachable MongoDB
+- **GIVEN** `mongo_url` pointing to a MongoDB that does not answer
+- **WHEN** the server starts
+- **THEN** it refuses to start, as before

openvidu-dashboard/openspec/changes/analytics-requires-mongodb/tasks.md

@@ -0,0 +1,19 @@
+# Tasks
+
+## 1. Writer (openvidu-livekit)
+
+- [x] 1.1 Add the pipeline update probe (an explain on `schema_meta`) and the unsupported database error to
+      `openvidu/analytics`, run it after the connection check, and make `openvidu.Start` log it and start without
+      analytics. Verify with unit tests of the error classification, an integration test against MongoDB and the lint
+      of the fork.
+- [x] 1.2 Start the server image against an Amazon DocumentDB cluster. Verify that it logs the error, serves a room
+      and creates no collection in the cluster.
+
+## 2. Docs and CHANGELOG
+
+- [x] 2.1 Add the upgrade note and correct the `DATABASE_TLS_CA_FILE` line of `openvidu-dashboard/CHANGELOG.md`, and add
+      the Changed line of `CHANGELOG-openvidu.md`. Verify by reading both against the change.
+
+## 3. Integration check
+
+- [x] 3.1 Run the spec validation and the format check of the dashboard. Verify that they pass.