Docker Compose Deployment Guide#

This guide walks through deploying CDS using Docker Compose for local development and testing.

Prerequisites#

Before proceeding, ensure you have completed the Docker Compose Prerequisites, including the following:

  • Docker and NVIDIA Container Toolkit installed

  • NGC authentication configured

  • Environment variables set or persisted

  • LocalStack hostname mapping added to /etc/hosts

Overview#

Docker Compose deployment provides a complete CDS stack running on a single node. This deployment method is ideal for the following use cases:

  • Local development and testing

  • Evaluating CDS capabilities

  • Small-scale deployments

  • Prototyping and experimentation

The deployment includes all required services: CDS API, Cosmos-embed NIM, Milvus vector database, LocalStack S3 storage, and the React web UI.

Time Estimate: The first deployment will take 15-30 minutes because of model downloads. Subsequent deployments take 2-5 minutes.

Deployment Steps#

Step 1: Clone the Repository#

Clone the CDS repository and navigate to the project directory:

# Clone the repository
git clone https://github.com/NVIDIA-Omniverse-blueprints/cosmos-dataset-search
cd cosmos-dataset-search

# Verify you're in the correct directory
ls -la
# You should see Makefile, pyproject.toml, and other project files

Step 2: Review Milvus Configuration (Optional)#

CDS includes multiple Milvus configuration files:

The following optimizations are included in the milvus_localstack.yaml configuration file:

  • GPU memory configuration for shared GPU with Cosmos-Embed

  • Storage V2 enabled with full configuration for better reliability

  • LocalStack S3 endpoints pre-configured

  • Automatic startup ordering for reliable Milvus startup (Cosmos-Embed → Milvus)

To switch to the official Milvus config, edit the deploy/standalone/docker-compose.build.yml file:

milvus:
  volumes:
    # Option 1: Use LocalStack-optimized config (default, recommended)
    - ./milvus_localstack.yaml:/milvus/configs/milvus.yaml
    
    # Option 2: Use official Milvus config (requires manual LocalStack setup)
    # - ./milvus_official.yaml:/milvus/configs/milvus.yaml

If you’re using milvus_official.yaml, you MUST manually configure the following settings:

  • S3/LocalStack settings (minio.address: localstack, minio.port: 4566)

  • GPU memory allocation (gpu.initMemSize, gpu.maxMemSize)

  • Storage scheme (common.storage.scheme: s3)

For more details on GPU memory configuration, refer to the GPU Memory Management Guide (/guides/gpu-memory-management.md).

Step 3: Configure Environment Variables#

CDS uses a .env file to manage all required environment variables. Start by copying the provided template:

# Copy the environment template
cp deploy/standalone/.env.example deploy/standalone/.env

Edit the .env file and update the following required variables:

# Edit the .env file with your preferred editor
nano deploy/standalone/.env
# or
vi deploy/standalone/.env

Update the following required variables:

  1. NVIDIA_API_KEY - Add the NGC API key (obtained from NGC)

    NVIDIA_API_KEY=<your-NGC-API-key>

  2. DATA_DIR - Add the path to your data directory (e.g., $HOME/cds-data)

    DATA_DIR=/path/to/your/data

    Important

    This directory must exist before proceeding. Create it if it doesn’t exist:

    mkdir -p $HOME/cds-data

    This folder is used to enable faster LocalStack uploads by providing direct file system access to the containerized S3 service.

The following are the default variables. Typically, no changes are needed for local deployment:

  • AWS_ACCESS_KEY_ID=test (for LocalStack)

  • AWS_SECRET_ACCESS_KEY=test (for LocalStack)

  • AWS_ENDPOINT_URL=http://localstack:4566

  • COSMOS_EMBED_NIM_URI=http://cosmos-embed:8000

  • GUNICORN_PORT=8888

Optional Variables for Remote Access#

  • Web UI Configuration - Update the following variables if accessing the UI from a different host (not localhost). If your web browser is running on a different machine than the CDS deployment (for example, deploying on a remote server and accessing from your laptop), you need to update these three variables with your deployment host IP address or hostname.

    • CDS_API_URL: API endpoint URL for the web UI

      CDS_API_URL=http://<deployment-host-ip>:8888/v1

    • CDS_CDN_URL: CDN URL for serving media assets (LocalStack S3)

      CDS_CDN_URL=http://<deployment-host-ip>:4566/cosmos-test-bucket

    • CDS_UI_URL: The base URL for the Web UI

      CDS_UI_URL=http://<deployment-host-ip>:8080/

The following are example variables for remote access (deploying on a server with IP 192.168.1.100):

CDS_API_URL=http://192.168.1.100:8888/v1
CDS_CDN_URL=http://192.168.1.100:4566/cosmos-test-bucket
CDS_UI_URL=http://192.168.1.100:8080/

For a complete list of configuration options, refer to the comments in the .env file.

Step 4: Validate Environment Configuration#

Before proceeding, validate your environment configuration:

# Run the validation script
bash deploy/standalone/scripts/validate_env.sh

This script will perform the following checks:

  • Verify that all required variables are set.

  • Check that API keys are not placeholder values.

  • Validate port numbers, URIs, and other settings.

  • Provide helpful error messages if issues are found.

The script should complete with “Environment validation completed successfully.” If validation fails, review the error messages and update your .env file accordingly, then run the validation script again.

Step 5: Install Dependencies#

Install Python dependencies and set up the development environment using the following command:

make install

This command will perform the following steps:

  • Create a Python virtual environment using UV.

  • Install all Python dependencies with GPU support.

  • Generate protobuf definitions for service communication.

  • Set up the complete development environment.

The command should complete without errors. Look for messages about dependency installation and protobuf generation.

Step 6: Build Docker Images#

Build all required Docker images:

make build-docker

This command will build the following images:

  • Python base image with CUDA support

  • CDS service image

  • Supporting service images

Time Estimate: The first build will take 10-20 minutes. Subsequent builds use Docker cache and are much faster (1-2 minutes).

Step 7: Launch Services#

Start the complete CDS stack with the following command:

make test-integration-up

This command will perform the following steps:

  • Start Milvus vector database with etcd.

  • Launch Cosmos-embed NIM service (GPU-accelerated).

  • Start the CDS API service.

  • Launch LocalStack S3-compatible storage.

  • Start React Web UI.

  • Wait for all services to become healthy.

Note the following about the launch process:

  • Startup time on first run: Cosmos-embed NIM will download model weights (~20GB) on first run. This will take 10-15 minutes, depending on your Internet connection.

  • GPU check: The NIM service requires GPU access. If it fails to start, verify your GPU setup with nvidia-smi.

  • Monitoring progress: Monitor the logs to track model download and service startup.

Expected Launch Results#

The results from a successful deployment should match the following:

Starting services...
cd deploy/standalone && docker compose -f docker-compose.build.yml up -d
[+] Running 1/1
 ✔ validate-env Pulled                                                                                                                     1.5s
[+] Running 7/7
 ✔ Container milvus-etcd                Healthy                                                                                            1.2s
 ✔ Container localstack                 Healthy                                                                                            1.2s
 ✔ Container milvus                     Healthy                                                                                            4.9s
 ✔ Container standalone-validate-env-1  Exited                                                                                             0.7s
 ✔ Container cosmos-embed               Healthy                                                                                           64.2s
 ✔ Container visual-search              Started                                                                                            0.2s
 ✔ Container cosmos-vds-web-ui          Started                                                                                            0.2s

----------------------------------------
Waiting for services to be ready...
This may take a few minutes for GPU services to initialize...
python scripts/wait_for_services.py
INFO:__main__:Waiting for services: milvus, cosmos-embed, visual-search, react-ui
INFO:__main__:Checking milvus at http://localhost:9091/healthz
INFO:__main__:milvus is ready
INFO:__main__:Checking cosmos-embed at http://localhost:9000/v1/health/ready
INFO:__main__:cosmos-embed is ready
INFO:__main__:Checking visual-search at http://localhost:8888/health
INFO:__main__:visual-search is ready
INFO:__main__:Checking react-ui at http://localhost:8080/
INFO:__main__:react-ui is ready
INFO:__main__:All services are ready!
INFO:__main__:Service check completed in 18.24s
INFO:__main__:All services are ready for testing!

Check the UI at http://localhost:8080/cosmos-dataset-search

Monitoring Startup#

Use the following commands to monitor the startup process:

# View logs in real-time
make test-integration-logs

# Or view specific service logs
docker compose -f deploy/standalone/docker-compose.build.yml logs -f cosmos-embed

Step 8: Verify Deployment (Optional)#

Once all services are running, you can optionally verify each component service manually:

# Check service health
curl http://localhost:8888/health

# Expected response: "OK"

# Check Cosmos-embed NIM
curl http://localhost:9000/v1/health/ready

# Expected response: {"status":"ready"}

# List available embedding pipelines
curl http://localhost:8888/v1/pipelines

# Expected response: JSON list of available pipelines

# Check UI is responding
curl http://localhost:8080/cosmos-dataset-search

All health checks should return successful responses. If any service fails, refer to the Troubleshooting section.

Step 9: Install and Configure the CDS CLI#

Install the CDS command-line interface for data ingestion and management.

Note: This step is required for the commands in the Testing the Deployment section below.

# Install CDS CLI
make install-cds-cli

# Activate the virtual environment
source .venv/bin/activate

# Verify CLI installation
cds --help

# Configure CLI to connect to local deployment
cds config set
# When prompted, enter: http://localhost:8888

# Verify configuration
cds pipelines list

Accessing the Services#

Web UI#

Access the interactive web interface at the following URL:

http://localhost:8080/cosmos-dataset-search

The web browser must be running on the localhost for access to succeed.

The web UI provides the following:

  • Text-to-video and video-to-video search interface

  • Collection browsing and management

  • Real-time search results with video previews

  • Data curation tools

Note

You’ll need to create a collection and ingest data before performing searches. Refer to the Testing the Deployment section below for more information.

API Documentation#

Interactive API documentation (using the Swagger UI) is available at the following URL:

http://localhost:8888/v1/docs

This provides a complete API reference with interactive request testing. For detailed API usage, refer to the API Reference sction.

Testing the Deployment#

Quick Verification Test#

Run the built-in integration tests to verify all services are functioning correctly:

make test-integration-run

This command will perform the following steps:

  • Minimal integration test validating service communication

  • Cosmos video end-to-end test verifying embedding generation

All tests should pass. This confirms the deployment is working correctly.

Ingest Sample Data#

Test data ingestion with a small sample dataset:

# Ingest 100 videos from MSR-VTT dataset for testing
make ingest-msrvtt-small

This command ingests a small subset of videos for quick testing using the following steps:

  1. Download videos from the dataset

  2. Upload to LocalStack S3 storage

  3. Process videos through the embedding pipeline

  4. Index embeddings in Milvus

The ingestion process will take 5-10 minutes for 100 videos, depending on your system.

Use the following command for a more comprehensive test with the full dataset:

make ingest-msrvtt

Verify Data Ingestion#

After ingestion completes, validate the data using the following commands:

# List collections (should show the newly created collection)
curl http://localhost:8888/v1/collections

# Or use the CLI
cds collections list

# Perform a test search
cds search --collection-ids <collection-id> \
  --text-query "person walking" \
  --top-k 5

Test via Web UI#

Open the web UI at http://localhost:8080/cosmos-dataset-search and perform the following steps:

  1. Select the ingested collection.

  2. Enter a text query (e.g., “person walking”, “cat playing”).

  3. View the search results with video previews.

  4. Try video-to-video search by uploading a query video.

Managing the Deployment#

Data Persistence#

All data ingested into CDS is ephemeral and will be lost when services are stopped and restarted. This includes all collections, ingested videos, and embeddings. You will need to re-ingest your data after restarting the services.

Stopping and Restarting Services#

Use the following command to stop all running services:

make test-integration-down

Use the following command to restart services:

make test-integration-up

Note

After restarting, all previous data will be deleted. You must re-ingest your datasets.

Clean Restart (Rebuild Images)#

Use the following command to stop services and also remove Docker images, forcing a rebuild on next startup:

# Stop services and remove images
make test-integration-clean

# Restart and rebuild
make test-integration-up

Use make test-integration-clean when you want to clear cached images and ensure a fresh build on the next startup.

Advanced Management#

For detailed service management, including viewing logs, restarting individual services, and advanced configuration options, refer to the CDS User Guide.

Service Endpoints Reference#

Service

Endpoint

Purpose

CDS API

http://localhost:8888

REST API for search operations

API Documentation

http://localhost:8888/v1/docs

Interactive API docs (Swagger)

Cosmos-embed NIM

http://localhost:9000

Embedding service

Milvus Database

localhost:19530

Vector database (internal)

LocalStack S3

http://localhost:4566

S3-compatible storage (internal)

Web UI

http://localhost:8080/cosmos-dataset-search

Interactive web interface

Troubleshooting#

If you encounter issues during deployment or operation, refer to the Docker Compose Troubleshooting Guide for detailed solutions to common problems.

Next Steps#

After successfully deploying CDS, proceed to the CDS User Guide to learn how to interact with CDS. The user guide covers three interaction methods: