Skip to main content

Docker CUDA

Docker Compose installation for Linux with an NVIDIA GPU.

Who this is for​

Use this path when you want to run Toposync in a container with NVIDIA CUDA acceleration for vision.

The default CUDA image is:

ghcr.io/toposync/toposync:0.8.0-cuda

It installs the toposync-vision-cuda bundle plus the streaming extension, FFmpeg, bundled go2rtc, and the same basic runtime tooling as the CPU image. It does not install the CPU toposync-streaming bundle, so it avoids pulling the CPU ONNX Runtime stack alongside the CUDA bundle.

For architecture support and Windows alternatives, see Compatibility.

Prerequisites​

  • Linux with an NVIDIA GPU.
  • NVIDIA driver installed on the host.
  • Docker.
  • Docker Compose.
  • NVIDIA Container Toolkit configured.

Verify that Docker can see the GPU:

docker run --rm --gpus all nvidia/cuda:12.6.3-base-ubuntu24.04 nvidia-smi

If this command fails, fix the NVIDIA driver or NVIDIA Container Toolkit before starting Toposync.

Installation​

Create a deployment directory and a Compose file:

docker-compose.yml
services:
  toposync:
    image: ghcr.io/toposync/toposync:0.8.0-cuda
    ports:
      - "${TOPOSYNC_PORT:-8000}:8000"
    volumes:
      - ${TOPOSYNC_DATA_VOLUME:-./toposync-data}:/data
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              capabilities: [gpu]
              count: all
    restart: unless-stopped

Start Toposync:

docker compose up -d

If you are using the repository checkout, use the checked-in Compose files:

docker compose -f docker-compose.yml -f docker-compose.cuda.yml up -d

By default:

  • public port: 8000;
  • data directory on the host: ./toposync-data;
  • data directory in the container: /data;
  • installed bundle: toposync-vision-cuda;
  • streaming extension: installed.

How to run​

Start:

docker compose up -d

Stop:

docker compose stop

View logs:

docker compose logs -f toposync

Change the public port:

TOPOSYNC_PORT=8080 \
docker compose up -d

How to access​

On the host:

http://127.0.0.1:8000/

On the local network:

http://<server-ip>:8000/

How to verify​

Verify the API:

curl -I http://127.0.0.1:8000/
curl http://127.0.0.1:8000/api/health
curl http://127.0.0.1:8000/api/auth/status

Verify the GPU from inside the container:

docker compose exec toposync nvidia-smi

Expected result:

  • / returns 200;
  • /api/health returns 200;
  • /api/auth/status returns JSON and may report requires_setup: true on first access;
  • nvidia-smi shows the GPU inside the container.

After you complete setup or login in the UI, authenticated API routes such as /api/extensions become available.

Streaming​

Streaming is included in the public CUDA image. FFmpeg is available on PATH, and go2rtc is bundled at /usr/local/bin/go2rtc.

How to update​

Pull the new image and recreate the container:

docker compose pull
docker compose up -d

For a fixed release, pin the exact tag in docker-compose.yml, for example ghcr.io/toposync/toposync:0.8.0-cuda.

Advanced: local build​

Use the local build path only when you are developing Toposync from a repository checkout or testing unpublished changes:

TOPOSYNC_DOCKER_TARGET=runtime-cuda \
TOPOSYNC_LOCAL_IMAGE=toposync:local-cuda \
docker compose -f docker-compose.yml -f docker-compose.cuda.yml -f docker-compose.local-build.yml up -d --build

This builds the runtime-cuda target from the monorepo Dockerfile instead of pulling the public GHCR image.

How to uninstall​

Stop and remove the container:

docker compose down

Also remove the local data:

rm -rf ./toposync-data

Troubleshooting​

Docker cannot see the GPU​

Test:

docker run --rm --gpus all nvidia/cuda:12.6.3-base-ubuntu24.04 nvidia-smi

If this fails, the problem is on the host: NVIDIA driver, Docker, or NVIDIA Container Toolkit.

The container does not become healthy​

Check the logs:

docker compose logs -f toposync

Test the health endpoints:

curl http://127.0.0.1:8000/api/health
curl http://127.0.0.1:8000/api/auth/status

I am on Windows​

On Windows, prefer the native installation with toposync-vision-directml or the processing server as a Windows service. Docker CUDA is documented here as a Linux + NVIDIA path.