# 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`](../../../roles/sys-front-inj-matomo/)
**Variable:** `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 loaded into the `users` runtime variable at play start.

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-utils-service-loader/tasks/load_frontend_service.yml`](../../../roles/sys-utils-service-loader/tasks/load_frontend_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 `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 loaded at startup,
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.