mirror of https://github.com/OpenVidu/openvidu.git
222 lines
10 KiB
Markdown
222 lines
10 KiB
Markdown
# deployment-compatibility Specification
|
|
|
|
## Purpose
|
|
The runtime contract between the dashboard container and the OpenVidu installers, Helm chart, reverse proxy
|
|
and health checks: environment variables, HTTP endpoints, startup order, exit codes and shutdown behaviour.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: Legacy environment variables are honoured
|
|
Both editions. The dashboard SHALL read `SERVER_PORT` (default `5000`), `ADMIN_USERNAME`, `ADMIN_PASSWORD`,
|
|
`MONGO_ENABLED` (default `true`), `DATABASE_URL`, `DATABASE_NAME` (default `openvidu`), `MONGO_NODES`,
|
|
`MONGO_PORT`, `MONGO_ADMIN_USERNAME`, `MONGO_ADMIN_PASSWORD`, `MONGO_REPLICA_SET_NAME`,
|
|
`DASHBOARD_CONFIG_PATH` and `LOG_LEVEL` (default `info`) with the same names and meaning as OpenVidu 3.9.
|
|
|
|
#### Scenario: Default port
|
|
- **GIVEN** `SERVER_PORT` is unset
|
|
- **WHEN** the dashboard starts
|
|
- **THEN** it listens on port 5000 and logs the port
|
|
|
|
#### Scenario: Explicit port
|
|
- **GIVEN** `SERVER_PORT=6000`
|
|
- **WHEN** the dashboard starts
|
|
- **THEN** it listens on port 6000
|
|
|
|
#### Scenario: Log level
|
|
- **GIVEN** `LOG_LEVEL=debug`
|
|
- **WHEN** the dashboard runs
|
|
- **THEN** debug messages are emitted; an unknown value falls back to `info` with a warning
|
|
|
|
### Requirement: Configuration file loaded at boot
|
|
Both editions. When `DASHBOARD_CONFIG_PATH` is set, the dashboard SHALL load that file (`KEY=value` lines)
|
|
into its environment before reading any configuration. Variables already present in the process environment
|
|
SHALL take precedence over the file. A missing file SHALL be logged as a warning, not an error; a file that exists but
|
|
cannot be read (for example, not readable by uid 1000) SHALL be logged with its path and exit with code 1.
|
|
|
|
#### Scenario: Value from the file
|
|
- **GIVEN** `DASHBOARD_CONFIG_PATH=/config/dashboard.env` containing `ADMIN_PASSWORD=secret`
|
|
- **WHEN** the dashboard starts
|
|
- **THEN** the administrator password is `secret`
|
|
|
|
#### Scenario: Environment wins over the file
|
|
- **GIVEN** the file sets `SERVER_PORT=7000` and the environment sets `SERVER_PORT=5000`
|
|
- **WHEN** the dashboard starts
|
|
- **THEN** it listens on port 5000
|
|
|
|
#### Scenario: File missing
|
|
- **GIVEN** `DASHBOARD_CONFIG_PATH` points to a non-existent file
|
|
- **WHEN** the dashboard starts
|
|
- **THEN** it logs a warning naming the path and continues with the environment
|
|
|
|
#### Scenario: File unreadable
|
|
- **GIVEN** `DASHBOARD_CONFIG_PATH` points to a file the dashboard user cannot read
|
|
- **WHEN** the dashboard starts
|
|
- **THEN** it logs the path and the reason and exits with code 1 without listening
|
|
|
|
### Requirement: MongoDB connection settings
|
|
Both editions. The dashboard SHALL connect with `DATABASE_URL` when set; otherwise it SHALL compose the URL
|
|
from `MONGO_NODES` (comma-separated hosts), `MONGO_PORT`, `MONGO_ADMIN_USERNAME`, `MONGO_ADMIN_PASSWORD` and
|
|
`MONGO_REPLICA_SET_NAME` with `readPreference=primaryPreferred`. Database name comes from `DATABASE_NAME`.
|
|
|
|
#### Scenario: Composed URL
|
|
- **GIVEN** `DATABASE_URL` unset and `MONGO_NODES=mongo1,mongo2`, `MONGO_PORT=27017`,
|
|
`MONGO_REPLICA_SET_NAME=rs0` plus credentials
|
|
- **WHEN** the dashboard starts
|
|
- **THEN** it connects to `mongodb://<user>:<pass>@mongo1:27017,mongo2:27017/?replicaSet=rs0&readPreference=primaryPreferred`
|
|
|
|
#### Scenario: Missing composition variables
|
|
- **GIVEN** `DATABASE_URL` unset and `MONGO_PORT` unset
|
|
- **WHEN** the dashboard starts
|
|
- **THEN** it logs every missing variable name and exits with code 1 without listening
|
|
|
|
### Requirement: MongoDB disabled
|
|
Both editions. When `MONGO_ENABLED` is set to any value other than `true` (case-insensitive), the dashboard SHALL log
|
|
that MongoDB is disabled and exit with code 0 before connecting to anything; unset means enabled.
|
|
|
|
#### Scenario: MONGO_ENABLED=false
|
|
- **GIVEN** `MONGO_ENABLED=false`
|
|
- **WHEN** the container starts
|
|
- **THEN** it logs `MongoDB is disabled. Stopping application.` and exits with code 0
|
|
|
|
#### Scenario: Value other than true
|
|
- **GIVEN** `MONGO_ENABLED=no`
|
|
- **WHEN** the container starts
|
|
- **THEN** it logs `MongoDB is disabled. Stopping application.` and exits with code 0
|
|
|
|
#### Scenario: Case-insensitive true
|
|
- **GIVEN** `MONGO_ENABLED=TRUE`
|
|
- **WHEN** the container starts
|
|
- **THEN** it connects to MongoDB
|
|
|
|
### 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 services such as Amazon DocumentDB).
|
|
|
|
#### 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
|
|
|
|
### Requirement: Administrator credentials are required
|
|
Both editions. `ADMIN_USERNAME` and `ADMIN_PASSWORD` SHALL be set and non-empty; the dashboard SHALL NOT
|
|
fall back to built-in credentials.
|
|
|
|
#### Scenario: Missing credentials
|
|
- **GIVEN** `ADMIN_PASSWORD` unset or empty
|
|
- **WHEN** the dashboard starts
|
|
- **THEN** it logs which variable is missing and exits with code 1
|
|
|
|
### Requirement: Session variables with the DASHBOARD_ prefix
|
|
Both editions. The dashboard SHALL accept `DASHBOARD_JWT_SECRET` (optional signing key; when unset a key is
|
|
generated and shared through the database), `DASHBOARD_REFRESH_TOKEN_TTL` (refresh session lifetime in
|
|
seconds, default `604800`) and `DASHBOARD_COOKIE_SECURE` (`auto` | `true` | `false`, default `auto`, semantics
|
|
owned by the `auth` capability).
|
|
|
|
#### Scenario: Invalid refresh TTL
|
|
- **GIVEN** `DASHBOARD_REFRESH_TOKEN_TTL=soon`
|
|
- **WHEN** the dashboard starts
|
|
- **THEN** it logs the invalid value and exits with code 1
|
|
|
|
#### Scenario: Automatic Secure flag
|
|
- **GIVEN** the default `DASHBOARD_COOKIE_SECURE=auto`
|
|
- **WHEN** an administrator logs in through a proxy that sets `X-Forwarded-Proto: https`
|
|
- **THEN** the refresh cookie carries the `Secure` attribute
|
|
|
|
#### Scenario: Insecure cookie for plain HTTP
|
|
- **GIVEN** `DASHBOARD_COOKIE_SECURE=false`
|
|
- **WHEN** an administrator logs in over plain HTTP
|
|
- **THEN** the refresh cookie is set without the `Secure` attribute and the session works
|
|
|
|
### Requirement: Cache variables with the DASHBOARD_ prefix
|
|
|
|
Edition: CE. The dashboard SHALL accept `DASHBOARD_ANALYTICS_CACHE_TTL` (seconds the analytics folds of completed
|
|
rollup documents are kept, non-negative integer, default `60`, `0` disables the cache); an invalid value SHALL be logged
|
|
and exit with code 1.
|
|
|
|
#### Scenario: Invalid cache lifetime
|
|
- **GIVEN** `DASHBOARD_ANALYTICS_CACHE_TTL=-5`
|
|
- **WHEN** the dashboard starts
|
|
- **THEN** it logs the invalid value and exits with code 1 without listening
|
|
|
|
#### Scenario: Caches disabled
|
|
|
|
- **GIVEN** `DASHBOARD_ANALYTICS_CACHE_TTL=0`
|
|
- **WHEN** an analytics request is repeated
|
|
- **THEN** each request aggregates from MongoDB and returns the same body as with the cache enabled
|
|
|
|
### Requirement: Naming rule for dashboard variables
|
|
Both editions. Every configuration variable that OpenVidu 3.9 does not read SHALL be prefixed `DASHBOARD_`, except
|
|
database connection variables, which SHALL be prefixed `DATABASE_`.
|
|
|
|
#### Scenario: Configuration schema audit
|
|
- **WHEN** the set of variable names read by the configuration is listed
|
|
- **THEN** every name is read by OpenVidu 3.9, starts with `DASHBOARD_` or starts with `DATABASE_`
|
|
|
|
### Requirement: HTTP contract owned by the API conventions
|
|
Both editions. The health endpoint (`GET /api/healthcheck`), `HEAD /`, the SPA fallback (including the unstripped
|
|
`/dashboard/api/healthcheck` used by the HA proxy health check), the JSON 404 for unknown `/api` paths and the
|
|
relative API URLs behind a stripped `/dashboard/` prefix SHALL behave as specified by the `api-conventions`
|
|
capability; this capability adds no second definition.
|
|
|
|
#### Scenario: Behind strip_path_prefix
|
|
- **GIVEN** an image built with `BASE_HREF=/dashboard/` behind a proxy that strips `/dashboard`
|
|
- **WHEN** an administrator logs in and opens the rooms list through the proxy
|
|
- **THEN** every request the SPA issues starts with `/dashboard/` and the pages load
|
|
|
|
### Requirement: Startup order
|
|
|
|
Edition: CE. Startup SHALL proceed in this order: load configuration, ping MongoDB, check the writer schema version,
|
|
provision the signing key and the session indexes, listen. A failure at any step SHALL exit without listening and log
|
|
its cause; the exit code is 3 for a writer schema older than the dashboard's minimum and 1 for any other failure.
|
|
|
|
#### Scenario: MongoDB unreachable
|
|
|
|
- **GIVEN** MongoDB does not answer
|
|
- **WHEN** the dashboard starts
|
|
- **THEN** it logs the connection error and exits with code 1 without listening
|
|
|
|
### Requirement: Writer schema version gate
|
|
Both editions. If `schema_meta` reports a writer schema version lower than the dashboard's minimum, the
|
|
dashboard SHALL log both versions with an upgrade instruction and exit with code 3. If the writer is newer,
|
|
it SHALL start, log a warning and expose the mismatch in `GET /api/v1/info` so the UI shows a banner. If
|
|
`schema_meta` is absent, it SHALL start and report `uninitialized` in the same field.
|
|
|
|
#### Scenario: Writer too old
|
|
- **GIVEN** `schema_meta.version` is lower than the dashboard's minimum
|
|
- **WHEN** the dashboard starts
|
|
- **THEN** it logs `Analytics schema version <w> is older than the minimum <m> supported by this dashboard;
|
|
upgrade the OpenVidu server` and exits with code 3
|
|
|
|
#### Scenario: Writer newer
|
|
- **GIVEN** `schema_meta.version` is higher than the dashboard's version
|
|
- **WHEN** the dashboard starts
|
|
- **THEN** it listens, logs a warning and `GET /api/v1/info` reports `schema.status = "newer"`
|
|
|
|
#### Scenario: Schema not initialized
|
|
- **GIVEN** no `schema_meta` document
|
|
- **WHEN** the dashboard starts
|
|
- **THEN** it listens and `GET /api/v1/info` reports `schema.status = "uninitialized"` until the document
|
|
appears
|
|
|
|
### Requirement: Graceful shutdown
|
|
Both editions. On `SIGTERM` or `SIGINT` the dashboard SHALL stop accepting connections, close idle
|
|
connections, close the MongoDB client and exit within 5 seconds (under the 10 s container stop timeout). A
|
|
signal-initiated shutdown exits with code 0; a repeated signal does not restart the sequence; a signal during
|
|
startup exits promptly.
|
|
|
|
#### Scenario: Stop under load
|
|
- **GIVEN** a running dashboard with idle keep-alive connections from a browser
|
|
- **WHEN** `SIGTERM` is received
|
|
- **THEN** the process exits with code 0 in less than 5 seconds
|
|
|
|
#### Scenario: Stop during startup
|
|
- **GIVEN** the dashboard is still pinging MongoDB
|
|
- **WHEN** `SIGTERM` is received
|
|
- **THEN** the process exits with code 0 without listening
|