Skip to content
This repository was archived by the owner on Oct 30, 2026. It is now read-only.

Commit 777f277

Browse files
committed
Move deployment documentation into the server project
1 parent e0006c7 commit 777f277

5 files changed

Lines changed: 308 additions & 300 deletions

File tree

‎.dockerignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ newsfragments
3131
secrets.tar.gpg
3232
spelling_private_dict.txt
3333
tests
34+
server/docs
3435
server/tests
3536
vuforia_secrets.env.example
3637
zizmor.yml

‎docs/source/docker.rst‎

Lines changed: 1 addition & 300 deletions
Original file line numberDiff line numberDiff line change
@@ -1,300 +1 @@
1-
Running a server in containers
2-
==============================
3-
4-
You can run a Mock VWS instance using Docker or Apple's `container`_ CLI.
5-
Both use the same published images.
6-
7-
This allows you to run tests against a mock VWS instance regardless of the language or tooling you are using.
8-
9-
Running the mock
10-
----------------
11-
12-
There are three containers required.
13-
One container mocks the VWS services, one container mocks the VWQ services and one container provides a shared target manager backend.
14-
15-
Each of these containers run their services on port 5000.
16-
17-
The VWS and VWQ containers must point to the target manager container using the :envvar:`TARGET_MANAGER_BASE_URL` variable.
18-
19-
.. _creating-containers:
20-
21-
Creating containers with Docker
22-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
23-
24-
Docker users can run the commands below directly.
25-
For a deployment using Apple's CLI directly, follow :ref:`apple-container-setup`.
26-
27-
.. code-block:: console
28-
29-
$ docker network create -d bridge vws-bridge-network
30-
$ docker run \
31-
--detach \
32-
--publish 5005:5000 \
33-
--name vuforia-target-manager-mock \
34-
--network vws-bridge-network \
35-
ghcr.io/vws-python/vuforia-target-manager-mock
36-
$ docker run \
37-
--detach \
38-
--publish 5006:5000 \
39-
-e TARGET_MANAGER_BASE_URL=http://vuforia-target-manager-mock:5000 \
40-
-e VWS_BASE_URL=http://127.0.0.1:5006 \
41-
--network vws-bridge-network \
42-
ghcr.io/vws-python/vuforia-vws-mock
43-
$ docker run \
44-
--detach \
45-
--publish 5007:5000 \
46-
-e TARGET_MANAGER_BASE_URL=http://vuforia-target-manager-mock:5000 \
47-
--network vws-bridge-network \
48-
ghcr.io/vws-python/vuforia-vwq-mock
49-
50-
The VWS container uses :envvar:`VWS_BASE_URL` to generate report download URLs.
51-
Set it to the URL clients use to reach the published VWS port.
52-
For clients on another machine, replace ``http://127.0.0.1:5006`` with an address those clients can reach.
53-
54-
55-
.. _apple-container-setup:
56-
57-
Creating containers with Apple container
58-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59-
60-
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.
61-
Install the runtime, start its services, and install the recommended Linux kernel:
62-
63-
.. code-block:: console
64-
65-
$ brew install container jq
66-
$ container system start --disable-kernel-install
67-
$ container system kernel set --recommended
68-
69-
Allow Local Network access for ``container-runtime-linux`` when macOS prompts.
70-
If requests to a published port reset, check this permission in System Settings → Privacy & Security → Local Network, then restart the container services.
71-
72-
Create a network and start the target manager first.
73-
Read its IP address on that network for the VWS and VWQ services to use:
74-
75-
.. code-block:: console
76-
77-
$ container network create vws-bridge-network
78-
$ container run \
79-
--detach \
80-
--publish 127.0.0.1:5005:5000 \
81-
--name vuforia-target-manager-mock \
82-
--network vws-bridge-network \
83-
ghcr.io/vws-python/vuforia-target-manager-mock
84-
$ TARGET_MANAGER_IP="$(container inspect vuforia-target-manager-mock | jq -er '.[0].status.networks[0].ipv4Address | split("/")[0]')"
85-
$ export TARGET_MANAGER_BASE_URL="http://$TARGET_MANAGER_IP:5000"
86-
$ container run \
87-
--detach \
88-
--publish 127.0.0.1:5006:5000 \
89-
--name vuforia-vws-mock \
90-
--env "TARGET_MANAGER_BASE_URL=$TARGET_MANAGER_BASE_URL" \
91-
--env VWS_BASE_URL=http://127.0.0.1:5006 \
92-
--network vws-bridge-network \
93-
ghcr.io/vws-python/vuforia-vws-mock
94-
$ container run \
95-
--detach \
96-
--publish 127.0.0.1:5007:5000 \
97-
--name vuforia-vwq-mock \
98-
--env "TARGET_MANAGER_BASE_URL=$TARGET_MANAGER_BASE_URL" \
99-
--network vws-bridge-network \
100-
ghcr.io/vws-python/vuforia-vwq-mock
101-
102-
Using the target manager's IP avoids requiring DNS configuration for container names on this network.
103-
The IP lookup removes the subnet suffix returned by ``container inspect``.
104-
The scheme and container port are fixed, so the URL is constructed separately.
105-
If you recreate the target manager, read its new address and recreate VWS and VWQ with the updated ``TARGET_MANAGER_BASE_URL``.
106-
The host ports match the Docker example, so the HTTP examples below work with either deployment.
107-
``VWS_BASE_URL`` is the URL clients use to reach VWS and download recognition reports.
108-
109-
Run each readiness probe until it exits successfully:
110-
111-
.. code-block:: console
112-
113-
$ container exec vuforia-target-manager-mock python -m vws_mock_server.healthcheck
114-
$ container exec vuforia-vws-mock python -m vws_mock_server.healthcheck
115-
$ container exec vuforia-vwq-mock python -m vws_mock_server.healthcheck
116-
117-
To stop and remove this deployment:
118-
119-
.. code-block:: console
120-
121-
$ container rm --force vuforia-vwq-mock vuforia-vws-mock vuforia-target-manager-mock
122-
$ container network rm vws-bridge-network
123-
124-
.. _container: https://github.com/apple/container
125-
126-
127-
Adding a database to the mock target manager
128-
--------------------------------------------
129-
130-
When using Vuforia Web Services, it is necessary to create a database on the `Target Manager`_.
131-
This is a web interface which does not have an HTTP API.
132-
133-
To mimic this functionality, this mock provides a target manager container which has an HTTP API.
134-
135-
To add a database, make a request to the following endpoint against the target manager container:
136-
137-
.. autoflask:: vws_mock_server.target_manager:TARGET_MANAGER_FLASK_APP
138-
:endpoints: create_cloud_database
139-
140-
For example, with either deployment above, use ``curl``:
141-
142-
.. code-block:: console
143-
144-
$ curl --request POST \
145-
--header "Content-Type: application/json" \
146-
--data '{}' \
147-
'127.0.0.1:5005/cloud_databases'
148-
{
149-
"database_id": "ca6e48ed25a340d998905ac59747a1f8",
150-
"database_name": "e515df24ba944f43b8f7969bc98af107",
151-
"server_access_key": "cb1759871a504875ab5f96d6db5ff79b",
152-
"server_secret_key": "9b8533d912ad4aa79cb61b6ee197ece2",
153-
"client_access_key": "2d61c1d17bb94694bee77c1f1f41e5d9",
154-
"client_secret_key": "b73f8170cf7d42728fa8ce66221ad147",
155-
"state_name": "WORKING",
156-
"database_type_name": "CLOUD_RECO",
157-
"targets": [],
158-
"request_quota": 100000,
159-
"reco_threshold": 1000,
160-
"current_month_recos": 0,
161-
"previous_month_recos": 0,
162-
"total_recos": 0,
163-
"target_quota": 1000,
164-
"requests_per_second_limit": null,
165-
"request_rate_limits": null
166-
}
167-
168-
Deleting a database
169-
-------------------
170-
171-
To delete a database use the following endpoint:
172-
173-
.. autoflask:: vws_mock_server.target_manager:TARGET_MANAGER_FLASK_APP
174-
:endpoints: delete_cloud_database
175-
176-
Setting the recognition counts of a target
177-
------------------------------------------
178-
179-
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.
180-
To make the target summary report and the reco counts report show non-zero counts, set the counts with the following endpoint:
181-
182-
.. autoflask:: vws_mock_server.target_manager:TARGET_MANAGER_FLASK_APP
183-
:endpoints: set_target_recognition_counts
184-
185-
186-
.. _Target Manager: https://developer.vuforia.com/library/vuforia-engine/getting-started/engine-developer-portal/vuforia-target-manager/
187-
188-
189-
Configuration options
190-
---------------------
191-
192-
Required configuration
193-
^^^^^^^^^^^^^^^^^^^^^^
194-
195-
.. envvar:: TARGET_MANAGER_BASE_URL
196-
197-
This is required by the VWS mock and the VWQ mock containers.
198-
This is the base URL of the target manager container as seen from the other containers.
199-
It must include a scheme, for example ``http://vuforia-target-manager-mock:5000``.
200-
201-
Optional configuration
202-
^^^^^^^^^^^^^^^^^^^^^^
203-
204-
VWS and Query containers
205-
~~~~~~~~~~~~~~~~~~~~~~~~
206-
207-
.. envvar:: RESPONSE_DELAY_SECONDS
208-
209-
The number of seconds to wait before sending each response.
210-
211-
Default: ``0.0``
212-
213-
Target manager container
214-
~~~~~~~~~~~~~~~~~~~~~~~~
215-
216-
.. envvar:: TARGET_RATER
217-
218-
The rater to use for target tracking ratings.
219-
220-
Options include:
221-
222-
* ``brisque``: The rating is derived using the BRISQUE algorithm.
223-
* ``perfect``: The rating is always 5.
224-
* ``random``: The rating is random.
225-
226-
Default: ``brisque``
227-
228-
Query container
229-
~~~~~~~~~~~~~~~
230-
231-
.. envvar:: QUERY_IMAGE_MATCHER
232-
233-
The matcher to use for the query endpoint.
234-
235-
Options include:
236-
237-
* ``exact``: The images must be exactly the same to match.
238-
* ``structural_similarity``: The images must have a similar structural similarity to match.
239-
240-
Default: ``structural_similarity``
241-
242-
VWS container
243-
~~~~~~~~~~~~~
244-
245-
.. envvar:: PROCESSING_TIME_SECONDS
246-
247-
The number of seconds to process each image for.
248-
249-
Default: ``2.0``
250-
251-
.. envvar:: MODEL_TARGET_TRAINING_ALLOWANCE_EXCEEDED
252-
253-
Whether Model Target dataset creation returns Vuforia's
254-
``TRAINING_ALLOWANCE_EXCEEDED`` response.
255-
256-
Default: ``false``
257-
258-
.. envvar:: VWS_BASE_URL
259-
260-
The base URL which clients use to reach the VWS container.
261-
The download URL of a reco counts report is built from this URL.
262-
263-
Default: ``https://vws.vuforia.com``
264-
265-
.. envvar:: DUPLICATES_IMAGE_MATCHER
266-
267-
The matcher to use for the duplicates endpoint.
268-
269-
Options include:
270-
271-
* ``exact``: The images must be exactly the same to be duplicates.
272-
* ``structural_similarity``: The images must have a similar structural similarity to be duplicates.
273-
274-
Default: ``structural_similarity``
275-
276-
Building images from source
277-
^^^^^^^^^^^^^^^^^^^^^^^^^^^
278-
279-
These commands build the images with ``docker buildx``.
280-
281-
.. code-block:: console
282-
283-
$ export REPOSITORY_ROOT="$PWD"
284-
$ export DOCKERFILE="$REPOSITORY_ROOT/server/Dockerfile"
285-
286-
$ export TARGET_MANAGER_TAG=ghcr.io/vws-python/vuforia-target-manager-mock:latest
287-
$ export VWS_TAG=ghcr.io/vws-python/vuforia-vws-mock:latest
288-
$ export VWQ_TAG=ghcr.io/vws-python/vuforia-vwq-mock:latest
289-
290-
$ docker buildx build "$REPOSITORY_ROOT" --file "$DOCKERFILE" --target target-manager --tag "$TARGET_MANAGER_TAG"
291-
$ docker buildx build "$REPOSITORY_ROOT" --file "$DOCKERFILE" --target vws --tag "$VWS_TAG"
292-
$ docker buildx build "$REPOSITORY_ROOT" --file "$DOCKERFILE" --target vwq --tag "$VWQ_TAG"
293-
294-
To build the same ``Dockerfile`` stages with Apple's CLI, set the variables above and run:
295-
296-
.. code-block:: console
297-
298-
$ container build "$REPOSITORY_ROOT" --file "$DOCKERFILE" --target target-manager --tag "$TARGET_MANAGER_TAG"
299-
$ container build "$REPOSITORY_ROOT" --file "$DOCKERFILE" --target vws --tag "$VWS_TAG"
300-
$ container build "$REPOSITORY_ROOT" --file "$DOCKERFILE" --target vwq --tag "$VWQ_TAG"
1+
.. include:: ../../server/docs/deployment.rst

‎pyproject.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -376,6 +376,7 @@ ignore = [
376376
"secrets.tar.gpg",
377377
"server/docker-bake.hcl",
378378
"server/Dockerfile",
379+
"server/docs/**",
379380
"server/tests/**",
380381
"spelling_private_dict.txt",
381382
"styles/snapper/*.yml",

‎server/README.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,3 +71,8 @@ From the workspace root, build the three service targets with the server's bake
7171
The default group builds ``linux/amd64`` and ``linux/arm64`` images.
7272
The ``VERSION`` variable selects the version tag alongside ``latest``.
7373
The image names and service targets remain the same.
74+
75+
Deployment
76+
----------
77+
78+
See the `deployment guide <docs/deployment.rst>`_ for Docker and Apple container commands and service configuration.

0 commit comments

Comments
 (0)