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.3.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.

Docker Network#

The bundled docker-compose.yml attaches the service to the Scenescape Docker network so it can resolve the broker and REST API hostnames. The network is controlled by two variables (set them in .env or the shell):

Variable

Default

Description

SCENESCAPE_NETWORK_NAME

scenescape_scenescape

Shared Docker network name (see docker network ls).

SCENESCAPE_NETWORK_EXTERNAL

false

true requires the network to already exist.

With the default false, Compose creates the network if it is missing, or joins it if the Scenescape deployment already created it.

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.