From 73ba25afe325fcd467fa78ba1125332cf0864e48 Mon Sep 17 00:00:00 2001
From: Owen Rees
Date: Tue, 10 Nov 2026 10:12:48 +0100
Subject: [PATCH] Add cookieless Matomo analytics and opt-out (#131) (#133)
* Align Postgres version on 18.6
* Document production tablebase path and permissions
* Add cookieless Matomo analytics with opt-out (#131)
---
README.md | 4 +
assets/js/analytics.js | 105 +++++++++++++++++
assets/js/app.js | 4 +
assets/js/marketing.js | 3 +
config/runtime.exs | 4 +
deploy/README.md | 60 +++++++++-
deploy/postgres.compose.yml | 4 +-
deploy/static/legal.css | 22 ++++
deploy/static/privacy.html | 109 ++++++++++++++++--
docker-compose.yml | 2 +-
docs/analytics.md | 93 +++++++++++++++
docs/tablebases.md | 21 +++-
lib/chesstrainer_web/components/layouts.ex | 44 +++++++
.../components/layouts/root.html.heex | 1 +
.../controllers/page_html/privacy.html.heex | 73 ++++++++++--
.../components/layouts_test.exs | 46 +++++++-
.../controllers/page_controller_test.exs | 6 +-
17 files changed, 572 insertions(+), 29 deletions(-)
create mode 100644 assets/js/analytics.js
create mode 100644 docs/analytics.md
diff --git a/README.md b/README.md
index e5a0475..6ee22f9 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,10 @@ mix tablebase.fetch --path /path/to/syzygy/3-4-5 # once per host (~939 MB)
export TABLEBASE_PATH=/path/to/syzygy/3-4-5 # set per environment
```
+On the production VPS the directory is `/opt/chesstrainer/tablebases`, owned by
+the `chesstrainer` user. Set `TABLEBASE_PATH` in `/etc/chesstrainer/env` and
+restart the service; the value is read at boot.
+
See [docs/tablebases.md](docs/tablebases.md) for the full reference — dev vs
VPS paths, `mix tablebase.check`, and boot logging.
diff --git a/assets/js/analytics.js b/assets/js/analytics.js
new file mode 100644
index 0000000..c4596a7
--- /dev/null
+++ b/assets/js/analytics.js
@@ -0,0 +1,105 @@
+// Cookieless Matomo for anonymous public pages. The server only renders the
+// #matomo-config element for anonymous visitors, so account and admin pages
+// never load a tracker.
+
+const OPT_OUT_KEY = "matomo_optout";
+
+export function isOptedOut() {
+ try {
+ return localStorage.getItem(OPT_OUT_KEY) === "1";
+ } catch (_error) {
+ // If storage is unavailable we cannot remember an opt-out. Fail closed.
+ return true;
+ }
+}
+
+function setOptedOut(optedOut) {
+ try {
+ if (optedOut) {
+ localStorage.setItem(OPT_OUT_KEY, "1");
+ } else {
+ localStorage.removeItem(OPT_OUT_KEY);
+ }
+ } catch (_error) {
+ // Nothing else to do; the current page remains untracked.
+ }
+}
+
+function updateUI() {
+ const optOutButton = document.getElementById("analytics-opt-out");
+ const optInButton = document.getElementById("analytics-opt-in");
+ const status = document.getElementById("analytics-status");
+
+ if (!optOutButton && !optInButton && !status) return;
+
+ const optedOut = isOptedOut();
+
+ if (optOutButton) optOutButton.hidden = optedOut;
+ if (optInButton) optInButton.hidden = !optedOut;
+ if (status) {
+ status.textContent = optedOut
+ ? "Analytics is currently off in this browser."
+ : "Analytics is currently on in this browser.";
+ }
+}
+
+function isPrivatePath() {
+ return window.location.pathname.startsWith("/admin");
+}
+
+function trackPageView() {
+ if (isPrivatePath() || isOptedOut() || !window._paq) return;
+
+ window._paq.push(["setCustomUrl", window.location.href]);
+ window._paq.push(["trackPageView"]);
+}
+
+function loadTracker() {
+ const config = document.getElementById("matomo-config");
+ if (!config || isPrivatePath() || isOptedOut()) return;
+
+ const url = config.dataset.url;
+ const siteId = config.dataset.siteId;
+ if (!url || !siteId) return;
+
+ const _paq = (window._paq = window._paq || []);
+ _paq.push(["disableCookies"]);
+ _paq.push(["setDoNotTrack", true]);
+ _paq.push(["trackPageView"]);
+ _paq.push(["setTrackerUrl", `${url}matomo.php`]);
+ _paq.push(["setSiteId", siteId]);
+
+ const script = document.createElement("script");
+ script.async = true;
+ script.src = `${url}matomo.js`;
+ document.head.appendChild(script);
+}
+
+function handleClick(event) {
+ const target = event.target instanceof Element ? event.target : null;
+ if (!target) return;
+
+ if (target.closest("#analytics-opt-out")) {
+ event.preventDefault();
+ setOptedOut(true);
+ updateUI();
+ return;
+ }
+
+ if (target.closest("#analytics-opt-in")) {
+ event.preventDefault();
+ setOptedOut(false);
+ // The tracker was not loaded while opted out. Reload to start it.
+ window.location.reload();
+ }
+}
+
+export function initAnalytics() {
+ if (window.__matomoInitialised) return;
+ window.__matomoInitialised = true;
+
+ loadTracker();
+ window.addEventListener("phx:navigate", trackPageView);
+ document.addEventListener("click", handleClick);
+ updateUI();
+}
diff --git a/assets/js/app.js b/assets/js/app.js
index 101a591..5e412a1 100644
--- a/assets/js/app.js
+++ b/assets/js/app.js
@@ -21,6 +21,8 @@
import "phoenix_html";
// Plain-DOM mobile navigation (works on controller and LiveView pages).
import "./nav";
+// Cookieless Matomo for anonymous public pages.
+import { initAnalytics } from "./analytics";
// Establish Phoenix Socket and LiveView configuration.
import { Socket } from "phoenix";
import { LiveSocket } from "phoenix_live_view";
@@ -58,6 +60,8 @@ liveSocket.connect();
// >> liveSocket.disableLatencySim()
window.liveSocket = liveSocket;
+initAnalytics();
+
// The lines below enable quality of life phoenix_live_reload
// development features:
//
diff --git a/assets/js/marketing.js b/assets/js/marketing.js
index 1be48b7..48ceeb2 100644
--- a/assets/js/marketing.js
+++ b/assets/js/marketing.js
@@ -2,3 +2,6 @@
// page. Keep this small: no Phoenix Socket, LiveView, hooks, or topbar.
import "phoenix_html";
import "./nav";
+import { initAnalytics } from "./analytics";
+
+initAnalytics();
diff --git a/config/runtime.exs b/config/runtime.exs
index 1462895..70d8b59 100644
--- a/config/runtime.exs
+++ b/config/runtime.exs
@@ -121,6 +121,10 @@ if config_env() == :prod do
System.get_env("SES_SECRET_ACCESS_KEY") ||
raise("environment variable SES_SECRET_ACCESS_KEY is missing")
+ config :chesstrainer, :matomo,
+ url: System.get_env("MATOMO_URL"),
+ site_id: System.get_env("MATOMO_SITE_ID")
+
config :chesstrainer, Chesstrainer.Repo,
# ssl: true,
url: database_url,
diff --git a/deploy/README.md b/deploy/README.md
index 0c34dca..52eebd4 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -19,7 +19,7 @@ Internet
| Elixir | 1.19.5-otp-28 |
| Rust | 1.98.1 |
| Node.js | 24 (asset build only) |
-| Postgres | `postgres:18.0`, pinned directly in the unified compose |
+| Postgres | `postgres:18.6`, pinned directly in the unified compose |
| Caddy | 2.11.9 |
| Docker | 29.9.3 |
| Docker Compose | v5.7.0 |
@@ -137,14 +137,23 @@ SES_SECRET_ACCESS_KEY=...
MATOMO_URL=https://analytics.owenrees.eu/
MATOMO_SITE_ID=6
+TABLEBASE_PATH=/opt/chesstrainer/tablebases
+
# Optional:
-# TABLEBASE_PATH=/path/to/syzygy
# RELEASE_COOKIE=...
```
The production endpoint binds to `127.0.0.1` only. Caddy is the public
entry point.
+## Matomo analytics
+
+Set `MATOMO_URL` and `MATOMO_SITE_ID` to enable cookieless analytics on public
+pages and the guest trainer. Signed-in account and admin pages are excluded.
+
+The privacy controls, Matomo server settings, retention, and opt-out behaviour
+are documented in `docs/analytics.md`.
+
Generate the two secrets:
```sh
@@ -191,6 +200,49 @@ volumes:
- chesstrainer_pgdata:/var/lib/postgresql
```
+## Local tablebases (optional)
+
+The production tablebase directory is `/opt/chesstrainer/tablebases`. Keep the
+`.rtbw`/`.rtbz` files flat in that directory, and make sure the `chesstrainer`
+user can read them:
+
+```sh
+sudo install -d -o chesstrainer -g chesstrainer /opt/chesstrainer/tablebases
+sudo chown -R chesstrainer:chesstrainer /opt/chesstrainer/tablebases
+sudo chmod -R u=rwX,g=rX,o= /opt/chesstrainer/tablebases
+```
+
+Set the path in `/etc/chesstrainer/env`:
+
+```sh
+TABLEBASE_PATH=/opt/chesstrainer/tablebases
+```
+
+Then restart the service, because `TABLEBASE_PATH` is read at boot:
+
+```sh
+sudo systemctl restart chesstrainer
+```
+
+Check `/health`. It should move from `degraded` / `not_configured` to
+`ok` / `local`:
+
+```sh
+curl -s http://127.0.0.1:4100/health
+sudo journalctl -u chesstrainer -n 50 --no-pager | grep -i tablebase
+```
+
+If the path is missing, unreadable, or empty, the app falls back to Lichess and
+health stays `degraded` but still returns 200.
+
+To refresh the files:
+
+```sh
+mix tablebase.fetch --path /opt/chesstrainer/tablebases
+sudo chown -R chesstrainer:chesstrainer /opt/chesstrainer/tablebases
+sudo systemctl restart chesstrainer
+```
+
## First-time setup
Run as root or with sudo:
@@ -223,13 +275,13 @@ Add the `chesstrainer-db` service and `chesstrainer_pgdata` volume from
The image is pinned directly in the unified compose:
```yaml
-image: postgres:18.0
+image: postgres:18.6
```
For an immutable pin, replace it with the exact digest:
```yaml
-image: postgres:18.0@sha256:...
+image: postgres:18.6@sha256:...
```
There is no `POSTGRES_IMAGE` environment variable involved.
diff --git a/deploy/postgres.compose.yml b/deploy/postgres.compose.yml
index c82f481..f80109e 100644
--- a/deploy/postgres.compose.yml
+++ b/deploy/postgres.compose.yml
@@ -3,12 +3,12 @@
#
# Pin the Postgres image directly in the unified file. Replace the tag with
# an exact digest if you want immutable image pinning:
-# image: postgres:18.0@sha256:...
+# image: postgres:18.6@sha256:...
services:
chesstrainer-db:
container_name: chesstrainer-db
- image: postgres:18.0
+ image: postgres:18.6
restart: unless-stopped
env_file: /etc/chesstrainer/postgres.env
ports:
diff --git a/deploy/static/legal.css b/deploy/static/legal.css
index 9926f2b..234c9e2 100644
--- a/deploy/static/legal.css
+++ b/deploy/static/legal.css
@@ -201,6 +201,28 @@ main {
opacity: 0.75;
}
+.analytics-buttons {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 12px;
+ margin-top: 16px;
+}
+
+.analytics-buttons button {
+ padding: 10px 16px;
+ border: 1px solid var(--color-hairline);
+ border-radius: 8px;
+ background: var(--color-canvas-raised);
+ color: var(--color-body);
+ font: inherit;
+ font-weight: 600;
+ cursor: pointer;
+}
+
+.analytics-buttons button:hover {
+ background: var(--color-canvas);
+}
+
.site-footer {
width: min(1180px, calc(100% - 48px));
margin: 0 auto;
diff --git a/deploy/static/privacy.html b/deploy/static/privacy.html
index 48a348f..10b22be 100644
--- a/deploy/static/privacy.html
+++ b/deploy/static/privacy.html
@@ -36,7 +36,7 @@
Privacy Policy
-
Last updated: 6 November 2026
+
Last updated: 10 November 2026
Inner Square Chess is an endgame training site. This policy explains what
@@ -70,6 +70,14 @@
(IP address, browser, timestamps) for security and troubleshooting.
These logs are rotated regularly.
+
+ Usage data.
+ On public pages and the guest trainer, we use a self-hosted Matomo
+ instance to understand aggregate usage. Matomo is configured without
+ cookies, with IP anonymisation, and to respect Do Not Track. We do
+ not use user IDs, track signed-in account pages, or share this data
+ with third parties.
+
Messages you send us.
If you contact us, we keep the message and our reply for as long as
@@ -86,19 +94,50 @@
a session cookie that keeps you signed in;
a CSRF token that protects forms from cross-site requests;
a colour-mode preference stored in your browser.
+
+ an analytics opt-out preference stored in your browser's local
+ storage, if you choose to opt out.
+
We do not use advertising cookies, third-party analytics, or cross-site
- tracking. You can clear these entries at any time in your browser
- settings; doing so will sign you out and reset your colour mode.
+ tracking. Our analytics is self-hosted Matomo and is configured without
+ cookies. You can clear these entries at any time in your browser
+ settings; doing so will sign you out, reset your colour mode, and reset
+ your analytics preference.
+
Analytics
+
+ We use a self-hosted Matomo instance at
+ analytics.owenrees.eu
+ to understand aggregate use of the public site and guest trainer. It is
+ configured without cookies, with IP anonymisation, and to respect Do
+ Not Track. We do not use user IDs, track signed-in account pages, or
+ share this data with third parties.
+
+
+ Raw analytics data is retained for up to 180 days. We process it on the
+ basis of our legitimate interests in improving the service. You can
+ object at any time using the control below or by emailing
+ support@innersquare.app.
+
+
Analytics is currently on in this browser.
+
+
+
+
+
How we use your information
To create and secure your account and sign you in.
To run the trainer and remember your progress.
To send service emails, such as confirmation and password reset links.
To send occasional endgame tips and site news, if you opted in.
+
+ To understand aggregate use of the public site and guest trainer, and
+ improve the service.
+
To keep the site available, prevent abuse, and fix faults.
To respond when you ask for help.
@@ -135,8 +174,10 @@
We do not sell your personal information. We share it only with providers
who help us run the site — for example hosting, database, and email
delivery providers — and only as far as they need it to perform that work.
- We may also disclose information where the law requires it or to protect
- the rights and safety of our users.
+ Self-hosted Matomo analytics is operated by us on infrastructure we
+ control; we do not share that data with third parties. We may also
+ disclose information where the law requires it or to protect the rights
+ and safety of our users.
Retention
@@ -144,16 +185,18 @@
We keep account and training data while your account is open. If you
delete your account, we remove your personal information within a
reasonable period, except where we must keep records for legal, security,
- or accounting reasons.
+ or accounting reasons. We retain raw analytics data for up to 180 days.
Your rights
Depending on where you live, you may have the right to access, correct,
delete, restrict, or export your personal information, and to object to
- some uses of it. To make a request, contact us using the address below. If
- you are in the UK or EU and are unhappy with our response, you can complain
- to your local data protection authority.
+ some uses of it. You can object to analytics processing at any time using
+ the control on this page or by contacting us. To make a request, contact
+ us using the address below. If you are in the UK or EU and are unhappy
+ with our response, you can complain to your local data protection
+ authority.