Use Pre-Built Docker Images#

This guide explains how to deploy ViPPET using pre-built Docker images, without building the application components from source. It is the fastest way to get a working local environment for evaluation, demos, and API exploration.

Prerequisites#

Before starting, ensure the following:

  • System requirements: The system meets the minimum requirements.

  • Internet access: The host has outbound internet connectivity. Container images, sample videos, models, and the Python packages used by the model-download service are downloaded on first start. Offline or air-gapped installation is not supported. See Network Requirements.

  • Docker platform: Docker Engine is installed. On Linux, install it from the Docker apt repository, see Install Docker Engine on Ubuntu, then complete the post-installation steps to run Docker as a non-root user.

    Note

    Do not use Docker Desktop on Linux. It runs the Docker daemon inside a virtual machine that is not forwarding GPU device on Linux (yet).

  • Dependencies installed:

    • Make: Standard build tool, typically provided by the build-essential (or equivalent) package on Linux.

    • curl: Command-line tool for transferring data with URLs, typically provided by the curl package on Linux.

For GPU and/or NPU usage, appropriate drivers must be installed. The recommended method is to use the DLS installation script, which detects available devices and installs the required drivers. Follow the Prerequisites section in Install Guide Ubuntu - Prerequisites.

Note

The same steps apply to Ubuntu 24.04 running under WSL 2 on Windows - run all commands inside the WSL distribution. On WSL, only the CPU and GPU (WSL) variants are supported. See System Requirements.

This guide assumes basic familiarity with terminal usage.

Before starting the setup, review the Pre-Installation Steps for optional configuration such as the Hugging Face access token used to download models from the Hugging Face Hub.

Setup#

Follow the steps below to quickly set up the environment and start the Visual Pipeline and Platform Evaluation Tool. For alternative ways to set up the sample application, refer to How to Build from Source.

  1. Clone the repository:

    git clone -b main --sparse --filter=blob:none https://github.com/open-edge-platform/edge-ai-libraries.git
    cd edge-ai-libraries
    git sparse-checkout set tools/visual-pipeline-and-platform-evaluation-tool
    cd tools/visual-pipeline-and-platform-evaluation-tool
    
  2. Pull the pre-built images and start the application:

    make run-prebuilt
    

    This target automatically:

    • runs setup_env.sh to detect available hardware (CPU/GPU/NPU) and write .env,

    • creates the required directories under shared/,

    • pulls the pre-built images (vippet-app, vippet-ui, sensor-manager, model-download, metrics-manager, mediamtx) and starts all services.

    On the main branch the images tagged latest are used; on a release branch, the images of that release. To run a different published tag, for example a weekly build listed on Docker Hub, use make run-prebuilt PREBUILT_TAG=<tag>.

    To stream from GigE Vision cameras, add GIGE=1 (make run-prebuilt GIGE=1), see GigE Vision Cameras.

    make run-prebuilt never builds images from source: if an image cannot be pulled, the command fails. make run is the build-from-source path, see Build from Source.

  3. Verify that the application is running:

    docker compose ps
    
  4. Access the application:

    Open a browser and navigate to http://localhost (or http://<HOST-IP>) to access the Visual Pipeline and Platform Evaluation Tool UI.

  5. Access the application API documentation:

    Open a browser and navigate to http://localhost/api/v1/docs (or http://<HOST-IP>/api/v1/docs) to access the Swagger UI.

Note

On the first start the model-download service may take several minutes to become healthy because it provisions its plugin virtual environments. The other services wait for it automatically. Package downloads use a 300-second HTTP timeout by default. Set UV_HTTP_TIMEOUT before startup to override it for slower or faster networks.

Stop the application#

Stop and remove all running containers:

make stop

Downloaded models and videos under shared/ are preserved. To also remove those artifacts, run:

make clean