Running a server with Docker

It is possible run a Mock VWS instance using Docker containers.

This allows you to run tests against a mock VWS instance regardless of the language or tooling you are using.

Running the mock

There are three containers required. One container mocks the VWS services, one container mocks the VWQ services and one container provides a shared target manager backend.

Each of these containers run their services on port 5000.

The VWS and VWQ containers must point to the target manager container using the TARGET_MANAGER_BASE_URL variable.

Creating containers

$ docker network create -d bridge vws-bridge-network
$ docker run \
    --detach \
    --publish 5005:5000 \
    --name vuforia-target-manager-mock \
    --network vws-bridge-network \
    ghcr.io/vws-python/vuforia-target-manager-mock
$ docker run \
    --detach \
    --publish 5006:5000 \
    -e TARGET_MANAGER_BASE_URL=http://vuforia-target-manager-mock:5000 \
    --network vws-bridge-network \
    ghcr.io/vws-python/vuforia-vws-mock
$ docker run \
    --detach \
    --publish 5007:5000 \
    -e TARGET_MANAGER_BASE_URL=http://vuforia-target-manager-mock:5000 \
    --network vws-bridge-network \
    ghcr.io/vws-python/vuforia-vwq-mock

Adding a database to the mock target manager

When using Vuforia Web Services, it is necessary to create a database on the Target Manager. This is a web interface which does not have an HTTP API.

To mimic this functionality, this mock provides a target manager container which has an HTTP API.

To add a database, make a request to the following endpoint against the target manager container:

POST /cloud_databases

Create a new cloud database.

Request Headers:
Response Headers:
Request JSON Object:

  • client_access_key (string) – (Optional) The client access key for the cloud database.

  • client_secret_key (string) – (Optional) The client secret key for the cloud database.

  • database_name (string) – (Optional) The name of the cloud database.

  • request_quota (int) – (Optional) The request quota. Set this to zero to make VWS endpoints return RequestQuotaReached.

  • target_quota (int) – (Optional) The target quota. Once this many targets exist, adding another returns TargetQuotaReached.

  • reco_threshold (int) – (Optional) The recognition threshold shown in the database summary report.

  • current_month_recos (int) – (Optional) The number of recognitions in the current month, shown in the database summary report.

  • previous_month_recos (int) – (Optional) The number of recognitions in the previous month, shown in the database summary report.

  • total_recos (int) – (Optional) The total number of recognitions, shown in the database summary report.

  • requests_per_second_limit (int) – (Optional) The maximum number of VWS requests accepted in a rolling one-second window, across all VWS endpoints. Set this to zero to make VWS endpoints return a 429 response.

  • request_rate_limits – (Optional) Request rate limits for individual groups of VWS endpoints. This is an object with the optional keys “other”, “get_target”, “get_duplicates” and “list_targets”, each either null or an object with the keys “max_requests” and “window_seconds”.

  • server_access_key (string) – (Optional) The server access key for the cloud database.

  • server_secret_key (string) – (Optional) The server secret key for the cloud database.

  • state_name (string) – (Optional) The state of the cloud database. This can be “WORKING”, “PROJECT_INACTIVE”, “PROJECT_SUSPENDED”, or “PROJECT_HAS_NO_API_ACCESS”. This defaults to “WORKING”.

Response JSON Object:

  • client_access_key (string) – The client access key for the cloud database.

  • client_secret_key (string) – The client secret key for the cloud database.

  • database_name (string) – The cloud database name.

  • request_quota (int) – The request quota.

  • target_quota (int) – The target quota.

  • requests_per_second_limit (int) – The per-second request limit, or null when rate limiting is disabled.

  • request_rate_limits – The per-endpoint request rate limits, or null when per-endpoint rate limiting is disabled.

  • server_access_key (string) – The server access key for the cloud database.

  • server_secret_key (string) – The server secret key for the cloud database.

  • state_name (string) – The cloud database state.

Request JSON Array of Objects:

  • targets – The targets in the cloud database.

Status Codes:

  • 201 Created – The cloud database has been successfully created.

  • 400 Bad Request – The request body is not a JSON object, or a field has a value which is not accepted. The response body is a JSON object with an errors list which names each offending field and the accepted values.

  • 409 Conflict – A cloud database with one of the given keys or the given name already exists.

For example, with the containers set up as in Creating containers, use curl:

$ curl --request POST \
    --header "Content-Type: application/json" \
    --data '{}' \
    '127.0.0.1:5005/cloud_databases'
{
    "database_id": "ca6e48ed25a340d998905ac59747a1f8",
    "database_name": "e515df24ba944f43b8f7969bc98af107",
    "server_access_key": "cb1759871a504875ab5f96d6db5ff79b",
    "server_secret_key": "9b8533d912ad4aa79cb61b6ee197ece2",
    "client_access_key": "2d61c1d17bb94694bee77c1f1f41e5d9",
    "client_secret_key": "b73f8170cf7d42728fa8ce66221ad147",
    "state_name": "WORKING",
    "database_type_name": "CLOUD_RECO",
    "targets": [],
    "request_quota": 100000,
    "reco_threshold": 1000,
    "current_month_recos": 0,
    "previous_month_recos": 0,
    "total_recos": 0,
    "target_quota": 1000,
    "requests_per_second_limit": null,
    "request_rate_limits": null
}

Deleting a database

To delete a database use the following endpoint:

DELETE /cloud_databases/(string: database_name)

Delete a cloud database.

Status Codes:

  • 200 OK – The cloud database has been deleted.

Setting the recognition counts of a target

The mock does not count recognitions, because the counts which the real Vuforia Web Services report lag behind its queries by longer than a test runs. To make the target summary report and the reco counts report show non-zero counts, set the counts with the following endpoint:

POST /cloud_databases/(string: database_name)/targets/(string: target_id)/recognition_counts

Set the recognition counts of a target.

A recognition is not a change to the target, so unlike a target update this does not change the target’s last modified date, and a processed target does not go back to being processed.

Request JSON Object:

  • current_month_recos (int) – (Optional) The number of recognitions of this target in the current month. If not given, the count is left as it is.

  • previous_month_recos (int) – (Optional) The number of recognitions of this target in the previous month. If not given, the count is left as it is.

  • total_recos (int) – (Optional) The total number of recognitions of this target. If not given, the count is left as it is.

Status Codes:

  • 200 OK – The recognition counts have been set.

Configuration options

Required configuration

TARGET_MANAGER_BASE_URL

This is required by the VWS mock and the VWQ mock containers. This is the base URL of the target manager container as seen from the other containers. It must include a scheme, for example http://vuforia-target-manager-mock:5000.

Optional configuration

VWS and Query containers

RESPONSE_DELAY_SECONDS

The number of seconds to wait before sending each response.

Default: 0.0

Target manager container

TARGET_RATER

The rater to use for target tracking ratings.

Options include:

  • brisque: The rating is derived using the BRISQUE algorithm.

  • perfect: The rating is always 5.

  • random: The rating is random.

Default: brisque

Query container

QUERY_IMAGE_MATCHER

The matcher to use for the query endpoint.

Options include:

  • exact: The images must be exactly the same to match.

  • structural_similarity: The images must have a similar structural similarity to match.

Default: structural_similarity

VWS container

PROCESSING_TIME_SECONDS

The number of seconds to process each image for.

Default: 2.0

MODEL_TARGET_TRAINING_ALLOWANCE_EXCEEDED

Whether Model Target dataset creation returns Vuforia’s TRAINING_ALLOWANCE_EXCEEDED response.

Default: false

VWS_BASE_URL

The base URL which clients use to reach the VWS container. The download URL of a reco counts report is built from this URL.

Default: https://vws.vuforia.com

DUPLICATES_IMAGE_MATCHER

The matcher to use for the duplicates endpoint.

Options include:

  • exact: The images must be exactly the same to be duplicates.

  • structural_similarity: The images must have a similar structural similarity to be duplicates.

Default: structural_similarity

Building images from source

$ export REPOSITORY_ROOT="$PWD"
$ export DOCKERFILE="$REPOSITORY_ROOT/src/mock_vws/_flask_server/Dockerfile"

$ export TARGET_MANAGER_TAG=ghcr.io/vws-python/vuforia-target-manager-mock:latest
$ export VWS_TAG=ghcr.io/vws-python/vuforia-vws-mock:latest
$ export VWQ_TAG=ghcr.io/vws-python/vuforia-vwq-mock:latest

$ docker buildx build "$REPOSITORY_ROOT" --file "$DOCKERFILE" --target target-manager --tag "$TARGET_MANAGER_TAG"
$ docker buildx build "$REPOSITORY_ROOT" --file "$DOCKERFILE" --target vws --tag "$VWS_TAG"
$ docker buildx build "$REPOSITORY_ROOT" --file "$DOCKERFILE" --target vwq --tag "$VWQ_TAG"