GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing vws-python.github.io — Running a server in containers - vws-python-mock

Running a server in containers¶

You can run a Mock VWS instance using Docker or Apple’s container CLI. Both use the same published images.

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 with Docker¶

Docker users can run the commands below directly. For a deployment using Apple’s CLI directly, follow Creating containers with Apple container.

$ 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 \
    -e VWS_BASE_URL=http://127.0.0.1:5006 \
    --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

The VWS container uses VWS_BASE_URL to generate report download URLs. Set it to the URL clients use to reach the published VWS port. For clients on another machine, replace http://127.0.0.1:5006 with an address those clients can reach.

Creating containers with Apple container¶

This setup requires a Mac with Apple silicon and macOS 26 or later, Apple’s container CLI 1.5.0 or later, and jq to read the container’s address. Install the runtime, start its services, and install the recommended Linux kernel:

$ brew install container jq
$ container system start --disable-kernel-install
$ container system kernel set --recommended

Allow Local Network access for container-runtime-linux when macOS prompts. If requests to a published port reset, check this permission in System Settings → Privacy & Security → Local Network, then restart the container services.

Create a network and start the target manager first. Read its IP address on that network for the VWS and VWQ services to use:

$ container network create vws-bridge-network
$ container run \
    --detach \
    --publish 127.0.0.1:5005:5000 \
    --name vuforia-target-manager-mock \
    --network vws-bridge-network \
    ghcr.io/vws-python/vuforia-target-manager-mock
$ TARGET_MANAGER_IP="$(container inspect vuforia-target-manager-mock | jq -er '.[0].status.networks[0].ipv4Address | split("/")[0]')"
$ export TARGET_MANAGER_BASE_URL="http://$TARGET_MANAGER_IP:5000"
$ container run \
    --detach \
    --publish 127.0.0.1:5006:5000 \
    --name vuforia-vws-mock \
    --env "TARGET_MANAGER_BASE_URL=$TARGET_MANAGER_BASE_URL" \
    --env VWS_BASE_URL=http://127.0.0.1:5006 \
    --network vws-bridge-network \
    ghcr.io/vws-python/vuforia-vws-mock
$ container run \
    --detach \
    --publish 127.0.0.1:5007:5000 \
    --name vuforia-vwq-mock \
    --env "TARGET_MANAGER_BASE_URL=$TARGET_MANAGER_BASE_URL" \
    --network vws-bridge-network \
    ghcr.io/vws-python/vuforia-vwq-mock

Using the target manager’s IP avoids requiring DNS configuration for container names on this network. The IP lookup removes the subnet suffix returned by container inspect. The scheme and container port are fixed, so the URL is constructed separately. If you recreate the target manager, read its new address and recreate VWS and VWQ with the updated TARGET_MANAGER_BASE_URL. The host ports match the Docker example, so the HTTP examples below work with either deployment. VWS_BASE_URL is the URL clients use to reach VWS and download recognition reports.

Run each readiness probe until it exits successfully:

$ container exec vuforia-target-manager-mock python -m vws_mock_server.healthcheck
$ container exec vuforia-vws-mock python -m vws_mock_server.healthcheck
$ container exec vuforia-vwq-mock python -m vws_mock_server.healthcheck

To stop and remove this deployment:

$ container rm --force vuforia-vwq-mock vuforia-vws-mock vuforia-target-manager-mock
$ container network rm vws-bridge-network

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:

Content-Type – application/json

Response Headers:

Content-Type – application/json

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 either deployment above, 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¶

These commands build the images with docker buildx.

$ export REPOSITORY_ROOT="$PWD"
$ export DOCKERFILE="$REPOSITORY_ROOT/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"

To build the same Dockerfile stages with Apple’s CLI, set the variables above and run:

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

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.