Deploy NeMo Safe Synthesizer with Docker#

Run the microservice on your local machine using Docker Compose for experimentation.

Prerequisites#

  • Docker and Docker Compose installed on your system.

  • Create an NGC API Key for accessing the NeMo Safe Synthesizer container from NGC Catalog

  • Install the NGC CLI

  • Ensure you have adequate RAM (16GB+ recommended) and disk space (20GB+ for Docker images and data) on your development environment

  • NVIDIA GPU with adequate VRAM for model inference (requirements vary by model, 80GB is recommended)

  • A build.nvidia.com API key (Free Trial available) for accessing NVIDIA-hosted language models

  • Make sure you have curl or a similar CLI tool to make HTTP requests

Launch NeMo Safe Synthesizer#

Authenticate with NGC#

Export the NGC API Key into your shell environment using the following command:

export NGC_CLI_API_KEY=<your-ngc-api-key>

Log in to the NVIDIA NGC container registry (following instructions at Getting Started with the NGC CLI):

echo $NGC_CLI_API_KEY | docker login nvcr.io -u '$oauthtoken' --password-stdin

Download the NeMo Safe Synthesizer Docker Compose Resources#

ngc registry resource download-version "nvidia/nemo-microservices/nemo-microservices-quickstart:25.10"
cd nemo-microservices-quickstart_v25.10

Set platform environment variables#

export NEMO_MICROSERVICES_IMAGE_REGISTRY=nvcr.io/nvidia/nemo-microservices
export NEMO_MICROSERVICES_IMAGE_TAG=25.10
export NIM_API_KEY=<build.nvidia.com-api-key> # Necessary for PII replacement to work properly

Start the Service#

docker compose -f docker-compose.yaml -f gpu/config.yaml --profile safe-synthesizer up

Verify Deployment#

Running the docker compose command starts the platform with NeMo Safe Synthesizer API running on http://localhost:8080.

Let’s check that all services are running properly.

docker compose ps --format '{{.Name}}\t{{.Status}}'

All containers with names prefixed nemo-microservices- should show “Up” with healthy status.

$ docker compose ps --format '{{.Service}}\t{{.Status}}'
datastore       Up 8 minutes (healthy)
docker  Up 8 minutes (healthy)
entity-store    Up 8 minutes (healthy)
envoy-gateway   Up 8 minutes
fluentbit       Up 8 minutes
jobs-api        Up 8 minutes (healthy)
jobs-controller Up 7 minutes
minio   Up 8 minutes (healthy)
openbao Up 8 minutes
postgres        Up 8 minutes (healthy)
safe-synthesizer        Up 7 minutes (healthy)

Note

Services may take several minutes to become fully available.

Test the API#

Test the jobs API:

curl -X GET -H "Content-type: application/json" localhost:8080/v1beta1/safe-synthesizer/jobs

You should see an empty array [] if you have not created any jobs yet.

Create your First Dataset#

Run one of our tutorials to create your first dataset, such as the Safe Synthesizer 101 Tutorial

Stop the Service (Optional)#

After you finish generating data, you can stop the service (note that -v will delete any local data)

docker compose --profile safe-synthesizer down -v

Available Services#

Once running, these services are accessible:

Key NeMo Safe Synthesizer endpoints:

  • Create job: POST /v1beta1/safe-synthesizer/jobs

  • List jobs: GET /v1beta1/safe-synthesizer/jobs

  • Get job status: GET /v1beta1/safe-synthesizer/jobs/{job_id}

  • Cancel job: POST /v1beta1/safe-synthesizer/jobs/{job_id}/cancel

  • Get job logs: GET /v1beta1/safe-synthesizer/jobs/{job_id}/logs

  • List job results: GET /v1beta1/safe-synthesizer/jobs/{job_id}/results

  • Download result: GET /v1beta1/safe-synthesizer/jobs/{job_id}/results/{result_id}/download

  • Download evaluation report: GET /v1beta1/safe-synthesizer/jobs/{job_id}/results/evaluation_report/download

  • Download job summary: GET /v1beta1/safe-synthesizer/jobs/{job_id}/results/summary/download

  • Download result synthetic data GET /v1beta1/safe-synthesizer/jobs/{job_id}/results/synthetic_data/download

Troubleshooting#

Common issues and solutions:

Service Health Checks#

Check if all services are running:

docker compose ps

View Service Logs#

View logs for specific services:

# View all logs
docker compose logs -f

# View safe synthesizer API logs
docker compose logs -f safe-synthesizer

# View jobs controller logs
docker compose logs -f jobs-controller

# View jobs api logs
docker compose logs -f jobs-api

# View logs for most recent running or exited job container
# NOTE: The job may have been cleaned up, in which case this will return no results
docker compose exec -ti docker bash -c 'docker ps -a | grep "nss" | head -n 1 | cut -d " " -f1 | xargs docker logs -f'

Common Issues#

GPU Memory Issues: Ensure your GPU has adequate VRAM for the models you plan to use. Check GPU usage with nvidia-smi.

Port Conflicts: If port 8080 is already in use, change the port mapping in the services/envoy.yaml file.

Storage Space: Ensure you have adequate disk space for Docker images, models, and datasets (50GB+ recommended).

Network Issues: Verify Docker can access external networks for downloading models and datasets.

For more detailed troubleshooting, check the service logs and verify that you have met all prerequisites.