Run With Docker Compose#

Use this path to run the service in a container. The API is exposed on port 8082. To rebuild the image from source, see build-from-source.md.

Before You Start#

  • Prepare your scene-config.yaml and rules.yaml in a local ./configs directory. For configuration details, see configuration.md.

  • Make sure a Scenescape deployment (MQTT broker + REST API) is reachable from the container, and that the mqtt / scenescape_api blocks in scene-config.yaml point at it.

  • If mqtt.use_tls: true, mount your Scenescape CA cert at /app/secrets.

Select the Image (Registry and Tag)#

The bundled docker-compose.yml resolves the image from two variables:

image: ${REGISTRY:-intel}/scene-understanding-service:${RELEASE_TAG:-latest}

Pin a specific release by setting them in a .env file next to docker-compose.yml (both fall back to intel / latest when unset):

# .env
REGISTRY=intel
RELEASE_TAG=2026.2.0-rc1

Compose loads .env automatically. Confirm the resolved image before starting:

docker compose config | grep image

Minimal Compose Service#

services:
  scene-understanding-service:
    image: intel/scene-understanding-service:latest
    ports:
      - "8082:8082"
    environment:
      STORE_ID: my_store_01
      SCENESCAPE_API_USER: admin
      SCENESCAPE_API_PASSWORD: ${SCENESCAPE_API_PASSWORD}
    volumes:
      - ./configs:/app/configs:ro          # scene-config.yaml + rules.yaml (required)
      - ./results:/app/results             # optional: persisted results/evidence
    restart: unless-stopped

For tighter isolation you can mount only the two files the service reads:

    volumes:
      - ./configs/scene-config.yaml:/app/configs/scene-config.yaml:ro
      - ./configs/rules.yaml:/app/configs/rules.yaml:ro

Full Integration#

When your stack includes a SeaweedFS frame store, a behavioral-analysis worker, and an alert-service, add the seaweedfs and alert_service blocks to scene-config.yaml and place the services on a shared Docker network so they resolve each other by container name. Behavioral analysis is integrated over MQTT (topics ba/requests / ba/results) — no direct URL wiring is needed.

Start#

docker compose up -d

Check Status#

docker compose ps
curl --noproxy '*' http://127.0.0.1:8082/health
curl --noproxy '*' http://127.0.0.1:8082/api/v1/sus/status

Follow Logs#

docker compose logs -f scene-understanding-service

Restart#

If you changed only the config files:

docker compose restart scene-understanding-service

For a clean restart:

docker compose down
docker compose up -d

Stop#

docker compose down

API Use Cases and Examples#

For endpoint details and examples, see the API Reference.

Notes#

  • Container host port: 8082; API base path: /api/v1/sus.

  • The service reads scene-config.yaml and rules.yaml from /app/configs (override with CONFIG_DIR). A mounted ./configs volume overrides the bundled samples.

  • There is no hard startup dependency on Scenescape — the service starts and retries the MQTT connection in the background.

  • Use GET /api/v1/sus/status (or GET /health) for readiness gating in depends_on.