Pular para o conteúdo principal

Docker CUDA

Instalação com Docker Compose para Linux com GPU NVIDIA.

Para Quem É​

Use este caminho quando quiser rodar o Toposync em container com aceleração NVIDIA CUDA para vision.

A imagem CUDA padrão é:

ghcr.io/toposync/toposync:0.8.0-cuda

Ela instala o bundle toposync-vision-cuda mais a extensão de streaming, FFmpeg, go2rtc embutido e o mesmo tooling básico de runtime da imagem CPU. Ela não instala o bundle CPU toposync-streaming, evitando puxar o runtime CPU de ONNX junto do bundle CUDA.

Para suporte por arquitetura e alternativas no Windows, consulte Compatibilidade.

Pré-requisitos​

  • Linux com GPU NVIDIA.
  • Driver NVIDIA instalado no host.
  • Docker.
  • Docker Compose.
  • NVIDIA Container Toolkit configurado.

Verifique se o Docker enxerga a GPU:

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

Se esse comando falhar, corrija o driver ou o NVIDIA Container Toolkit antes de subir o Toposync.

Instalação​

Crie uma pasta de deploy e um arquivo Compose:

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

Suba o Toposync:

docker compose up -d

Se você estiver usando o checkout do repositório, use os arquivos Compose já incluídos:

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

Por padrão:

  • porta pública: 8000;
  • pasta de dados no host: ./toposync-data;
  • pasta de dados no container: /data;
  • bundle instalado: toposync-vision-cuda;
  • extensão de streaming: instalada.

Como Rodar​

Subir:

docker compose up -d

Parar:

docker compose stop

Ver logs:

docker compose logs -f toposync

Alterar porta pública:

TOPOSYNC_PORT=8080 \
docker compose up -d

Como Acessar​

No host:

http://127.0.0.1:8000/

Na rede local:

http://<ip-do-servidor>:8000/

Como Verificar​

Verifique a 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

Verifique a GPU dentro do container:

docker compose exec toposync nvidia-smi

O esperado:

  • / responde 200;
  • /api/health responde 200;
  • /api/auth/status responde JSON e pode indicar requires_setup: true no primeiro acesso;
  • nvidia-smi mostra a GPU dentro do container.

Depois de concluir o setup/login pela UI, a API autenticada passa a responder as rotas protegidas, como /api/extensions.

Streaming​

Streaming já vem incluído na imagem CUDA pública. O FFmpeg está no PATH, e o go2rtc fica embutido em /usr/local/bin/go2rtc.

Como Atualizar​

Baixe a nova imagem e recrie o container:

docker compose pull
docker compose up -d

Para uma release fixa, pinne a tag exata no docker-compose.yml, por exemplo ghcr.io/toposync/toposync:0.8.0-cuda.

Avançado: build local​

Use o caminho de build local apenas quando estiver desenvolvendo o Toposync a partir de um checkout do repositório ou testando mudanças ainda não publicadas:

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

Isso cria o target runtime-cuda a partir do Dockerfile do monorepo em vez de puxar a imagem pública do GHCR.

Como Desinstalar​

Parar e remover o container:

docker compose down

Remover também os dados locais:

rm -rf ./toposync-data

Troubleshooting​

Docker não enxerga a GPU​

Teste:

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

Se falhar, o problema está no host: driver NVIDIA, Docker ou NVIDIA Container Toolkit.

Container não fica saudável​

Veja os logs:

docker compose logs -f toposync

Teste o healthcheck:

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

Estou no Windows​

Para Windows, prefira instalação nativa com toposync-vision-directml ou o processing server como serviço. Docker CUDA é tratado aqui como caminho Linux + NVIDIA.