Is this page helpful?

Deploy NeMo Safe Synthesizer with Docker#

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

Prerequisites#

Before following this deployment guide, ensure that you have:

  • Sufficient disk space for generated artifacts (20GB+ for Docker images and data).

  • At least 16GB of available RAM.

  • An NVIDIA GPU with 80GB. Less VRAM is required for smaller models.

  • Docker and Docker Compose installed on your system.

  • An NGC API Key with access to the NGC Catalog and Model endpoints on build.nvidia.com. Create an NGC API key following the instructions at Generating NGC API Keys. Specify the NGC Catalog and Public API Endpoints permissions when you generate the key.

  • The NGC CLI installed. Refer to Getting Started with the NGC CLI for details on setup.

  • A tool such as curl 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.12"
cd nemo-microservices-quickstart_v25.12

Set platform environment variables#

export NEMO_MICROSERVICES_IMAGE_REGISTRY=nvcr.io/nvidia/nemo-microservices
export NEMO_MICROSERVICES_IMAGE_TAG=25.12
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 --detach --quiet-pull --wait

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.