VROOM

Search the Azure Marketplace for VROOM on Ubuntu 24.04 and choose your VM size.

Attach an NSG that allows TCP 22 (SSH) from your management network and TCP 80 (the API) from the applications that submit optimisation requests. In production, front port 80 with TLS (see Enabling HTTPS below).

RG="vroom-prod"; LOCATION="eastus"; VM_NAME="vroom-01" IMAGE_URN="sac1647283583153:vroom-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION" az network vnet create -g "$RG" --name vroom-vnet --address-prefix 10.92.0.0/16 --subnet-name vroom-subnet --subnet-prefix 10.92.1.0/24 az network nsg create -g "$RG" --name vroom-nsg az network nsg rule create -g "$RG" --nsg-name vroom-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp az network nsg rule create -g "$RG" --nsg-name vroom-nsg --name allow-api --priority 110 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 80 --access Allow --protocol Tcp
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:vroom-ubuntu-24-04:default:latest
az vm create -g "$RG" --name "$VM_NAME" --image "$IMAGE_URN" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name vroom-vnet --subnet vroom-subnet --nsg vroom-nsg --public-ip-sku Standard

ssh azureuser@<vm-ip>

Run the commands below on the VM. vroom-express listens on 127.0.0.1:3000, and nginx fronts the API on port 80. The /healthz endpoint is public. Every other endpoint requires your per-VM password.

sudo systemctl is-active vroom-express nginx /opt/vroom/bin/vroom --version sudo ss -ltn | grep -E ':80 |:3000' curl -s http://127.0.0.1/healthz

Expect both services active, vroom 1.15.0, the two listening sockets, and ok from the health endpoint.

The first-boot service generated a password unique to this VM and stored it in a root-only file. Read it as root:

sudo cat /root/vroom-credentials.txt

Use the VROOM_PASSWORD value with the admin username. Store it in your secret manager. It is not recoverable from anywhere else, and it is different on every VM you launch from this image.

Before you send real work, confirm that the gate is closed. An unauthenticated request and a wrong-password request must both be rejected with 401. Only your per-VM password should return 200.

curl -s -o /dev/null -w 'no credentials -> HTTP %{http_code}\n' -X POST \
  -H 'Content-Type: application/json' \
  --data-binary @/opt/vroom/samples/sac-sample-problem.json http://127.0.0.1/
curl -s -o /dev/null -w 'wrong password -> HTTP %{http_code}\n' -X POST \
  -u 'admin:definitely-wrong-pw' -H 'Content-Type: application/json' \
  --data-binary @/opt/vroom/samples/sac-sample-problem.json http://127.0.0.1/
sudo ufw status verbose | head -12

Expect 401, 401, and a firewall that is active with Default: deny (incoming) and only 22/tcp and 80/tcp allowed.

Submit the ready-to-run problem at /opt/vroom/samples/sac-sample-problem.json. It has one vehicle, three jobs with delivery time windows, and a supplied 4x4 duration matrix. Because the matrix is in the request, this solve contacts no external service.

curl -s -u "admin:<VROOM_PASSWORD>" -H 'Content-Type: application/json' \
  --data-binary @/opt/vroom/samples/sac-sample-problem.json http://127.0.0.1/ \
  | python3 -m json.tool | head -40

VROOM returns "code": 0, one route, zero unassigned jobs, and a step-by-step plan. The time windows in this sample admit exactly one feasible ordering, so a correct solve always visits job 101, then 102, then 103, with a total travel time of 3600 seconds.

The result also shows the scheduler at work. Rather than leaving the depot at time zero and idling at a closed stop, VROOM delays departure to 600 so that arrivals line up with the windows. This cuts total waiting time to 300 seconds.

The second sample models four deliveries in two geographic clusters, served by two vans that can each carry two units. VROOM assigns one cluster to each van.

curl -s -u "admin:<VROOM_PASSWORD>" -H 'Content-Type: application/json' \
  --data-binary @/opt/vroom/samples/sac-sample-capacity.json http://127.0.0.1/ \
  | python3 -m json.tool | head -30

You get two routes, zero unassigned jobs, and each van carrying exactly its capacity.

Write your own problem

A request is a JSON object with vehicles, jobs (or shipments for paired pickup and delivery) and, in matrix mode, a matrices object. Locations are referred to by their index into that matrix.

cat > /tmp/my-problem.json <<'JSON' { "vehicles": [ { "id": 1, "start_index": 0, "end_index": 0, "capacity": [10] } ], "jobs": [ { "id": 1, "location_index": 1, "delivery": [3], "service": 180 }, { "id": 2, "location_index": 2, "delivery": [4], "service": 180 } ], "matrices": { "car": { "durations": [ [0, 480, 720], [480, 0, 300], [720, 300, 0] ] } } } JSON curl -s -u "admin:<VROOM_PASSWORD>" -H 'Content-Type: application/json' \
  --data-binary @/tmp/my-problem.json http://127.0.0.1/ | python3 -m json.tool | head -25

The matrix is square and measured in seconds. Row and column i correspond to location_index i. Entries need not be symmetric: one-way systems and turn restrictions are exactly why they often are not.

These modelling keys are all documented in the upstream API reference:

• capacity on a vehicle and delivery / pickup on a job: multi-dimensional load limits (weight, volume, pallet count, all at once)
• time_windows on a job and time_window on a vehicle: opening hours and driver shifts
• skills: only vehicles holding every skill a job requires may serve it (refrigeration, a tail lift, a certified driver)
• priority: when not everything fits, control what gets dropped first
• breaks: mandatory driver rest periods inside a shift
• max_travel_time, max_distance, max_tasks: per-vehicle limits
• costs with fixed, per_hour, per_km: model what a route actually costs you

If you supply a non-zero per_km cost, or ask for route geometry, VROOM needs distances as well as durations. In matrix mode, supply a distances matrix alongside durations. Otherwise VROOM tries to reach a routing engine to fetch them.

To send location coordinates instead of location_index, point this image at a routing engine you operate. Nothing is bundled, so you provision the engine yourself. Run OSRM, Openrouteservice or Valhalla on another host (or in a container on this VM) with a map extract that covers your operating area.

Edit the routingServers section of the configuration to set the host and port of your engine:

sudo cp /opt/vroom-express/config.yml /opt/vroom-express/config.yml.bak
sudo sed -n '/^routingServers:/,$p' /opt/vroom-express/config.yml

Change the host and port under the profile you use, then restart the service:

sudo systemctl restart vroom-express
sudo systemctl is-active vroom-express

Once the engine is reachable, requests can use "location": [lon, lat] on jobs and "start" / "end" on vehicles, and can omit matrices entirely. Coordinates are always [longitude, latitude], in that order. This is the reverse of the usual mapping convention, and the most common first-time mistake.

If you send coordinates without a reachable engine, VROOM returns status code 3 (routing error). That is the expected result, not a fault in the image.

Edit the configuration in /opt/vroom-express/config.yml. List the active settings with:

sudo grep -vE '^\s*#|^\s*$' /opt/vroom-express/config.yml | head -20

• threads is set to 2 to match Standard_B2s. Raise it to the vCPU count of a larger VM.
• explore (0 to 5) trades solve time against solution quality. The default, 5, is the most thorough.
• maxlocations (1000) and maxvehicles (200) bound request size, and limit (20mb) bounds the request body. Large matrices are large JSON: a 1000 by 1000 duration matrix is several megabytes.
• timeout is 300000 ms, and nginx is configured to match. Raise both together if you routinely solve very large problems.
• override is false on purpose. Setting it to true lets any caller pass "options": {"t": 64, "x": 5} in the request body and dictate thread count and exploration depth on your VM. Leave it disabled on anything internet-facing.

Restart the service after editing:

sudo systemctl restart vroom-express curl -s http://127.0.0.1/healthz