The documented Docker instructions use an environment variable which does not exist #3387

What happens

docs/source/docker.rst tells users to point the VWS and VWQ containers at the target manager with TARGET_MANAGER_BACKEND:

$ docker run \
    --detach \
    --publish 5006:5000 \
    -e TARGET_MANAGER_BACKEND=vuforia-target-manager-mock:5000 \
    --network vws-bridge-network \
    ghcr.io/vws-python/vuforia-vws-mock

There is no such setting. TARGET_MANAGER_BACKEND appears four times in docs/source/docker.rst and nowhere else in the repository. The apps read target_manager_base_url on VWSSettings and VWQSettings, which pydantic-settings populates from TARGET_MANAGER_BASE_URL, and that name appears nowhere in the documentation.

The documented value is wrong too. target_manager_base_url is interpolated straight into a requests call:

url=f"{settings.target_manager_base_url}/cloud_databases"

so it needs a scheme. vuforia-target-manager-mock:5000 has none.

Following the documented instructions exactly:

1. VWSSettings.model_validate -> ValidationError target_manager_base_url
2. health check probe -> ValidationError 1 validation error for VWSSettings
3. correct name, documented value -> InvalidSchema No connection adapters were found for
   'vuforia-target-manager-mock:5000/cloud_databases'

Line 2 is the part that matters most. The Dockerfile's HEALTHCHECK probes /some-random-endpoint, which goes through the validate_request before-request hook, which calls get_all_cloud_databases() and therefore constructs VWSSettings. With the setting missing that raises, so the probe fails, so the VWS and VWQ containers never become healthy when started as documented.

Why it matters

This is the entire quickstart for the Docker images, and the Docker images are the supported way to use this mock from languages other than Python. A user following docs/source/docker.rst gets two permanently unhealthy containers and an error which names an environment variable they were never told to set.

Two smaller things in the same file, worth fixing in the same pass:

• The example response body for POST /cloud_databases omits database_id, database_type_name, request_quota, target_quota, requests_per_second_limit and request_rate_limits, all of which create_cloud_database returns via database.to_dict().
• RESPONSE_DELAY_SECONDS is read by both VWSSettings and VWQSettings but is not in the "Optional configuration" list, so a genuinely useful knob is undiscoverable for Docker users.

Why it was not caught

tests/mock_vws/test_docker.py::test_build_and_run starts the containers with the correct TARGET_MANAGER_BASE_URL and a proper http:// URL, so it passes while the documentation is wrong.

The console blocks in the docs are checked by shellcheck and shfmt through doccmd, which verifies they are valid shell but never runs them. By contrast the Python blocks in the docs are type-checked, linted and executed as doctests through Sybil. So the shell quickstart is the one piece of user-facing instruction in the project with no correctness check on it, which is presumably how the name drifted.

Suggested resolution

Fix the four occurrences to TARGET_MANAGER_BASE_URL and the values to http://vuforia-target-manager-mock:5000, and add RESPONSE_DELAY_SECONDS and the missing response fields.

Then consider closing the gap that allowed it. The cheapest option is a test which asserts that every .. envvar:: directive in docs/source/docker.rst corresponds to a real settings field on one of the three apps, and vice versa — ci/test_custom_linters.py is already the home for exactly this kind of consistency check, and it would catch both the drift and any future setting added without documentation.

Having test_build_and_run construct its docker run environment from the documented variable names would be stronger, but it is a bigger change and the linter catches the same class of bug.