TourOptimizer REST Server

Deploy and operate JOpt.TourOptimizer as a reactive Spring WebFlux service with an OpenAPI 3 contract.

Overview

• Helpful links
• Why WebFlux and reactive
• Swagger and OpenAPI
• Run locally with Docker
• Endpoint groups and feature flags
• Configuration reference
• Container environment variables

Helpful links

• Docker image: https://hub.docker.com/r/dnaevolutions/jopt_touroptimizer
• REST client documentation: /docs/learn-and-explore/rest/rest_client_touroptimizer
• Sandboxes: /docs/learn-and-explore/feature-guides/jopt-sandboxes
• Self-hosting repository: https://github.com/DNA-Evolutions/Docker-REST-TourOptimizer

Why WebFlux and reactive

Optimization services run in bursty, concurrent scenarios: batch planning, interactive UI runs, multiple teams submitting jobs simultaneously, CI regression pipelines. TourOptimizer uses Spring WebFlux and reactive patterns to keep the HTTP layer non-blocking, support high concurrency for status and progress polling without thread starvation, and integrate naturally with the reactive event streams emitted by the Java core engine (progress percentages, warnings, errors, status transitions). The optimizer itself is compute-heavy and runs on its own thread pool. WebFlux keeps the service layer scalable and responsive regardless of how many connections are open.

Swagger and OpenAPI

The OpenAPI schema is derived from the snapshot model inside the Java library via annotations. The REST contract always matches the SDK snapshot definition, generated clients stay aligned with the server, and snapshots remain reproducible across environments.

• Swagger UI: http://localhost:8081/swagger-ui/index.html
• OpenAPI JSON: http://localhost:8081/v3/api-docs

Swagger Endpoint UI

Run locally with Docker

Minimal start (sync mode only, no database):

docker run -d --rm --name jopt-touroptimizer \
  -p 8081:8081 \
  -e SPRING_PROFILES_ACTIVE=cors \
  dnaevolutions/jopt_touroptimizer:latest

Full start (all features enabled — sync + database + all endpoints):

# Step 1 — Create a network
docker network create mongonetwork

# Step 2 — Start MongoDB
docker run -d --name dnamongo --network mongonetwork \
  -p 27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=dnauser \
  -e MONGO_INITDB_ROOT_PASSWORD=dnapwd \
  mongo:latest

# Step 3 — Start TourOptimizer
docker run --rm --name jopt-touroptimizer \
  --network mongonetwork \
  -p 8081:8081 \
  -e SPRING_PROFILES_ACTIVE=cors \
  -e DNA_DATABASE_ACTIVE=true \
  -e DNA_DATABASE_URI="mongodb://dnauser:dnapwd@dnamongo:27017/admin" \
  -e DNA_DATABASE_DB=touroptimizer \
  -e DNA_SHOW_SYNCH_CONTROLLERS=true \
  -e DNA_DATABASE_FREE_SEARCH_ENABLED=true \
  -e DNA_DATABASE_JOB_IMPORT_ENABLED=true \
  -e DNA_WEBHOOK_VALIDATION=relaxed \
  dnaevolutions/jopt_touroptimizer:latest

If your REST client runs inside another container on the same machine, use http://host.docker.internal:8081 instead of http://localhost:8081.

For platform-specific deployment help see:

• JOpt TourOptimizer on Linux
• JOpt TourOptimizer on Windows
• JOpt TourOptimizer on macOS
• Kubernetes
• Terraform / Enterprise

Endpoint groups and feature flags

Endpoints are activated conditionally based on application properties and environment variables. Endpoints that are not active in a given deployment are absent from the service and do not appear in the runtime OpenAPI spec.

Job endpoints (/api/v1/jobs/*)

The primary integration model for all deployments with a connected database. Submit a job and receive a jobId. Use that token to poll and retrieve results at any time without holding an HTTP connection open. Requires DNA_DATABASE_ACTIVE=true.

All job endpoints require the X-Tenant-Id header. In SaaS deployments this is injected by the API gateway. In local and on-premise deployments any fixed string is acceptable (for example local or my-tenant).

Synchronous run endpoints (/api/v1/runs/*)

For short optimizations (up to a few minutes) where holding the connection open is acceptable. Each run is isolated by a runId — multiple concurrent runs are fully supported. Requires DNA_SHOW_SYNCH_CONTROLLERS=true.

For optimizations that take longer than a few minutes, use the job endpoints instead.

SSE stream endpoints (/api/v1/runs/{runId}/stream/*)

Server-Sent Event streams scoped to a specific sync run. Subscribe while the run is in progress to receive live events. Each run has independent, isolated stream subscriptions. Requires DNA_SHOW_SYNCH_CONTROLLERS=true.

Health endpoint

Configuration reference

JOpt / DNA properties

Spring / WebFlux / springdoc properties

Container environment variable summary

References

• DockerHub: https://hub.docker.com/r/dnaevolutions/jopt_touroptimizer
• Self-hosting repo: https://github.com/DNA-Evolutions/Docker-REST-TourOptimizer
• Docker variables reference: https://github.com/DNA-Evolutions/Docker-REST-TourOptimizer/blob/main/TourOptimizerDockerVars.md

A product by DNA Evolutions GmbH ©