Skip to main content

Docker CPU

Docker Compose installation without GPU acceleration.

Who this is for​

Use this path when you want to run Toposync isolated in a container.

The default image is:

ghcr.io/toposync/toposync:0.8.0

It includes the toposync-streaming bundle, FFmpeg, bundled go2rtc, and the minimum RF-DETR local build toolchain. You do not need a repository checkout for the normal install path.

For architecture support, see Compatibility.

Prerequisites​

  • Docker.
  • Docker Compose.

Installation​

Create a deployment directory and a Compose file:

docker-compose.yml
services:
  toposync:
    image: ghcr.io/toposync/toposync:0.8.0
    ports:
      - "${TOPOSYNC_PORT:-8000}:8000"
    volumes:
      - ${TOPOSYNC_DATA_VOLUME:-./toposync-data}:/data
    restart: unless-stopped

Start Toposync:

docker compose up -d

If you are using the repository checkout, the root docker-compose.yml already uses the same public image by default.

By default:

  • public port: 8000;
  • data directory on the host: ./toposync-data;
  • data directory in the container: /data.

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

Change the data directory:

TOPOSYNC_DATA_VOLUME=/path/to/toposync-data 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​

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

Expected result:

  • / returns 200;
  • /api/health returns 200;
  • /api/auth/status returns JSON and may report requires_setup: true on first access.

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

First camera and streaming​

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

If you do not have a real camera ready, start with the synthetic RTSP path:

That guide starts a local RTSP source, adds it as a manual camera, starts the streaming engine, reconciles live publications, and confirms the Live cameras view.

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.

Advanced: local build​

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

docker compose -f docker-compose.yml -f docker-compose.local-build.yml up -d --build

This builds toposync:local 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​

Port 8000 is already in use​

Use another host port:

TOPOSYNC_PORT=8080 docker compose up -d

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 need GPU acceleration​

This guide is CPU-only. For NVIDIA in Docker, use the Docker CUDA guide.