|
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 |
0 commit comments