Skip to main content

Processing server on Docker

Run a processing server in a container.

Who this is for​

Use this path when you want to run an isolated processing server with Docker.

The default image is:

ghcr.io/toposync/toposync:0.8.0

Use the CUDA image on Linux hosts with NVIDIA acceleration:

ghcr.io/toposync/toposync:0.8.0-cuda

For architecture and GPU support, see Compatibility.

Prerequisites​

  • Docker.
  • Docker Compose.
  • TCP access between the origin and the processing server. The default port is 49321.

Installation​

Pull the CPU image:

docker pull ghcr.io/toposync/toposync:0.8.0

For CUDA:

docker pull ghcr.io/toposync/toposync:0.8.0-cuda

How to run​

Docker run​

Without Basic Auth:

docker run --rm -d \
  --name toposync-processing \
  --no-healthcheck \
  -p 49321:49321 \
  -v "$PWD/toposync-processing-data:/data" \
  ghcr.io/toposync/toposync:0.8.0 \
  toposync processing-serve --host 0.0.0.0 --port 49321 --data-dir /data

With Basic Auth:

docker run --rm -d \
  --name toposync-processing \
  --no-healthcheck \
  -e TOPOSYNC_PROCESSING_USERNAME=toposync \
  -e TOPOSYNC_PROCESSING_PASSWORD='<strong-password>' \
  -p 49321:49321 \
  -v "$PWD/toposync-processing-data:/data" \
  ghcr.io/toposync/toposync:0.8.0 \
  toposync processing-serve --host 0.0.0.0 --port 49321 --data-dir /data

--no-healthcheck is intentional here: the image has the origin healthcheck at /api/health, while the processing server responds at /api/processing/status.

Docker Compose override​

Create a docker-compose.processing.yml file in your deployment directory:

services:
  toposync-processing:
    image: ghcr.io/toposync/toposync:0.8.0
    command:
      - toposync
      - processing-serve
      - --host
      - 0.0.0.0
      - --port
      - "49321"
      - --data-dir
      - /data
    ports:
      - "49321:49321"
    volumes:
      - ./toposync-processing-data:/data
    environment:
      TOPOSYNC_PROCESSING_USERNAME: toposync
      TOPOSYNC_PROCESSING_PASSWORD: "<strong-password>"
    healthcheck:
      test:
        - CMD-SHELL
        - >
          python -c "import base64, os, sys, urllib.request;
          req=urllib.request.Request('http://127.0.0.1:49321/api/processing/status');
          user=os.getenv('TOPOSYNC_PROCESSING_USERNAME','');
          password=os.getenv('TOPOSYNC_PROCESSING_PASSWORD','');
          req.add_header('Authorization','Basic '+base64.b64encode(f'{user}:{password}'.encode()).decode());
          sys.exit(0 if urllib.request.urlopen(req, timeout=3).status == 200 else 1)"
      interval: 30s
      timeout: 5s
      start_period: 20s
      retries: 5
    restart: unless-stopped

Start the service:

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

For CUDA, change the image to ghcr.io/toposync/toposync:0.8.0-cuda and add the NVIDIA device reservation used in the Docker CUDA guide.

How to access​

The origin must be able to reach:

http://<processing-server-ip>:49321

The processing server does not serve the main UI.

How to verify​

Without Basic Auth:

curl http://127.0.0.1:49321/api/processing/status

With Basic Auth:

curl -u toposync:'<strong-password>' http://127.0.0.1:49321/api/processing/status

View logs:

docker logs -f toposync-processing

or, with Compose:

docker compose -f docker-compose.processing.yml logs -f toposync-processing

Register on the origin​

On the origin server:

curl -X PUT http://127.0.0.1:8000/api/processing-servers/docker_processing \
  -H 'content-type: application/json' \
  -d '{
    "id": "docker_processing",
    "name": "Docker Processing",
    "kind": "http",
    "url": "http://<processing-server-ip>:49321",
    "username": "toposync",
    "password": "<strong-password>"
  }'

Then validate through the origin:

curl http://127.0.0.1:8000/api/processing-servers/docker_processing/status

How to update​

Pull the new image and recreate the processing server:

docker compose -f docker-compose.processing.yml pull
docker compose -f docker-compose.processing.yml up -d

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 build

For a local CUDA image:

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 build

Then replace the image in your processing server Compose file with the local image tag you built.

How to uninstall​

With docker run:

docker stop toposync-processing
rm -rf ./toposync-processing-data

With Compose:

docker compose -f docker-compose.processing.yml down
rm -rf ./toposync-processing-data

Also remove the registered processing server from the origin.

Troubleshooting​

Container is unhealthy​

Do not use the origin image's default healthcheck. The processing server must check:

/api/processing/status

If you use docker run, pass --no-healthcheck or create a custom healthcheck.

401 Unauthorized​

The username or password configured on the origin does not match TOPOSYNC_PROCESSING_USERNAME and TOPOSYNC_PROCESSING_PASSWORD.

Connection refused​

Confirm the 49321:49321 port mapping, the --host 0.0.0.0 command, and the host firewall.

Pipeline still runs locally​

The pipeline is still using processing_server_id: "local". Change it to the server id registered on the origin.