kevinveenbirkenbachandClaude Opus 5
1138acf441
The entry described what an empty matomo_site_id causes and left unsaid how it gets that way, which 7309d50575 had meanwhile made non-obvious: resolve_site.yml starts from an empty id, skips the lookup entirely when no token resolved, and only enters the registration block when the answer is a 200 that is not a mapping, because a Matomo error arrives as a JSON object rather than the expected list.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2.5 KiB
Deployment Exceptions ⚠️
This page documents known cases where an Ansible role deliberately skips its work instead of failing, and explains the conditions under which the skipped work will be completed on a subsequent run.
Matomo Token Not Yet Available ⚠️
Role: roles/sys-front-inj-matomo
Variable: lookup('users', 'administrator').tokens['web-app-matomo']
Cause 🔍
The Matomo API token is generated during the Matomo bootstrap and persisted to disk by sys-token-store.
It is then resolved through lookup('users'), which hydrates tokens from the store at runtime.
On the first deployment, or after a factory reset, the token does not yet exist because the bootstrap
has not run yet. A second common cause is that roles/sys-service-loader/tasks/load_service.yml
skips load/app.yml when the
Matomo container is already reachable. In that case the container is healthy but the token file is still
absent from the token store, so the variable arrives empty.
Behaviour ⚙️
resolve_site.yml resolves the token, queries
SitesManager.getSitesIdFromSiteUrl, registers the site when it is unknown, and leaves matomo_site_id
as the empty string whenever any of those steps cannot complete. An empty token short-circuits the API
call, and an API answer that is not a 200 list leaves the id unresolved the same way.
When matomo_site_id is empty, sys-front-inj-matomo sets inj_enabled.matomo = false for the current
domain. This prevents the NGINX template from rendering the Matomo body snippet (which would reference
matomo_site_id) and skips inject.yml entirely. The play continues without error.
Failing instead of skipping would make the play non-idempotent on first deployment and would block every other application from being configured just because Matomo's bootstrap has not completed yet. Matomo tracking is a best-effort enhancement, not a hard runtime dependency of the target application.
Resolution ✅
Once the Matomo bootstrap has run, either later in the same play or on the next Ansible invocation,
sys-token-store writes the token to disk. On the next play run the token is resolved from the store,
the condition evaluates to false, and inject.yml executes normally: registering the site at Matomo
and injecting the tracking code into the target application.
No manual intervention is required. Re-running the play is sufficient.