/vss-setup-video-analytics-api

Deploy Video Analytics API — Standalone Service

Deploy just vss-video-analytics-api (no perception, no behavior-analytics, no UI) — useful when you want to:

• Run the REST API against an existing Elasticsearch cluster (and optionally Kafka), or bring up only the minimum infra it needs.
• Serve calibration, sensor, behavior, alerts, events, tracking, incident, and metrics endpoints.

Required host runtime: Docker Engine 28.3.3 with Docker Compose plugin v2.39.1+.

What you edit

You only edit the existing service compose:

<repo>/deploy/docker/services/analytics/video-analytics-api/compose.yml

1. command: — which config file the Node server loads at startup.
2. volumes: — what config (required) and what data-log directory (optional) to mount.

Walk steps 1-3 below to decide each one; the bring-it-up command lives in Deploy + verify at the end. For a field-by-field JSON config reference, see the Configuration Guide.

Step 1 — Choose a config (required)

Every startup requires --config <path>. The container has three viable sources:

Option A — Use the image-baked default

Cheapest path. The image ships a default config at /configs/default-configs/config.json. To use it, change the command: and drop the config volume mount:

command: node index.js --config /configs/default-configs/config.json

The defaults assume:

• Elasticsearch at http://localhost:9200
• Index prefix mdx-
• Kafka disabled (empty brokers list)
• Server port 8081

Option B — Use the service-shipped config (default in compose)

The base compose already mounts the config from the services directory:

services/analytics/video-analytics-api/configs/vss-video-analytics-api-config.json

This config is identical to the image-baked default except Kafka is enabled (brokers: ["localhost:9092"]). This is the right choice when you have a local Kafka broker running. If Kafka is absent, the server can still start once Elasticsearch is healthy, but Kafka-dependent endpoints will fail until a broker becomes reachable. Use Option A or a custom config with kafka.brokers: [] for a quiet broker-less deployment.

No compose change needed — this is the default:

services:
  vss-video-analytics-api:
    volumes:
      - $VSS_APPS_DIR/services/analytics/video-analytics-api/configs/vss-video-analytics-api-config.json:/opt/mdx/vss-video-analytics-api/configs/vss-video-analytics-api-config.json
    command: node index.js --config /opt/mdx/vss-video-analytics-api/configs/vss-video-analytics-api-config.json

Option C — Use your own custom config

Drop in any absolute host path; copy one of the above as a starting point and edit. Compose change:

volumes:
  - /abs/path/to/my-config.json:/opt/mdx/vss-video-analytics-api/configs/vss-video-analytics-api-config.json
command: node index.js --config /opt/mdx/vss-video-analytics-api/configs/vss-video-analytics-api-config.json

Config — what's in it

Top-level shape:

Step 2 — Data log volume

The compose mounts a data-log directory for multipart upload handling and file-backed assets such as calibration images:

volumes:
  - $VSS_DATA_DIR/data_log/vss_video_analytics_api:/web-api-app/files

If you keep this mount, set $VSS_DATA_DIR to a writable host path and pre-create the subdirectory before docker compose up:

export VSS_DATA_DIR=<path-to-data-directory>  # e.g. /tmp/vss-data
mkdir -p "$VSS_DATA_DIR/data_log/vss_video_analytics_api"

If you don't need image upload endpoints, you can drop this mount — the container will still start, but uploaded images will write to the container's ephemeral filesystem.

Step 3 — Infrastructure dependencies

Elasticsearch (required)

The server pings Elasticsearch on startup. If ES is unreachable, the server logs [APP ERROR] Server initialization failed and exits. The restart: always policy in the base compose brings it back, so docker ps may show a Restarting (N) loop until ES is reachable.

Make sure the elasticsearch.node in your config matches the running ES instance. With network_mode: "host", ES must also be on the host network.

If you need to bring up Elasticsearch too, use the infra compose:

docker compose -f services/infra/compose.yml up -d elasticsearch

Wait for ES to be healthy before starting the API:

curl -sf http://localhost:9200/_cluster/health

Kafka (optional)

Kafka is optional. If kafka.brokers is empty or null in the config, the server skips Kafka entirely — no error, no retry loop.

When brokers are configured and reachable, the API gains:

• Dynamic config — produces/consumes config update notifications on mdx-notification (Kafka key behavior-analytics-config). This is how the UI pushes config changes to behavior-analytics through the API.
• Dynamic calibration — produces calibration update notifications on mdx-notification (Kafka key calibration).
• RTLS / AMR — consumes real-time location and AMR messages from mdx-rtls / mdx-amr topics and exposes them via REST.

If brokers are configured but unreachable, the server still starts (ES must be up), but Kafka-dependent endpoints will fail. If you want the API to run broker-less without Kafka connection errors, set kafka.brokers to an empty array ([]) or null.

How profiles use this service

Every profile extends the same base service and adds its own depends_on and profiles constraints. The config is always the same service-shipped config — no profile overrides it:

The import-calibration-output-container in warehouse profiles depends on the video-analytics-api service — it POSTs calibration data to the API after startup.

REST API endpoints

The server auto-discovers controllers from src/app/controllers/rest-apis/ and mounts them as routes. Available endpoints:

The server must initialize against Elasticsearch before /livez can return healthy. Data-query endpoints also need matching Elasticsearch indices and data. Endpoints that publish notifications (config, calibration) or expose RTLS / AMR streams also require Kafka.

Deploy + verify

cd <repo>/deploy/docker
docker --version        # need 28.3.3
docker compose version  # need v2.39.1+

export VSS_APPS_DIR=$(pwd)
export VSS_DATA_DIR=<path-to-data-directory>  # e.g. /tmp/vss-data
mkdir -p "$VSS_DATA_DIR/data_log/vss_video_analytics_api"

# (one-time) edit services/analytics/video-analytics-api/configs/vss-video-analytics-api-config.json if needed.

docker compose -f services/analytics/video-analytics-api/compose.yml up -d vss-video-analytics-api

docker ps --filter "name=vss-video-analytics-api" --format '{{.Names}}\t{{.Status}}'
# Compose auto-names the standalone container <project>-<service>-<index>; project defaults to
# the compose file's parent dir, so the full name is:
docker logs -f video-analytics-api-vss-video-analytics-api-1

Healthy log lines include:

{"timestamp":"...","level":"info","message":"[SERVER] Listening on port: 8081"}

Verify the health endpoint:

curl -sf http://localhost:8081/livez && echo "OK" || echo "DOWN"

If Elasticsearch is not yet up, you'll see:

{"timestamp":"...","level":"error","message":"[ELASTICSEARCH RETRY] attempt=1"}

The process retries until ES is reachable, up to the configured elasticsearch.retries count. If retries are exhausted, the app exits and restart: always starts a fresh cycle. This is expected when you bring up the API before ES; otherwise start ES and the next restart cycle will connect.

Teardown

docker compose -f services/analytics/video-analytics-api/compose.yml down

For a multi-service teardown (broker, ES, etc.), use the vss-deploy-profile teardown workflow.

Troubleshooting

Inspect a mounted config inside the container (same path as command: node index.js --config …):

docker exec video-analytics-api-vss-video-analytics-api-1 node -e \
  "const fs=require('fs'); const p='/opt/mdx/vss-video-analytics-api/configs/vss-video-analytics-api-config.json'; console.log(JSON.stringify(JSON.parse(fs.readFileSync(p,'utf8')), null, 2))"

With compose (standalone deploy):

docker compose -f services/analytics/video-analytics-api/compose.yml \
  exec vss-video-analytics-api node -e \
  "const fs=require('fs'); const p='/opt/mdx/vss-video-analytics-api/configs/vss-video-analytics-api-config.json'; console.log(JSON.stringify(JSON.parse(fs.readFileSync(p,'utf8')), null, 2))"