kevinveenbirkenbachandClaude Fable 5
40e553069d
Move files that share a delimiter-bounded name prefix within a folder (threshold 2) into a subfolder named after the prefix, dropping the prefix from the filename. Covers plugins/filter (docker, generate, has, merge, get/all), env handler subpackages, utils/roles/entity, utils/tests/swarm/write, role SQL/scripts/templates, keycloak/mailu task-includes, shared tasks/utils/load, and CI scripts. Update every import, query_file/script/include_tasks/src/lookup target, compose bind mount, and python -m path to the new locations. Extend the prefix-grouped-files lint to threshold 2 with dir-level .nocheck and file-head nocheck opt-outs, and skip groups whose shortest member's stem equals the shared prefix. Keep flat only where a loader forbids nesting: WordPress mu-plugins and the docs/requirements namespace. Ansible filter discovery is recursive, so nested filters stay Jinja-resolvable. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2.2 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 ⚙️
When lookup('users', 'administrator').tokens['web-app-matomo'] 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.