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.

This guide uses the local image built from the repository. It does not assume a public container image yet.

For architecture and GPU support, see Compatibility.

Prerequisites​

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

Installation​

First build the local CPU image:

docker compose build

For CUDA, build with the CUDA override:

docker compose -f docker-compose.yml -f docker-compose.cuda.yml build

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" \
  toposync:local \
  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" \
  toposync:local \
  toposync processing-serve --host 0.0.0.0 --port 49321 --data-dir /data

--no-healthcheck is intentional here: the local 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: toposync:local
    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, make sure the toposync:local image was built with docker-compose.cuda.yml before starting this service.

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​

Rebuild the local image:

git pull
docker compose build

For CUDA:

git pull
docker compose -f docker-compose.yml -f docker-compose.cuda.yml build

Restart the processing server:

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

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.