Deploy Scenescape on Docker#

This guide deploys a clean Scenescape instance with Docker Compose: an empty scene database, without the bundled demo video sources or preloaded demo scenes. To run the demo instead, see Deploy the Demo.

Time to Complete: 15-30 minutes

Prerequisites#

Verify you meet the System Requirements, including Docker.
A checkout of the Scenescape repository (see Get Scenescape).
Complete Preparation for source-built or prebuilt images.

Deploy#

Before deploying for the first time, set the SUPASS environment variable to the super user password for logging into Scenescape. This should be different from your system user’s password:

export SUPASS='<choose-a-strong-admin-password>'

Then, from the repository root, start the default Controller + Analytics deployment:

make deploy

make deploy regenerates docker-compose.yml and .env on every invocation, overwriting edits to those files, then starts the controller profile. It requires SUPASS for the initial administrator account. Image, secret, and model preparation is covered in Preparation.

If you want to keep persistent Compose customizations, such as a different Mapping image, in a separate override file and pass it through DEPLOY_COMPOSE_ARGS:

make deploy DEPLOY_COMPOSE_ARGS='-f docker-compose.yml -f docker-compose.custom.yml'

The generated .env is also overwritten on each run. Keep custom environment values in the shell or a separate env file and pass that file with DEPLOY_COMPOSE_ARGS='--env-file .env.custom -f docker-compose.yml -f docker-compose.custom.yml'.

This starts the Scenescape core: the web application, database, broker, NTP server, Scene Controller, Analytics, and Auto Camera Calibration. It does not start the separate demo video-source stack, and it does not upload any demo scenes.

Verify the containers are running:

docker compose --profile controller ps

Verify a Successful Deployment#

If you are running remotely, connect using https://<ip_address> or https://<hostname>, using the correct IP address or hostname of the remote Scenescape system. If accessing on a local system, use https://localhost. If you see a certificate warning, click the prompts to continue to the site. For example, in Chrome click “Advanced” and then “Proceed to <ip_address> (unsafe)”.

Note: These certificate warnings are expected due to the use of a self-signed certificate for initial deployment purposes. This certificate is generated at deploy time and is unique to the instance.

Sign in as admin with the password assigned to SUPASS.

The scene list is empty. Import or create your own scene and configure its cameras and analytics inputs before expecting detections or tracks; see Build a Scene.

Docker Compose Profiles#

Scenescape uses Docker Compose profiles to organize services into logical groups. When starting or stopping services, you must specify the same profile(s) used during deployment.

The following profiles are available:

Profile	Description
`controller`	Scene Controller (tracking) + Analytics service. Used by this guide and `make demo`.
`mapping`	Enables mapping service.
`cluster-analytics`	Enables cluster-analytics service.
`tracker`	Tracker service + Analytics service (no Scene Controller). Used by `make demo-tracker`.

ReID backends: For raw Compose, add exactly one of sample_data/compose/compose.vdms-override.yml or sample_data/compose/compose.qdrant-override.yml. Both overrides provide the same logical reid service, shared host reid.scenescape.intel.com, port 55555, TLS settings, and certificates. See Selecting the ReID Vector Database Backend.

Profiles can be specified on the command line with --profile:

docker compose --profile controller up -d

Multiple profiles can be combined:

docker compose --profile controller --profile mapping up -d

Alternatively, profiles can be set via the COMPOSE_PROFILES environment variable:

export COMPOSE_PROFILES=controller
docker compose up -d

For multiple profiles, use a comma-separated list:

export COMPOSE_PROFILES=controller,mapping
docker compose up -d

(Optional) Select the Mapping Model#

This section is applicable only when mapping profile is selected)

Each Mapping image contains exactly one 3D reconstruction model, fixed at build time. The mapping service in docker-compose.yml uses intel/scenescape-mapping:${VERSION}, which is MapAnything. To run VGGT, change its image to intel/scenescape-mapping:${VERSION}-vggt.

The selected variant must exist locally or on Docker Hub. The root make build-all builds only the default MapAnything image; build both variants with make -C mapping build-all (see Build Mapping Service from Source).

For more details, see the Docker Compose profiles documentation and the COMPOSE_PROFILES environment variable reference.

Note: The --profile flags used with docker compose down must match those used when starting the services. Otherwise, containers started under a specific profile will remain running.

Stopping and Starting#

To stop the containers, use the following command in the project directory (see Docker Compose Profiles for details on choosing profiles):

docker compose --profile controller down --remove-orphans

To start again after the first time:

docker compose --profile controller up -d