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.yamlandrules.yamlin a local./configsdirectory. 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_apiblocks inscene-config.yamlpoint 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 |
|---|---|---|
|
|
Shared Docker network name (see |
|
|
|
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.yamlandrules.yamlfrom/app/configs(override withCONFIG_DIR). A mounted./configsvolume 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(orGET /health) for readiness gating independs_on.