Frontend usage analytics — self-hosted Matomo¶
1. Problem¶
Issue #2649: we have no usage data — which modules are opened, which pages are
abandoned, whether the back-office is used at all. We want the ENAC IT4R
self-hosted, open-source option (Matomo at https://enac-webanalytics.epfl.ch/piwik/),
not a third-party SaaS.
The app ships one Vite bundle to dev/stage/prod (docker/entrypoint.sh →
/injectEnv.js → window.injectedEnvVariable), so the Matomo endpoint and the
site id cannot be baked at build time. They must ride the existing runtime
config chain, exactly like APP_SENTRY_DSN.
2. Configuration design¶
Two new APP_* variables, resolved in src/config/runtime.ts with the same
injected || import.meta.env || default cascade as every other value there:
| Variable | Default | Behaviour |
|---|---|---|
APP_MATOMO_URL |
https://enac-webanalytics.epfl.ch/piwik/ |
Code default (like APP_MAP_TILE_STYLE_URL). Trailing slash normalized. |
APP_MATOMO_SITE_ID |
(unset) | The on/off switch. Empty → no script loaded, no requests (like the DSN). |
One Matomo site per instance (dev / stage / prod each get their own site id
from the ENAC analytics admin), rather than one site plus an environment
dimension. Reasons: dev traffic never pollutes prod numbers, retention and
access can differ per site, and turning an instance off is "unset the id".
runtimeConfig.environment is still sent as a custom dimension so a
misconfigured pod is visible in the data rather than silent.
Wiring, mirroring the Sentry chain end to end:
| File | Change |
|---|---|
frontend/.env.example |
Both vars, documented, APP_MATOMO_SITE_ID= empty → local dev is silent. |
frontend/quasar.config.js |
build.env: APP_MATOMO_URL, APP_MATOMO_SITE_ID from process.env. |
frontend/src/env.d.ts |
Two readonly entries on ImportMetaEnv. |
frontend/src/config/runtime.ts |
matomoUrl (with default) and matomoSiteId (no default). |
helm/values.yaml |
frontend.env placeholders + comment that ops repo sets the real site id. |
docs/src/architecture/05-environments.md |
Both rows in the frontend env table. |
docker/entrypoint.sh |
No change — it forwards every APP_* var generically. |
Per-environment values are set in the ops repo (enack8s-app-config /
openshift-app-config), same as the Sentry DSN — no rebuild to enable or
disable analytics on an instance.
3. Tracking client¶
New — frontend/src/utils/matomo.ts (~80 lines, no npm dependency):
initMatomo({ url, siteId, environment })— no-ops without a site id; otherwise seedswindow._paq, applies the privacy config below, and injects<script async src="${url}matomo.js">. Loading Matomo's ownmatomo.jsfrom the configured host (rather than hand-rolling a beacon, as we did for GlitchTip) is deliberate: the tracker is versioned with the server we point at, and opt-out / DoNotTrack / heartbeat / link tracking come for free. It is a runtime script from a configured host, not a new package — no dependency decision to defer to the lead.trackPageView({ url, title, referrer })— pushes onto_paq; safe before the script loads (that is what the array queue is for). Custom URL and referrer are absolute: Matomo resolves a relative URL against the tracker's own host, which would attribute every intra-SPA navigation to the analytics server. The injected<script>carriesreferrerPolicy="no-referrer"so the tracker host never sees an SPA path in theRefererheader.buildTrackedUrl(route)— the normalization described in §4. Pure function, unit-tested.
New — frontend/src/boot/matomo.ts, added to the boot array in
quasar.config.js after sentry:
- Calls
initMatomo(runtimeConfig). router.afterEach→setReferrerUrl/setCustomUrl/setDocumentTitle/trackPageView, the standard Matomo SPA sequence.- Skips entirely when
window.__LIGHTHOUSE_BYPASS__is set, so Lighthouse CI runs don't inflate the numbers. - Errors stay with GlitchTip — nothing about error reporting changes.
4. Privacy posture¶
Non-negotiables baked into initMatomo, not left to server config:
disableCookies()— cookieless tracking, so no consent banner and no new i18n strings. Trade-off: unique-visitor counts become approximate; page-view and module-usage trends, which is what #2649 asks for, are unaffected.- No
setUserId, no sciper, no email. Nothing that identifies a person. - URL normalization. Our paths carry the org unit:
/en/ENAC-IT4R/2024/results. A small unit plus a timestamp is close to identifying, so every param outside the language/year/module allow-list is replaced by_—/en/_/2024/results— while language, year and module stay (they are the interesting dimensions). Query strings are dropped wholesale rather than allow-listed, so a token or filter value can never leak.
Masking is positional: each path segment is judged by the matched route
pattern above it, never by comparing it against param values. Value
comparison would over-mask (a plan id of 2024 blanks the year segment) and,
worse, under-mask — route.path keeps percent-encoding while route.params
is decoded, so a unit needing encoding would sail through unmasked. Splitting
the pattern is depth-aware because an inline regex can contain a slash
(:unit([^/]+)). A segment with no pattern above it (the not-found catch-all)
is masked: the failure direction is losing a dimension, never leaking an id.
setDocumentTitleuses the route name, not the rendered title, for the same reason (rendered titles can contain unit names).- Data stays on EPFL infrastructure; nothing goes to a third party.
If the unit dimension turns out to be needed for a real question later, it is a separate, explicit change (a custom dimension with a documented rationale) — not something we enable by default here.
5. CSP¶
frontend/nginx.conf sets no Content-Security-Policy today, so nothing
blocks this. Noted here because the security-in-depth work (#89) will add one:
it must then allow the Matomo host in script-src, img-src and connect-src,
and the host must come from the same env var rather than being hardcoded.
6. Tests¶
The DOM-touching part of initMatomo is three lines (create script, set src,
append); everything worth asserting is a pure function, so both specs run in the
Playwright CT runner's Node process with no browser harness:
frontend/tests/unit/matomo-url.spec.ts—buildTrackedUrlmasks the unit, masks record ids, masks a param added later (allow-list, not deny-list), keeps language/year/module, drops query strings, handles print routes; andbuildTrackedTitlefalls back to the masked URL, never the raw path.frontend/tests/unit/matomo-init.spec.ts— no site id →isTrackingEnabledfalse andmatomoInitCommandsempty (so no script is injected); with a site id →disableCookiesqueued first, tracker URL and site id set, environment dimension sent,setUserIdnever queued, andtrackerScriptSrcnormalizing an endpoint with or without a trailing slash.- No e2e: integration runs have no site id, so tracking is off by construction — which is what the init spec asserts.
7. Rollout¶
- Request three site ids from the ENAC web analytics admins (dev / stage / prod).
- Merge with all instances unset → zero behaviour change, verifiable in prod.
- Set the dev site id in the ops repo, confirm hits land and that no unit acronym appears in any tracked URL.
- Stage, then prod.
8. Open questions¶
- Should the print routes (
/results/print,/simulation/explore/print) be tracked? They are user-initiated today, so the plan tracks them; excluding them is a one-line change if the numbers look inflated. - Retention on the Matomo side — ENAC default, or a shorter window? Ops call.