Compare commits

..
76 Commits
Author SHA1 Message Date
owenrees 2759b34296 Derive only-move, underpromotion and 50-move motif themes (#195)
Motifs describe the kind of problem, independent of the material family. One
local tablebase probe returns the root WDL, the DTZ and every legal move with
its own WDL, so each motif is proved without a search or a remote lookup.

- only move: more than one legal move and exactly one preserves the
  50-move-aware result, for wins and draws.
- underpromotion: a preserving underpromotion exists while no preserving queen
  promotion does.
- 50-move draw: cursed/blessed WDL, or a win whose DTZ exceeds the remaining
  halfmove budget.

Motif links are recorded as derived and refreshed as a whole, scoped to the
motif themes, so material, curated and community links survive. Loss endgames
are skipped because only-move is undefined there.

Stalemate is deferred: a stored endgame cannot itself be terminal, so it can
only describe a line and needs a definition before it becomes a predicate.

Release helpers run the derivation without starting the web application, so
`bin/chesstrainer eval` works on the server.

Closes #188
2026-11-17 22:37:37 +01:00
owenrees e6f08e0ca6 Add a workspace for tagging technique themes by family (#194)
An admin picks a technique theme and sees candidate endgames grouped by Key
with counts. Expanding a family previews its boards without starting a puzzle,
and selecting positions applies the theme in bulk as curated. Large families are
paginated so a 600-endgame group stays usable, and curated links can be removed
from the same surface.

Removal is scoped to curated links, so derived and community links are never
deleted by hand. Material themes are refused because derivation owns them.

Closes #187
2026-11-17 21:55:37 +01:00
owenrees 946fc38756 Derive disjoint material family themes from each endgame's Key (#193)
Every endgame now belongs to exactly one material family derived from its Key:
pawn, rook, rook and pawn, queen, queen and pawn, minor piece, minor piece and
pawn, basic mate, king and pawn, or bare king other. The bare-king families are
split out because those positions teach a mating or promotion technique rather
than a general material class.

Family membership is objective, so a derivation pass owns links to its themes:
refreshing rewrites them as derived and removes a curated link that contradicts
the family, while technique themes are untouched. Re-running is idempotent.

A mix task applies the mapping to the whole library. Seeds add the king
technique themes for later human tagging.

Closes #186
2026-11-17 21:18:11 +01:00
owenrees 80cb033077 Add theme slugs, kinds and link provenance (#192)
* add function for upgrading a user's plan in interactive Elixir

* Add theme slugs, kinds and link provenance

Themes gain a stable slug, an optional description and a kind so the app can
tell material, motif and technique labels apart. Slugs are generated from the
name on first save and keep their value when the theme is renamed, so links to
a theme stay valid.

Endgame-to-theme links now record their source (derived, curated or community)
and creation time. Existing links are backfilled as curated. A derived pass can
therefore replace only its own links, leaving human work untouched.

The admin index shows each theme's kind and its coverage across the library.
Creating a theme name requires the manage_themes capability, and members get an
unauthorized error instead, ahead of the suggestion flow.

Closes #185
2026-11-17 20:46:43 +01:00
owenrees 7209923de7 Align board file labels with their squares 2026-11-17 15:13:47 +01:00
owenrees f4ff1e00fb Move colour mode and Discord controls into the mobile menu 2026-11-17 15:05:02 +01:00
owenrees 514c6ac924 Add Discord invite link to navbar and footer 2026-11-17 15:00:38 +01:00
owenrees e0b446bbfb Weight puzzle selection and stop repeats inside a session (#183)
Selection took a hard rating band (medium = user rating ± 100), removed
everything attempted in the last 30 days, and drew uniformly from what was
left. Because the bulk importer gives every endgame in a batch the same
rating, the band held either the whole library or — once a user's rating
drifted past it — only the endgames that user had already played. With
`fresh` empty, the fallback re-drew from the same band ignoring recency, so
recently played puzzles came straight back. An empty band used a
deterministic nearest-match, alternating between the same two puzzles.

Difficulty is now a bias rather than a filter: candidates are weighted by
`exp(-|rating - target| / spread)` and drawn with an exponential race, so
the whole library stays reachable and a thin region around the user's rating
can never empty the pool. `easy` and `hard` keep one-sided guards so the
labels stay honest. When every candidate is excluded, selection serves the
least recently attempted endgame instead of a random recent one.

Sessions now carry the ids they have served, which fixes the observed
in-session repeat (only the current puzzle used to be excluded), and guest
training gets the same treatment. The 30-day window is configurable as the
repeat window and is now named in GLOSSARY.md, distinct from the rating
window and from the tablebase cooldown.

Difficulty copy is qualitative, since the band numbers no longer describe
how selection works.
2026-11-17 14:28:24 +01:00
owenrees fa1fef7b62 Launch amendments: one login, crawler policy, and asset caching (#180)
* lesson library shown as com,ing soon. re-enable learngin strip

* replace learning strip text with a lasker quote

* remove admin login endpoint

* fix crawler directives and prelaunch login

- noindex the authenticated scope and the 404 catch-all, and cover the
  mailing-list confirmation redirect
- emit noindex, nofollow from the robots meta and /health, and assert
  public pages stay indexable and followable
- stop inventing lastmod values in the sitemap
- log in through /users/log-in during prelaunch now that the admin login
  endpoint is gone; drop create_admin/2 and its orphaned tests

* update caching length to 1 year - name change will invalidate cache

* remove logger

* fix tablebase path breaking tests

* test: check cache headers without requiring built assets

CI's test job does not run mix assets.build, so /assets/css/app.css is a
404 there. Committed piece art is already content-hashed and takes the same
Plug.Static cache option, so the test no longer needs a build step and
passes on a fresh checkout.
2026-11-17 12:55:47 +01:00
owenrees 37e0ac8e56 Transactional mail, crawler metadata, and asset measurement (#179)
* Send transactional email from no-reply@mail.innersquare.app

Centralise the sender identity, reply-to address and SES configuration set in Chesstrainer.Mail so no notifier can drift. Add MAIL_REDIRECT_TO for smoke tests and a mix mail.check task that exercises the SES mailbox simulators, and document the setup in the deploy guide and .env.example.

* Tighten crawler metadata and keep play pages out of search

Canonical URLs no longer carry query strings, public pages get an OG image, WebSite JSON-LD and a per-page language, and the sitemap dates the landing page only. Play and guest-training routes are marked noindex so tens of thousands of near-identical pages stay out of the index.

* Measure built asset sizes with mix assets.sizes

Report raw, gzip and brotli sizes for built JS and CSS, and record the current numbers plus the board-code split recommendation in docs/assets.md.
2026-11-17 10:29:45 +01:00
owenrees b33c5e334a Update to OTP 29 / Elixir 1.20 and refresh dependencies (#175) 2026-11-15 09:34:15 +01:00
owenrees aebb2aecfb Fix the error-state regressions from the #164 verification (#171) (#173)
T8: the invalid-FEN flash is generic; the client message and FEN go to the
log. A2: an expired confirmation link says so and lands on log-in, where an
unconfirmed account resends the email. W3: the connection banner gains Reload
and Home actions. D1: a failed export logs and redirects to the data tab with
a support address instead of a bare 500. D2: an unknown export format renders
the styled 404. H1: the empty-database home CTA points at the guest trainer
instead of auth-gated /endgames. X2/X3: the importer hides inspect(reason)
behind generic copy and logs it.

Adds coverage for the T8 copy, A2 destination, D2 404 page, H1 CTA and the W3
actions; the H1 tests now restore the curated-code override so async page
tests cannot poison each other.
2026-11-13 16:46:29 +01:00
owenrees 8934d191ad Record the launch observability decision and verify the error states (#172)
ADR 0012 states the launch bar, the deferred error tracking/metrics/log
shipping with a concrete revisit trigger for each, and the accepted risk of
journald plus off-box backups.

The verification page walks the #162 checklist against a local MIX_ENV=prod
build with forced failures: Postgres stopped, missing tablebase, empty pool,
expired tokens and exhausted guest budget. 14 rows pass, 6 fail; the eight
regressions are filed in #171. The audit's X1 row is corrected: an unknown
play code already returns the styled 404 page.
2026-11-13 16:10:42 +01:00
owenrees 021e412167 Make tablebase and empty-pool failures recoverable (#163) (#170)
Tablebase failures now render one message per class, with a Retry action
when fetching again can help. The generic class no longer interpolates
inspect(reason) into the page; the reason goes to the log instead.
Positions outside the tablebase offer the next puzzle (in a session) or the
existing back link, rather than a futile retry.

Train's no-puzzles and exhausted-difficulty flashes become in-page states
with Retry and Change difficulty. The guest pool gets the same treatment,
and GuestLimits.remaining/1 lets a guest see the wall, or the empty pool,
without spending a puzzle.
2026-11-13 15:36:59 +01:00
owenrees 0563b5aca2 Audit the user-facing error states (#162) (#169)
Records 35 states across play, sessions, accounts, mailing list, site-level, data and admin surfaces, each with its trigger, today's copy, a verdict and a concrete action. Calls out the five places where an internal detail can reach rendered HTML, and closes with the sign-off checklist for #164.
2026-11-13 15:04:30 +01:00
owenrees 0ae4c5b6fd Record the probe outage drill and its outcome (#168)
Adds the stop-Phoenix drill to the runbook, using forced probe runs so the
outage stays under a minute, and a dated drill log with the first run's
results. The log notes that the manual probe was started twice during the
outage, which is why two notifications arrived for one down/up transition.
2026-11-13 14:48:01 +01:00
owenrees b41c8bf1a6 Fix deploy docs: Bot Fight Mode status and probe reinstall (#167)
* Record that Bot Fight Mode is off

Both docs still claimed Bot Fight Mode was enabled. It is off; the Caddy
origin allowlist stays in force. Neither CI nor the on-box probe can get
past it on the free plan, so re-enabling needs the changes tracked in #153.

* Note that the probe must be installed to two places

The timer runs /usr/local/sbin/chesstrainer-probe, not the copy under
/opt/chesstrainer/src. Say so next to the install block, as the backup
section already does, so a changed deploy/probe does not silently drift
from what the timer runs.
2026-11-13 13:57:33 +01:00
owenrees 69b89f68ef Add a public health probe and monitoring runbook (#166)
* move theme picker position in add endgames form

* Add branded favicons and web manifest

- Replace the placeholder favicon with the knight mark: .ico (16/32/48),
  SVG, and 16/32 PNGs.
- Add opaque apple-touch and Android launcher icons plus a site
  webmanifest naming the app and using the brand palette.
- Link the icon set, manifest, and theme-color from the root layout and
  the 404/500 pages.
- Whitelist the new static files in static_paths/0 and the prelaunch
  allowlist so they are served in production and behind the gate.
- Sync the coming-soon site's favicon.ico and drop the unused Phoenix
  logo.

* Add a public health probe and monitoring runbook

Probe https://<PHX_HOST>/health through Cloudflare every two minutes and
report to a healthchecks.io check. A healthy run posts the raw health JSON;
a tablebase mismatch is a green check-in with the mismatch recorded; a
non-200, non-JSON, down database or network failure posts one fail ping with
the response body and a loopback cross-check as evidence.

--dry-run evaluates the success, degraded, fail, non-JSON and unreachable
fixtures without reading config or touching the network. The runbook covers
the healthchecks.io check, install, what /health proves, Beszel's blind spot
and the drills.

* Fix theme picker search after moving it into the endgame form

The picker moved inside the endgame form, which nested the component's
own <form>. Browsers, and the LiveView test DOM, drop a nested form along
with its phx-change and phx-submit bindings, so the search box did nothing
and three form tests lost their #theme-form selector.

The component now renders no form: phx-change sits on the search input,
which works both inside the endgame form and standalone on the bulk
importer. The unreachable create_theme_from_search handlers go away; theme
creation uses the existing button. Tests search through the input and
click that button.
2026-11-13 13:24:35 +01:00
owenrees f27e16af1d Allow bulk importer through prelaunch gate (#159)
The new EndgameLive.Import view was missing from the prelaunch allowlist, so PRELAUNCH=true redirected it to the home page.
2026-11-12 22:58:34 +01:00
owenrees fddb94e2bd Add admin bulk FEN importer (#156)
* change position of theme picker

* Add admin bulk FEN importer

Paste FENs, resolve results from the local Syzygy tablebase only, preview each line's status, and bulk insert with themes and a batch rating.
2026-11-12 22:44:13 +01:00
owenrees 20b53dae6f Show rating changes on puzzle completion (#146) (#154)
* Show rating changes in flashes and session UI (#146)

- Flash the new rating and delta on every rated completion, with a
  dedicated success flash kind for solved puzzles
- Move flash notifications to the top-left
- Add a colour-coded rating-change pill and show the current rating with
  the session's net change in the train session bar
- Show the user's rating and change beside the puzzle rating after an
  attempt, and show the finishing rating in the last-session summary

* fix header component and start reusing it

* Hide the sign-up link on the prelaunch admin login

The header refactor dropped the @prelaunch guard, so the gated admin login linked to the public registration page again.
2026-11-12 21:13:54 +01:00
owenrees 9e76045862 Automate, verify, and ship database backups off-box (#145) (#152)
The VPS now takes a daily logical dump, verifies it, encrypts it, and hands
it to a workstation; a monthly drill proves the archive restores.

- deploy/backup: pg_dump -Fc plus pg_dumpall --globals-only, pg_restore -l
  and globals-role checks before anything is promoted, row counts for the
  drill, sha256, age encryption into offsite/, retention (3d plaintext,
  14d encrypted, 5 pre-deploy sets), JSON logging and a healthchecks.io
  heartbeat
- systemd service and timer (03:15 UTC, Persistent, jittered) plus an
  OnFailure unit that logs a distinct event
- deploy/activate takes a pre-deploy dump after extracting and before
  flipping current, because migrations run in ExecStartPre; a failed dump
  aborts the activation, with SKIP_PRE_DEPLOY_BACKUP=1 as the escape hatch
- deploy/workstation/backup-pull: rsync the encrypted archives over SSH,
  verify by decrypting and checking the inner sha256, retain 7d/4w/6m, and
  fail when the newest archive is older than 48h
- deploy/workstation/backup-drill: restore the newest archive into a
  throwaway postgres:18.6, replay the globals dump as the same superuser,
  assert both roles, compare users/endgames/attempts, and append the result
  to drills.log
- user units for the daily pull and monthly drill, with a shared OnFailure
  alert template
- docs: install, key handling, retention, restore, disaster recovery, a run
  by hand section, monitoring and troubleshooting

Verified against production: the first backup completed and pinged the
heartbeat, the pull verified the archive, and the drill restored
users=1 endgames=39 attempts=0, matching the live database.
2026-11-11 22:59:54 +01:00
owenrees 624ddab644 Admin panel, login throttling, and Cloudflare edge hardening (#150)
* Document the remote shell for production user management

* add sitemap to footer links

* remove border under theme selection

* Add admin theme and user management (#144)

Add /admin/themes CRUD and /admin/users list/detail with role and plan editing, guarded by a shared Policy module. Include last-super-admin and self-role protections plus structured id-only admin logs.

Also add admin invitations, confirmation resends and password-reset emails, which work in development through the Swoosh mailbox before SES is configured.

* Rate-limit password logins and emit auth events (#142)

Add a two-bucket login throttle (5 failures per login, 10 per IP in a 15-minute window) and a shared client-address helper for controllers and LiveViews. Blocked attempts skip the database and bcrypt.

Log auth.login.failed and auth.login.throttled warnings with boot-scoped HMAC addresses only, and stop repeated confirmation emails on unconfirmed login attempts.

* Harden the production login edge for Cloudflare

Document the layered login defence: the app throttle is primary, Caddy must pass Cloudflare's CF-Connecting-IP to the app, and Cloudflare edge rate limiting covers request floods.

Update the reference Caddyfile to accept only Cloudflare ranges and reject direct-to-origin traffic, and document the exact Cloudflare dashboard rules.

* Document 10-second Cloudflare rate-limit window

Cloudflare may only offer a 10-second period. Keep the edge rule at 10 login POSTs per 10 seconds per IP and rely on the app's 15-minute login/address throttle for credential guessing.

* Document Cloudflare limits for LiveView registration

Registration submits over the shared LiveView socket, so a Cloudflare rule on POST /users/register will not count account creations. Note the app-level throttle/Turnstile options instead.

* Document current Cloudflare free-plan edge controls

Record the production setup: Cloudflare-only Caddy origins, Bot Fight Mode, and the 10-second login flood rule (10 POSTs per 10 seconds, 10-second block). Clarify that the application's 15-minute throttle remains the real credential lockout.

* Auto-refresh Cloudflare CIDRs for Caddy

Move the origin allowlist into a generated cloudflare-ranges.caddy imported by Caddy. Add an hourly systemd timer and script that fetch Cloudflare's v4/v6 lists, reject malformed responses, validate the candidate Caddyfile, and reload Caddy only when the ranges change. Restore the previous file on validation or reload failure.

* Document Cloudflare CIDR refresher setup and operations

Record the installed paths, permissions, timer checks, manual run, update procedure, and the direct-on-VPS setup fallback when the deploy directory is absent.
2026-11-11 21:27:59 +01:00
owenrees 202b9b1f6a Add structured production logging (#105, #107) (#141)
* Update README.md

* Add structured JSON production logging (#105)

* Log requests and background failures (#107)

* Document production logging and the VPS runbook
2026-11-10 22:00:05 +01:00
owenrees f8897fa5ae Add French legal notice and complete privacy disclosures (#134)
- Add /mentions-legales (LCEN art. 6-III): publisher, SIRET, VAT status,
  publication director, and host details
- Name the data controller in the privacy policy and the terms
- Disclose Hetzner/Cloudflare hosting, third-country transfers, the CDN
  security cookie, and backup/suppression-list retention
- Remove the children section; the age floor now lives in the terms
- State that request logs are kept by the providers, not by us
- Mirror all changes in the pre-launch static site

The publisher address is a placeholder pending a domiciliation address.
2026-11-10 11:41:40 +01:00
owenrees 73ba25afe3 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)
2026-11-10 10:12:48 +01:00
owenrees be57f21729 Add manual CD dispatch and deployment docs (#128) 2026-11-10 09:29:20 +01:00
owenrees ee687dfb2d update with deploy job 2026-11-10 09:27:40 +01:00
owenrees fa90e1102d pin action versions 2026-11-10 09:15:06 +01:00
owenrees 2821f8e984 Avoid stale _build cache in CI 2026-11-10 08:49:53 +01:00
owenrees fda52dd2e7 Install npm assets in CI release build and pin Node 2026-11-10 08:47:46 +01:00
owenrees 7463784e03 update checkout version 2026-11-10 08:43:02 +01:00
owenrees f024bc608d Make endgame fixtures generate unique FENs 2026-11-10 08:42:29 +01:00
owenrees f12ae0b81f Add CI workflow with test and release build (#127) 2026-11-10 08:34:44 +01:00
owenrees 8b25020737 Document SECRET_KEY_BASE requirements 2026-11-09 22:31:07 +01:00
owenrees 56d51347b9 Add JSON health check with database and tablebase status (#106) 2026-11-09 22:24:09 +01:00
owenrees 4c39f231f1 Document VPS provisioning and guard the service before first release (#125) 2026-11-09 22:19:20 +01:00
owenrees b1767e5fbc Add production release and VPS deploy artifacts (#123, #124) 2026-11-09 22:03:54 +01:00
owenrees 3a849ddff0 update matomo env vars 2026-11-09 20:52:37 +01:00
owenrees 79782dc778 prelaunch env var prevents the site from being operational 2026-11-09 20:49:25 +01:00
owenrees 9d3dd426db update static site with privacy and terms 2026-11-09 20:24:28 +01:00
owenrees cae4e35a70 Set up SES mail delivery and harden the mailing list (#120)
* setup basic SES email sending

* basic honeypot form form submission
2026-11-09 16:38:55 +01:00
owenrees 5b3241ae1f Feature/static (#118)
* commented out lesson and learning strip until lessons are established

* reword the hero section

* change layout and working on puzzle section - remove top div as it was
redundant

* amend flash message on replay

* switch cancel session for return home

* remove system theme toggle since this is the default, leaving only light
and dark toggles

* add keyboard and screen reader support for play (#72)

First draft covering the accessibility work in #72:\n\n- labelled SAN/UCI move input, validated against the tablebase and applied\n  by the board hook, plus an accessible promotion picker\n- live-region announcements for moves, checks, checkmates and solve/fail,\n  and a hidden text summary of the position\n- accessible labels, focus ring, skip link, keyboard-friendly review table\n  and non-colour grade cues\n- WCAG AA text contrast roles and a responsive play surface\n- regression tests for move entry, announcements and link-style CTAs

* static pre-release page
2026-11-09 12:50:04 +01:00
owenrees 805c2f1150 Accessibility: keyboard move entry and screen reader support (#72) (#115)
* commented out lesson and learning strip until lessons are established

* reword the hero section

* change layout and working on puzzle section - remove top div as it was
redundant

* amend flash message on replay

* switch cancel session for return home

* remove system theme toggle since this is the default, leaving only light
and dark toggles

* add keyboard and screen reader support for play (#72)

First draft covering the accessibility work in #72:\n\n- labelled SAN/UCI move input, validated against the tablebase and applied\n  by the board hook, plus an accessible promotion picker\n- live-region announcements for moves, checks, checkmates and solve/fail,\n  and a hidden text summary of the position\n- accessible labels, focus ring, skip link, keyboard-friendly review table\n  and non-colour grade cues\n- WCAG AA text contrast roles and a responsive play surface\n- regression tests for move entry, announcements and link-style CTAs
2026-11-09 12:09:07 +01:00
owenrees 8df7ac982c change header and paragraph sizes 2026-11-09 10:12:02 +01:00
owenrees aa9c882b08 update brand 2026-11-09 08:32:50 +01:00
owenrees eaf72a7686 add sitemap, robots, and noindex admin routes (#85)
Serve a runtime sitemap.xml with the indexable marketing pages only; endgame play pages are left out to avoid indexing tens of thousands of near-identical pages. Generate robots.txt at runtime so it points at the sitemap on the deployment's host, and send X-Robots-Tag: noindex from every /admin response.
2026-11-06 23:04:10 +01:00
owenrees 924a3e08dc add mailing list signup with email confirmation (#67) 2026-11-06 22:37:40 +01:00
owenrees b54fb0a6d7 show logged-in player count in landing hero
Count distinct users with a session token valid within the 14-day window and use it for the hero players-training stat. The learning strip keeps the total player count.

Also load the split seed modules in seeds_test and drop an invalid 8-piece seed FEN so precommit passes.
2026-11-06 22:11:06 +01:00
owenrees 46bc27f614 change header size and rating placement 2026-11-06 22:03:24 +01:00
owenrees f2d886d602 add visual rating guide (#48) 2026-11-06 21:52:07 +01:00
owenrees 64a9210580 change stats 2026-11-06 21:48:12 +01:00
owenrees 5c8d2494b6 seed Lucena endgame 2026-11-06 21:34:51 +01:00
owenrees 1003ec203a reorder seed so that themes can be added to seed endgames 2026-11-06 21:25:11 +01:00
owenrees f9340fb57b add small board to show fen string on endgame add 2026-11-06 21:19:25 +01:00
owenrees c71f465487 Add user profile hub with account, settings and data export (#103) 2026-11-06 21:13:37 +01:00
owenrees f5efcde5ca back home button on daily puzzle 2026-11-06 19:51:27 +01:00
owenrees bf176ebd42 show error page puzzle link only for premium users 2026-11-06 15:47:53 +01:00
owenrees 785e403370 404 and 500 drafts 2026-11-06 15:42:52 +01:00
owenrees b17f346b25 Show tablebase moves during review (#65) (#102)
* engine 8+ tablebase adr

* Show tablebase moves during review (#65)

- group reviewed moves by winning/drawn/losing and make each row playable
- move review navigation under the board with start/end jumps
- give review a full-height scrollable tablebase pane
2026-11-06 15:31:11 +01:00
owenrees bd8be4d10d Privacy and terms pages with config-driven branding (#91)
* comment out begin with basics until lessons are on the way

* route to footer link dead views

* proposed >7 piece engame processing

* basic privacy and terms pages with default text

* add branding to config and reference across the site

* disclose guest puzzle limit in privacy policy (#87)
2026-11-06 13:56:20 +01:00
owenrees 6a4288bb6c split endgame seed files by result 2026-11-06 12:49:03 +01:00
owenrees dda588da06 Feature/guest trainer (#89)
* add anonymous guest training with a daily puzzle limit

- /guest-train serves random endgames with no difficulty picker; signed-in
  visitors are redirected to /train
- guests get 5 puzzles per UTC day, keyed by an in-memory HMAC of the client
  address; the raw address is never stored or logged
- a sign-up wall replaces the next puzzle once the budget is spent
- move the endgame library behind auth so guests cannot browse it
- privacy disclosure tracked in #87

* remove chess-test endpoint and liveview
2026-11-06 12:06:32 +01:00
owenrees 2c5e290e66 remove roadmap and todo in favour of project based overview 2026-11-06 10:41:08 +01:00
owenrees 2f3f39a21d show live player count on landing page 2026-11-05 16:40:58 +01:00
owenrees 8d1876b13b show date, hide puzzle search for non premium 2026-11-05 16:14:04 +01:00
owenrees 0453e97897 update navbar and footer links
- point Puzzle Search at the endgames list
- list the signed-in username after Settings and Log out
- replace the footer's landing anchors with privacy and terms links
- align the landing-page test with the new footer
2026-11-05 15:52:56 +01:00
owenrees 1b44dae378 let the difficulty picker be closed
Add an X in the corner and a Cancel button, both returning home, so a user
who opens /train without wanting a session is not stuck in the modal.
2026-11-05 15:50:17 +01:00
owenrees 84eee4057e restyle flash toasts and auto-dismiss them
- use brand info/error colours that pass AA contrast in both modes
- dismiss flashes on click on controller pages, where no LiveView handles it
- auto-dismiss real flashes after a few seconds
- keep connection notices pinned until the connection recovers
2026-11-05 15:44:42 +01:00
owenrees 55d2e2a913 add puzzle training sessions with difficulty and ratings
- /train starts an ephemeral session by choosing easy/medium/hard, banded
  relative to the user's current rating (band width configurable)
- session timer, average per-puzzle time, net rating gain and per-puzzle delta
- next puzzle, plus review and retry reused from the play surface
- explicit stop/start: stopping returns to the difficulty picker
- puzzle rating shown once a puzzle completes, and a side-to-move indicator
- extract the play logic/markup into shared PlayCore and PlayComponents so the
  standalone play view and sessions share one implementation
- sticky footer; glossary entries for Difficulty and Session; ADR 0009
2026-11-05 15:44:11 +01:00
owenrees c95173cda8 password reset flow 2026-11-05 14:19:49 +01:00
owenrees e89df68e7d email signup up flow in dev mode, therefore in place for prod 2026-11-05 14:11:12 +01:00
owenrees 6b0e0ed352 add margin top to subtitle 2026-11-05 13:57:15 +01:00
owenrees 93806b9ab2 landing page (#63)
* remove daisyui and rebuild styles

* very basic setup of new design - missing components etc

* basic navbar with reusable landing components

* basic puzzle of the day

* update todos

* update todos

* add curated landing puzzle cards with selectable board (#55)

* update with footer

* add button to solve today's puzzle

* Make landing page a dead view

Render the home page from PageController with a static board preview, link puzzle cards and CTAs to public-code play routes, count puzzles from the DB, and add a global footer.

* Serve a marketing-only JS bundle on the landing page

Build a small marketing entry point with phoenix_html and the plain-DOM navbar, select it on controller-rendered pages, and keep the full LiveView bundle for LiveView pages.

* Add landing page SEO metadata

Replace the Phoenix default title with a descriptive Lucid Chess title, and add description, canonical, Open Graph, and Twitter card tags to the landing page.

* Complete the hero copy block

Add the spark icon primitive and the Endgames, made clear eyebrow. The primary CTA keeps linking to the active puzzle rather than scrolling to the board.

* Add a persisted global daily puzzle

Assign one endgame per UTC day in a daily_puzzles table with a unique date, preferring endgames unused in the last 30 days and falling back to any. Concurrent first requests insert with on-conflict-ignore and read the winning row. The landing board now shows the daily puzzle.

* remove unused CSS, nav links, time pill

* allow devices to connect to dev server by changing IP address to 0.0.0.0

* Restore the colour-mode switch and add a dark palette

* Use brand colour tokens on the play page

* self host fonts  - closes issue #62

* begin splitting CSS into modules

* remove hover on hero chessboard, split more css modules

* remove interactivity from hero chessboard

* update todo
2026-11-05 13:52:14 +01:00
owenrees fd6277ef92 add initial todo and roadmap 2026-11-04 20:18:31 +01:00
owenrees 1012c74d60 Let users delete their account from settings (#46) 2026-11-04 19:59:12 +01:00
289 changed files with 26256 additions and 12432 deletions
+19
View File
@@ -0,0 +1,19 @@
SECRET_KEY_BASE=...
DATABASE_URL=...
PHX_HOST=innersquare.app
PORT=4000
PRELAUNCH=true
MAILING_LIST_ENABLED=false
SES_REGION=eu-north-1
SES_ACCESS_KEY_ID=AKIA...
SES_SECRET_ACCESS_KEY=...
SES_CONFIGURATION_SET=my-first-configuration-set
# Optional: override the sender or send everything to one address while testing.
# MAIL_FROM=no-reply@mail.innersquare.app
# MAIL_REDIRECT_TO=you@example.com
# Optional: directory of local Syzygy .rtbw/.rtbz files. Ignored by the test
# suite, which always uses the committed 3-piece fixtures.
TABLEBASE_PATH=
MATOMO_URL=https://analytics.owenrees.eu/
MATOMO_SITE_ID=6
+137
View File
@@ -0,0 +1,137 @@
name: CI
on:
pull_request:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
test:
name: Test
runs-on: ubuntu-24.04
env:
MIX_ENV: test
services:
postgres:
image: postgres:18.6
env:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
ports:
- 5432:5432
options: >-
--health-cmd "pg_isready -U postgres"
--health-interval 5s
--health-timeout 5s
--health-retries 10
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #v7.0.1
- uses: jdx/mise-action@b44d12e7d0d8ee7461bb893e1b1993500433185b #v5.2.7
- uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 #v6.1.0
with:
path: |
deps
~/.cargo/registry
~/.cargo/git
key: ${{ runner.os }}-mix-test-${{ hashFiles('mix.lock', 'mise.toml') }}
restore-keys: |
${{ runner.os }}-mix-test-
- run: mix local.hex --force
- run: mix local.rebar --force
- run: mix deps.get
- run: mix format --check-formatted
- run: mix precommit
build-release:
name: Build release
needs: test
runs-on: ubuntu-24.04
env:
MIX_ENV: prod
SECRET_KEY_BASE: build-only-secret-key-base-build-only-secret-key-base-build-only-secret-key-base
DATABASE_URL: ecto://postgres:postgres@127.0.0.1:5432/chesstrainer_build
SES_REGION: eu-north-1
SES_ACCESS_KEY_ID: build
SES_SECRET_ACCESS_KEY: build
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #v7.0.1
- uses: jdx/mise-action@b44d12e7d0d8ee7461bb893e1b1993500433185b #v5.2.7
- uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 #v6.1.0
with:
path: |
deps
~/.cargo/registry
~/.cargo/git
assets/node_modules
key: ${{ runner.os }}-mix-prod-${{ hashFiles('mix.lock', 'mise.toml', 'assets/package-lock.json') }}
restore-keys: |
${{ runner.os }}-mix-prod-
- run: mix local.hex --force
- run: mix local.rebar --force
- run: npm ci --prefix assets --no-audit --no-fund
- run: mix deps.get --only prod
- run: mix assets.setup
- run: mix assets.deploy
- run: mix release
- run: tar -czf chesstrainer-release.tar.gz -C _build/prod/rel/chesstrainer .
- uses: actions/upload-artifact@v4
with:
name: chesstrainer-release
path: chesstrainer-release.tar.gz
retention-days: 7
deploy:
name: Deploy
needs: build-release
if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
runs-on: ubuntu-24.04
environment: production
concurrency:
group: production
cancel-in-progress: false
steps:
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 #v8.0.2
with:
name: chesstrainer-release
- name: Install SSH key
run: |
mkdir -p ~/.ssh
printf '%s\n' "${{ secrets.VPS_SSH_KEY }}" > ~/.ssh/id_ed25519
chmod 600 ~/.ssh/id_ed25519
printf '%s\n' "${{ secrets.VPS_KNOWN_HOSTS }}" > ~/.ssh/known_hosts
chmod 644 ~/.ssh/known_hosts
- name: Upload release
run: |
scp -i ~/.ssh/id_ed25519 -o BatchMode=yes \
chesstrainer-release.tar.gz \
"${{ secrets.VPS_USER }}@${{ secrets.VPS_HOST }}:/tmp/chesstrainer-release.tar.gz"
- name: Activate release
run: |
ssh -i ~/.ssh/id_ed25519 -o BatchMode=yes \
"${{ secrets.VPS_USER }}@${{ secrets.VPS_HOST }}" \
'sudo -n /opt/chesstrainer/src/deploy/activate /tmp/chesstrainer-release.tar.gz'
- name: Public smoke test
run: |
curl -fsS https://innersquare.app/health
curl -fsS -o /dev/null https://innersquare.app/
+5 -1
View File
@@ -31,8 +31,12 @@ chesstrainer-*.tar
# Ignore ETS table backups
/priv/static/backups/
# Ignore digested assets cache.
# Ignore digested assets cache and generated digests.
/priv/static/cache_manifest.json
/priv/static/favicon-*.ico
/priv/static/fonts/*-*.woff2
/priv/static/images/*-*.svg
/priv/static/images/*.svg.gz
# In case you use Node.js/npm, you want to ignore these.
npm-debug.log
+47 -3
View File
@@ -12,18 +12,32 @@ _Avoid_: Position, puzzle
**Puzzle**:
A playable challenge derived from an endgame: play the winning (or drawing)
side correctly against tablebase-optimal defence.
side correctly against tablebase-optimal defence. Each endgame currently
yields one puzzle.
_Avoid_: Endgame (the stored record), exercise
**Daily puzzle**:
The one endgame assigned to a UTC date and shared by every user; the
assignment is persisted so it stays stable for that day.
_Avoid_: Random puzzle, featured puzzle
**Attempt**:
A recorded playthrough of a puzzle by a user, ending solved or failed; a
per-user record, distinct from an endgame's global attempt and solve counts.
_Avoid_: Run, session, game
_Avoid_: Run, game
**Theme**:
A label describing an endgame's technique or goal, such as "mate in 2", "Lucena" or
"opposition"; an endgame can carry several.
_Avoid_: Tag, label, category
_Avoid_: Tag, label, category, UI theme, colour mode
## Interface
**Colour mode**:
A user's display preference for the interface — `system`, `light` or `dark` — where
`system` follows the operating system setting. It is a per-browser preference,
independent of any user account.
_Avoid_: Theme, colour scheme, display theme
**Key**:
The canonical material signature of an endgame's starting position — which
@@ -50,6 +64,12 @@ _Avoid_: Permission, access level
A user's subscription tier — `free` or `premium` — independent of their role.
_Avoid_: Tier, subscription, membership
**Mailing list**:
Email addresses that opted in to occasional product updates, collected from the
landing-page form or the registration checkbox; a subscriber need not have an
account.
_Avoid_: Newsletter, subscription (reserved for the premium plan)
## Play
**Winning side**:
@@ -79,6 +99,20 @@ The decisive zeroing move — a promotion — that ends a conversion-type puzzle
The terminal condition short of mate at which a puzzle counts as solved:
promotion (still winning) for conversion puzzles, mate otherwise.
**Session**:
One continuous spell of puzzle play, begun by choosing a difficulty, that
carries a start time and a rating baseline for the timer and rating-gain
monitor. Ephemeral — it lives only in the running LiveView, never persisted.
_Avoid_: Run, game, attempt
**Repeat window**:
The minimum interval before the same endgame may be served to the same user
again. Selection skips endgames attempted inside the window; only when nothing
else is available does the least recently attempted endgame come back. It is
independent of the rating window, which decides whether a replay may move a
rating.
_Avoid_: Cooldown (reserved for tablebase rate-limiting), due date
## Ratings
**Rating**:
@@ -101,6 +135,16 @@ A measure of how erratic a competitor's recent results are, used by some rating
systems; the trainer deliberately does not track it.
_Avoid_: Variance, inconsistency
**Difficulty**:
A choice — `easy`, `medium` or `hard` — that biases which puzzles are served
relative to the current user's rating: `medium` centres on the user's rating,
`easy` below it, `hard` above it. Candidates are weighted by how close their
rating is to that centre, so a session draws mostly from near the target but the
whole library stays reachable. The spread is a configured constant. It is a
property of a session, not of an endgame — the same endgame is easy for one user
and hard for another.
_Avoid_: Level, rank, tier
## Infrastructure
**Tablebase**:
+12
View File
@@ -21,9 +21,21 @@ 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.
## Logging
Production logs are one JSON object per line so they can be filtered with
`journalctl` and `jq`; development and test keep the readable formatter. See
[docs/logging.md](docs/logging.md) for the line shape, redaction rules and the
background-work audit, and [`deploy/README.md`](deploy/README.md) for the VPS
runbook.
## Learn more
* Official website: https://www.phoenixframework.org/
-7
View File
@@ -1,7 +0,0 @@
.bg-boardwhite {
background-color: #f2f5f3; /* light square */
}
.bg-boardblack {
background-color: #71828f; /* dark square */
}
+58 -98
View File
@@ -4,116 +4,76 @@
@import "tailwindcss" source(none);
@import "phoenix-colocated/chesstrainer/colocated.css";
/* Chessground imports */
@import "../node_modules/chessground/assets/chessground.base.css";
@import "../node_modules/chessground/assets/chessground.brown.css";
@import "../node_modules/chessground/assets/chessground.cburnett.css";
@import "./_board.css";
@import "./_promotion.css";
@import "./helpers/_variables.css";
@import "./base/_theme.css";
@import "./base/_globals.css";
@import "./base/_typography.css";
@import "./layouts/_nav.css";
@import "./layouts/_footer.css";
@import "./layouts/_hero.css";
@import "./layouts/_section.css";
@import "./components/_icon.css";
@import "./components/_button.css";
@import "./components/_learning-strip.css";
@import "./components/_mailing-list.css";
@import "./components/_board.css";
@import "./components/_promotion.css";
@import "./pages/_legal.css";
@import "./pages/_error.css";
@source "../css";
@source "../js";
@source "../../lib/chesstrainer_web";
/* Required for Tailwind to automatically pick up changes in colocated CSS files in dev */
@source "../../_build/dev/phoenix-colocated/chesstrainer/*/";
/* A Tailwind plugin that makes "hero-#{ICON}" classes available.
The heroicons installation itself is managed by your mix.exs */
@plugin "../vendor/heroicons";
/* daisyUI Tailwind Plugin. You can update this file by fetching the latest version with:
curl -sLO https://github.com/saadeghi/daisyui/releases/latest/download/daisyui.js
Make sure to look at the daisyUI changelog: https://daisyui.com/docs/changelog/ */
@plugin "../vendor/daisyui" {
themes: false;
.rating-note { display: flex; align-items: center; gap: 11px; color: var(--color-muted); font-size: 11px; line-height: 1.3; }
.rating-note strong { display: block; color: var(--color-body); font-size: 12px; }
.avatar-stack { display: flex; }
.avatar-stack i { width: 29px; height: 29px; display: grid; place-items: center; margin-left: -7px; border: 2px solid var(--color-canvas); border-radius: 50%; background: var(--color-mint-chip); color: var(--color-body); font-style: normal; }
.avatar-stack i:first-child { margin-left: 0; background: var(--color-coral-control); color: #fff; }
.avatar-stack i:last-child { background: var(--color-deep); color: var(--color-on-deep); }
.puzzle-section { width: min(1180px, calc(100% - 48px)); margin: 0 auto; padding: 110px 0 125px; }
.puzzle-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; }
.puzzle-coming-soon { min-height: 285px; display: grid; place-content: center; justify-items: center; gap: 10px; padding: 46px 28px; text-align: center; border: 1px dashed var(--color-hairline); border-radius: 12px; background: var(--color-canvas-raised); }
.puzzle-coming-soon .eyebrow { margin-bottom: 6px; }
.puzzle-coming-soon strong { font-family: 'DM Serif Display', serif; font-size: 30px; font-weight: 400; }
.puzzle-coming-soon p { max-width: 420px; margin: 0; color: var(--color-muted); font-size: 14px; line-height: 1.7; }
.puzzle-card { display: block; position: relative; min-height: 285px; padding: 25px; text-align: left; text-decoration: none; color: inherit; cursor: pointer; border: 1px solid var(--color-hairline); border-radius: 12px; background: rgba(255,255,255,.28); overflow: hidden; transition: transform .25s, background .25s, box-shadow .25s; }
.puzzle-card:hover, .puzzle-card.active { transform: translateY(-5px); background: var(--color-canvas-raised); box-shadow: 0 18px 36px rgba(23,53,45,.08); }
.puzzle-card.active { border-color: var(--color-success-text); }
.card-number { color: var(--color-muted); font-size: 10px; font-weight: 700; letter-spacing: .12em; }
.mini-piece { display: block; margin: 27px 0 22px; font-family: Georgia, serif; color: var(--color-body); font-size: 57px; line-height: 1; }
.difficulty { display: block; margin-bottom: 8px; color: var(--color-coral-text); font-size: 9px; text-transform: uppercase; font-weight: 700; letter-spacing: .12em; }
.puzzle-card strong { display: block; font-family: 'DM Serif Display', serif; font-size: 24px; font-weight: 400; }
.puzzle-card small { color: var(--color-muted); font-size: 11px; }
.card-arrow { position: absolute; right: 22px; bottom: 23px; display: grid; place-items: center; width: 36px; height: 36px; border: 1px solid var(--color-hairline); border-radius: 50%; transition: background .2s, color .2s; }
.puzzle-card:hover .card-arrow, .puzzle-card.active .card-arrow { background: var(--color-coral-control); color: white; border-color: var(--color-coral-control); }
.progress-banner { width: min(1180px, calc(100% - 48px)); margin: 0 auto 60px; padding: 70px 76px; display: flex; justify-content: space-between; align-items: end; border-radius: 16px; color: white; background: var(--color-coral-control); }
.progress-banner .section-kicker { color: var(--color-on-accent-muted); }
/* Dark mode needs a few tuned surfaces: tints and shadows are meaningless when
the canvas flips, and they are not worth a role token each. */
html[data-theme="dark"] .puzzle-card { background: rgba(233, 239, 233, .045); }
html[data-theme="dark"] .puzzle-card:hover,
html[data-theme="dark"] .puzzle-card.active { box-shadow: 0 18px 36px rgba(0, 0, 0, .35); }
html[data-theme="dark"] .board-shell { box-shadow: 0 26px 65px rgba(0, 0, 0, .55); }
html[data-theme="dark"] .primary-button { box-shadow: 0 10px 28px rgba(0, 0, 0, .35); }
html[data-theme="dark"] .learning-strip { box-shadow: inset 0 1px 0 var(--color-hairline); }
@media (max-width: 650px) {
.puzzle-section { width: calc(100% - 36px); padding: 80px 0; }
.puzzle-grid { grid-template-columns: 1fr; }
.puzzle-coming-soon { min-height: 255px; padding: 38px 22px; }
.puzzle-card { min-height: 255px; }
.progress-banner { width: calc(100% - 36px); padding: 48px 28px; flex-direction: column; align-items: flex-start; gap: 34px; }
}
/* daisyUI theme plugin. You can update this file by fetching the latest version with:
curl -sLO https://github.com/saadeghi/daisyui/releases/latest/download/daisyui-theme.js
We ship with two themes, a light one inspired on Phoenix colors and a dark one inspired
on Elixir colors. Build your own at: https://daisyui.com/theme-generator/ */
@plugin "../vendor/daisyui-theme" {
name: "dark";
default: false;
prefersdark: true;
color-scheme: "dark";
--color-base-100: oklch(30.33% 0.016 252.42);
--color-base-200: oklch(25.26% 0.014 253.1);
--color-base-300: oklch(20.15% 0.012 254.09);
--color-base-content: oklch(97.807% 0.029 256.847);
--color-primary: oklch(58% 0.233 277.117);
--color-primary-content: oklch(96% 0.018 272.314);
--color-secondary: oklch(58% 0.233 277.117);
--color-secondary-content: oklch(96% 0.018 272.314);
--color-accent: oklch(60% 0.25 292.717);
--color-accent-content: oklch(96% 0.016 293.756);
--color-neutral: oklch(37% 0.044 257.287);
--color-neutral-content: oklch(98% 0.003 247.858);
--color-info: oklch(58% 0.158 241.966);
--color-info-content: oklch(97% 0.013 236.62);
--color-success: oklch(60% 0.118 184.704);
--color-success-content: oklch(98% 0.014 180.72);
--color-warning: oklch(66% 0.179 58.318);
--color-warning-content: oklch(98% 0.022 95.277);
--color-error: oklch(58% 0.253 17.585);
--color-error-content: oklch(96% 0.015 12.422);
--radius-selector: 0.25rem;
--radius-field: 0.25rem;
--radius-box: 0.5rem;
--size-selector: 0.21875rem;
--size-field: 0.21875rem;
--border: 1.5px;
--depth: 1;
--noise: 0;
}
@plugin "../vendor/daisyui-theme" {
name: "light";
default: true;
prefersdark: false;
color-scheme: "light";
--color-base-100: oklch(98% 0 0);
--color-base-200: oklch(96% 0.001 286.375);
--color-base-300: oklch(92% 0.004 286.32);
--color-base-content: oklch(21% 0.006 285.885);
--color-primary: oklch(70% 0.213 47.604);
--color-primary-content: oklch(98% 0.016 73.684);
--color-secondary: oklch(55% 0.027 264.364);
--color-secondary-content: oklch(98% 0.002 247.839);
--color-accent: oklch(0% 0 0);
--color-accent-content: oklch(100% 0 0);
--color-neutral: oklch(44% 0.017 285.786);
--color-neutral-content: oklch(98% 0 0);
--color-info: oklch(62% 0.214 259.815);
--color-info-content: oklch(97% 0.014 254.604);
--color-success: oklch(70% 0.14 182.503);
--color-success-content: oklch(98% 0.014 180.72);
--color-warning: oklch(66% 0.179 58.318);
--color-warning-content: oklch(98% 0.022 95.277);
--color-error: oklch(58% 0.253 17.585);
--color-error-content: oklch(96% 0.015 12.422);
--radius-selector: 0.25rem;
--radius-field: 0.25rem;
--radius-box: 0.5rem;
--size-selector: 0.21875rem;
--size-field: 0.21875rem;
--border: 1.5px;
--depth: 1;
--noise: 0;
}
/* Add variants based on LiveView classes */
@custom-variant phx-click-loading (.phx-click-loading&, .phx-click-loading &);
@custom-variant phx-submit-loading (.phx-submit-loading&, .phx-submit-loading &);
@custom-variant phx-change-loading (.phx-change-loading&, .phx-change-loading &);
/* Use the data attribute for dark mode */
@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));
/* Make LiveView wrapper divs transparent for layout */
[data-phx-session],
[data-phx-teleported-src] {
display: contents;
}
/* This file is for your main application CSS */
+37
View File
@@ -0,0 +1,37 @@
:root {
color-scheme: light;
}
@layer base {
html { scroll-behavior: smooth; }
body {
min-width: 320px;
min-height: 100vh;
min-height: 100dvh;
display: flex;
flex-direction: column;
background: var(--color-canvas);
color: var(--color-body);
font-family: 'DM Sans', sans-serif;
}
button, a { -webkit-tap-highlight-color: transparent; }
button { cursor: pointer; }
/* A consistent focus ring for links, buttons and native controls. Components
that provide their own ring (form inputs) override this through utilities. */
:focus-visible { outline: 2px solid var(--color-coral-text); outline-offset: 2px; }
}
main { overflow: hidden; flex: 1 0 auto; }
/* LiveView */
@custom-variant phx-click-loading (.phx-click-loading&, .phx-click-loading &);
@custom-variant phx-submit-loading (.phx-submit-loading&, .phx-submit-loading &);
@custom-variant phx-change-loading (.phx-change-loading&, .phx-change-loading &);
@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));
/* Make LiveView wrapper divs transparent for layout */
[data-phx-session],
[data-phx-teleported-src] {
display: contents;
}
+107
View File
@@ -0,0 +1,107 @@
@theme static {
/* Roles — light mode reads from the palette. */
--color-canvas: var(--paper);
--color-canvas-raised: var(--cream);
--color-body: var(--ink);
--color-muted: var(--ink-soft);
--color-hairline: var(--line);
--color-deep: var(--ink);
--color-on-deep: var(--paper);
--color-coral: var(--coral);
--color-coral-control: var(--coral);
--color-coral-control-hover: var(--coral-dark);
--color-coral-text: #b8432c;
--color-success-text: #3f6d5a;
--color-warning-text: #8a5a00;
--color-primary-text: #b8432c;
--color-error-text: #b8432c;
--color-mint-chip: var(--mint);
--color-on-accent-muted: #5f2c23;
/* Content colours — identical in every colour mode. */
--color-board-light: #e9e1cc;
--color-board-dark: #81a996;
--color-piece-light: #fffdf5;
--color-piece-outline: #17352d;
--color-on-deep-muted: #c8d6d1;
--color-on-deep-faint: #a9beb6;
/* Promotion picker. */
--color-promotion-surface: #ffffff;
--color-promotion-tile: #fafafa;
--color-promotion-tile-hover: #fff1ec;
--color-promotion-selected: var(--coral);
/* Phoenix semantic tokens, retuned to the brand. Utilities such as
`bg-base-200` and `text-base-content` resolve through these. */
--color-base-100: #fffcf4;
--color-base-200: #f4f0e6;
--color-base-300: #e7e1d3;
--color-base-content: #17352d;
--color-primary: #c74c33;
--color-primary-content: #ffffff;
--color-secondary: #17352d;
--color-secondary-content: #f4f0e6;
--color-accent: #3f6d5a;
--color-accent-content: #ffffff;
--color-neutral: #587068;
--color-neutral-content: #f4f0e6;
/* Toasts use the brand palette rather than the stock blue/red: info is the
deep ink green, error is the coral used by primary actions. Both pass AA
against their content colour. */
--color-info: #17352d;
--color-info-content: #fffcf4;
--color-success: oklch(70% 0.14 182.503);
--color-success-content: oklch(98% 0.014 180.72);
--color-warning: oklch(66% 0.179 58.318);
--color-warning-content: oklch(98% 0.022 95.277);
--color-error: #c74c33;
--color-error-content: #ffffff;
}
html[data-theme="dark"] {
color-scheme: dark;
--color-canvas: #0f1714;
--color-canvas-raised: #1b2822;
--color-body: #e9efe9;
--color-muted: #9ab0a5;
--color-hairline: rgba(233, 239, 233, 0.14);
--color-deep: #1d3c33;
--color-on-deep: #f4f0e6;
--color-coral: #f2816b;
--color-coral-control: #c74c33;
--color-coral-control-hover: #b8432c;
--color-coral-text: #ff9c85;
--color-success-text: #8fd3b5;
--color-warning-text: #f0b35a;
--color-primary-text: #f2816b;
--color-error-text: #f2816b;
--color-mint-chip: #24403a;
--color-on-accent-muted: rgba(255, 255, 255, 0.97);
--color-promotion-surface: #1b2822;
--color-promotion-tile: #233029;
--color-promotion-tile-hover: #2c3d35;
--color-promotion-selected: #ff9c85;
--color-base-100: #1b2822;
--color-base-200: #141f1a;
--color-base-300: #0f1714;
--color-base-content: #e9efe9;
--color-primary: #c74c33;
--color-primary-content: #ffffff;
--color-secondary: #1d3c33;
--color-secondary-content: #f4f0e6;
--color-accent: #8fd3b5;
--color-accent-content: #0f1714;
--color-neutral: #2b3a33;
--color-neutral-content: #e9efe9;
--color-info: #24403a;
--color-info-content: #e9efe9;
--color-success: oklch(72% 0.13 165);
--color-success-content: oklch(15% 0.02 165);
--color-warning: oklch(78% 0.15 75);
--color-warning-content: oklch(20% 0.03 75);
--color-error: #c74c33;
--color-error-content: #ffffff;
}
+49
View File
@@ -0,0 +1,49 @@
@font-face {
font-family: "DM Sans";
font-style: normal;
font-weight: 100 1000;
font-display: swap;
src: url("/fonts/dm-sans-variable.woff2") format("woff2");
}
@font-face {
font-family: "DM Sans";
font-style: italic;
font-weight: 400;
font-display: swap;
src: url("/fonts/dm-sans-italic.woff2") format("woff2");
}
@font-face {
font-family: "DM Serif Display";
font-style: normal;
font-weight: 400;
font-display: swap;
src: url("/fonts/dm-serif-display.woff2") format("woff2");
}
@font-face {
font-family: "DM Serif Display";
font-style: italic;
font-weight: 400;
font-display: swap;
src: url("/fonts/dm-serif-display-italic.woff2") format("woff2");
}
h1, h2 { font-family: 'DM Serif Display', serif; font-weight: 400; letter-spacing: -.035em; }
h1 { max-width: 590px; font-size: clamp(56px, 6vw, 87px); line-height: .93; }
h1 em { color: var(--color-coral); font-weight: 400; }
.settings-header {
font-size: 3rem;
}
.settings-subtitle {
font-size: 1rem;;
color: var(--color-muted);
margin-top: 0.5rem;
}
@media (max-width: 650px) {
h1 { font-size: clamp(51px, 15vw, 68px); }
}
+55
View File
@@ -0,0 +1,55 @@
/* Hero Chessboard */
.board-shell { position: relative; z-index: 2; width: min(458px, 85vw); padding: 18px; border-radius: 12px; background: var(--color-canvas-raised); box-shadow: 0 26px 65px rgba(23, 53, 45, .25); transform: rotate(1.5deg); }
.board-topline, .board-caption { display: flex; align-items: center; justify-content: space-between; }
.board-topline { padding: 1px 1px 13px; }
.board-stage { position: relative; min-height: 580px; display: grid; place-items: center; }
.chessboard { aspect-ratio: 1; display: grid; grid-template-columns: repeat(8, 1fr); overflow: hidden; border-radius: 4px; box-shadow: inset 0 0 0 1px rgba(0,0,0,.05); }
.player { display: flex; align-items: center; gap: 9px; }
.player-piece { display: grid; place-items: center; width: 31px; height: 31px; background: var(--color-deep); border-radius: 50%; color: var(--color-on-deep); font-size: 20px; }
.player span:last-child { display: flex; flex-direction: column; line-height: 1.05; }
.player small { color: var(--color-muted); font-size: 8px; text-transform: uppercase; letter-spacing: .1em; }
.player strong { font-size: 12px; }
.square { position: relative; display: grid; place-items: center; aspect-ratio: 1; border: 0; }
.square.light { background: var(--color-board-light); }
.square.dark { background: var(--color-board-dark); }
.piece { position: relative; z-index: 2; font-family: Georgia, serif; font-size: clamp(25px, 4vw, 42px); line-height: 1; transform: translateY(-1px); }
.white-piece { color: var(--color-piece-light); text-shadow: 0 2px 0 var(--color-piece-outline), 1px 0 0 var(--color-piece-outline), -1px 0 0 var(--color-piece-outline), 0 -1px 0 var(--color-piece-outline); }
.black-piece { color: var(--color-piece-outline); text-shadow: 0 1px 0 rgba(255,255,255,.25); }
.rank, .file { position: absolute; z-index: 3; color: rgba(23,53,45,.65); font-size: 7px; font-weight: 700; }
.rank { top: 3px; left: 4px; }
.file { right: 4px; bottom: 2px; }
.dark .rank, .dark .file { color: rgba(255,255,255,.65); }
.board-caption { padding: 14px 2px 0; }
.board-caption div { display: flex; flex-direction: column; }
.board-caption span { color: var(--color-muted); font-size: 9px; text-transform: uppercase; letter-spacing: .1em; }
.board-caption strong { font-size: 13px; }
.board-caption button { color: var(--color-coral-text); font-size: 11px; font-weight: 700; }
.board-themes { color: var(--color-coral-text); font-size: 8px; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; }
@media (max-width: 900px) {
.board-stage { min-height: 620px; }
}
@media (max-width: 650px) {
.board-stage { min-height: 500px; }
.board-shell { width: min(390px, 92vw); padding: 12px; }
.piece { font-size: clamp(24px, 9vw, 38px); }
}
/* Admin Chessboard */
.bg-boardwhite { background-color: #f2f5f3; /* light square */ }
.bg-boardblack { background-color: #71828f; /* dark square */ }
/* Play board */
#endgame-board { position: relative; }
/* Chessground's stock stylesheet shifts the file labels 24px right of the
board, assuming a gutter we don't have, so they land on square boundaries
instead of under each file. Place the row on the board and right-justify
each label within its square; the row's width already matches the board
because the container is sized to whole squares. */
#endgame-board coords.files { left: 0; text-align: right; }
/* Chessground's wrapper has no intrinsic height; let it fill the sized
aspect-ratio container so the board scales with the viewport. */
#endgame-board .cg-wrap { width: 100%; height: 100%; }
+9
View File
@@ -0,0 +1,9 @@
.primary-button { padding: 16px 23px; background: var(--color-coral-control); color: #fff; box-shadow: 0 10px 28px rgba(217, 93, 72, .21); }
.primary-button:hover { background: var(--color-coral-control-hover); }
.light-button { padding: 15px 22px; background: var(--color-canvas-raised); color: var(--color-body); white-space: nowrap; }
.menu-button { display: none; }
@media (max-width: 650px) {
.menu-button { display: flex; width: 38px; height: 38px; flex-direction: column; align-items: center; justify-content: center; gap: 6px; }
.menu-button span { width: 19px; height: 1.5px; background: var(--color-body); }
}
+9
View File
@@ -0,0 +1,9 @@
.eyebrow { display: flex; align-items: center; gap: 9px; margin-bottom: 27px; color: var(--color-coral-text); text-transform: uppercase; letter-spacing: .13em; font-size: 12px; font-weight: 700; }
.eyebrow svg { width: 20px; height: 20px; }
/* Icon-only external links, e.g. the Discord invite in the navbar and footer.
Colour is inherited so the glyph matches the surrounding link row. */
.discord-link { display: inline-flex; align-items: center; color: inherit; transition: opacity .2s; }
.discord-link:hover { opacity: .55; }
.discord-link:focus-visible { outline: 2px solid var(--color-coral-control); outline-offset: 3px; border-radius: 4px; }
.discord-link svg { width: 20px; height: 20px; }
+23
View File
@@ -0,0 +1,23 @@
.learning-strip {
padding: 27px max(24px, calc((100% - 1180px)/2));
display: grid; grid-template-columns: 1.5fr repeat(3, 1fr); align-items: center; background: var(--color-deep); color: var(--color-on-deep);
}
.learning-quote { margin: 0; max-width: 300px; }
.learning-quote blockquote { margin: 0; color: var(--color-on-deep); font-family: 'DM Serif Display', serif; font-size: 19px; line-height: 1.25; }
.learning-quote figcaption { margin-top: 10px; color: var(--color-on-deep-faint); font-size: 10px; text-transform: uppercase; letter-spacing: .09em; }
.stat { padding-left: 34px; border-left: 1px solid rgba(255,255,255,.17); }
.stat strong { display: block; font-family: 'DM Serif Display', serif; font-size: 28px; font-weight: 400; }
.stat span { color: var(--color-on-deep-faint); font-size: 10px; text-transform: uppercase; letter-spacing: .09em; }
@media (max-width: 900px) {
.learning-strip { grid-template-columns: 1fr repeat(3, .7fr); }
}
@media (max-width: 650px) {
.learning-strip { padding: 38px 24px; grid-template-columns: 1fr 1fr; gap: 30px 10px; }
.learning-quote { grid-column: 1 / -1; }
.stat { padding-left: 18px; }
.stat:last-child { grid-column: 1 / -1; }
}
+37
View File
@@ -0,0 +1,37 @@
.mailing-list {
width: min(1180px, calc(100% - 48px));
margin: 0 auto 110px;
padding: 56px 60px;
display: flex;
align-items: center;
justify-content: space-between;
gap: 48px;
border-radius: 16px;
background: var(--color-deep);
color: var(--color-on-deep);
}
.mailing-list-copy { max-width: 480px; }
.mailing-list-copy .section-kicker { color: var(--color-on-deep-muted); }
.mailing-list-copy h2 { font-size: clamp(32px, 3.4vw, 46px); line-height: 1; }
.mailing-list-copy p { margin-top: 16px; color: var(--color-on-deep-muted); font-size: 14px; line-height: 1.65; }
.mailing-list-form { width: min(420px, 100%); flex-shrink: 0; }
.mailing-list-honeypot { position: absolute; left: -10000px; width: 1px; height: 1px; overflow: hidden; }
.mailing-list-form label { display: block; margin-bottom: 8px; color: var(--color-on-deep-faint); font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: .11em; }
.mailing-list-row { display: flex; gap: 10px; }
.mailing-list-row input { flex: 1; min-width: 0; padding: 15px 17px; border: 1px solid rgba(255, 255, 255, .22); border-radius: 8px; background: rgba(255, 255, 255, .1); color: var(--color-on-deep); font-size: 14px; }
.mailing-list-row input::placeholder { color: var(--color-on-deep-faint); }
.mailing-list-row input:focus { border-color: transparent; outline: 2px solid var(--color-coral); outline-offset: 2px; }
.mailing-list-row .primary-button { white-space: nowrap; }
@media (max-width: 900px) {
.mailing-list { flex-direction: column; align-items: flex-start; gap: 30px; }
.mailing-list-form { width: 100%; }
}
@media (max-width: 650px) {
.mailing-list { width: calc(100% - 36px); margin-bottom: 80px; padding: 40px 24px; }
.mailing-list-row { flex-direction: column; }
.mailing-list-row .primary-button { justify-content: center; }
}
@@ -13,19 +13,23 @@
display: flex;
flex-direction: column;
gap: 6px;
background: white;
background: var(--color-promotion-surface);
padding: 10px;
border-radius: 14px;
box-shadow: 0 8px 32px rgba(0, 0, 0, 0.35);
}
html[data-theme="dark"] .promotion-overlay {
background: rgba(0, 0, 0, 0.68);
}
.promotion-piece {
width: 80px;
height: 80px;
cursor: pointer;
border: 2px solid transparent;
border-radius: 8px;
background-color: #fafafa;
background-color: var(--color-promotion-tile);
background-size: 80% 80%;
background-position: center;
background-repeat: no-repeat;
@@ -33,8 +37,8 @@
}
.promotion-piece:hover {
background-color: #eff6ff;
border-color: #3b82f6;
background-color: var(--color-promotion-tile-hover);
border-color: var(--color-promotion-selected);
transform: scale(1.08);
}
+12
View File
@@ -0,0 +1,12 @@
:root {
/* Raw brand palette. */
--ink: #17352d;
--ink-soft: #587068;
--paper: #f4f0e6;
--cream: #fffcf4;
--mint: #b9d7c9;
--mint-deep: #8bb9a8;
--coral: #ef755d;
--coral-dark: #d95d48;
--line: rgba(23, 53, 45, 0.15);
}
+18
View File
@@ -0,0 +1,18 @@
.site-footer {
width: min(1180px, calc(100% - 48px)); margin: 0 auto; padding: 44px 0;
display: flex; align-items: center; justify-content: space-between; gap: 30px;
border-top: 1px solid var(--color-hairline);
}
.footer-brand { display: flex; flex-direction: column; gap: 12px; }
.footer-brand p { color: var(--color-muted); font-size: 13px; }
.footer-links { display: flex; gap: 26px; font-size: 14px; font-weight: 600; }
.footer-links a { transition: opacity .2s; }
.footer-links a:hover { opacity: .55; }
.site-footer > small { color: var(--color-muted); font-size: 11px; }
@media (max-width: 650px) {
.site-footer { width: calc(100% - 36px); flex-direction: column; align-items: flex-start; gap: 24px; }
.footer-links { flex-wrap: wrap; gap: 16px 22px; }
}
+28
View File
@@ -0,0 +1,28 @@
.hero {
width: min(1180px, calc(100% - 48px)); min-height: 650px; margin: 0 auto;
display: grid; grid-template-columns: .91fr 1.09fr; align-items: center; gap: 60px;
}
.hero-copy { position: relative; z-index: 2; padding: 74px 0 92px; }
.hero-copy > p { max-width: 480px; margin-top: 29px; color: var(--color-muted); font-size: 17px; line-height: 1.65; }
.hero-actions { display: flex; align-items: center; gap: 25px; margin-top: 35px; }
.coral-orbit, .mint-orbit { position: absolute; border-radius: 50%; }
.coral-orbit { width: 460px; height: 460px; right: -34px; top: 46px; background: var(--color-coral); }
.mint-orbit { width: 230px; height: 230px; left: 14px; bottom: 28px; background: var(--color-mint-chip); }
@media (max-width: 900px) {
.hero { grid-template-columns: 1fr; gap: 0; }
.hero-copy { padding-bottom: 30px; }
.hero-copy > p { max-width: 560px; }
.coral-orbit { right: 6%; }
.mint-orbit { left: 10%; }
}
@media (max-width: 650px) {
.hero { width: calc(100% - 36px); }
.hero-copy { padding: 65px 0 24px; }
.hero-copy > p { font-size: 15px; }
.coral-orbit { width: 340px; height: 340px; right: -28%; top: 65px; }
.mint-orbit { width: 170px; height: 170px; left: -8%; }
}
+55
View File
@@ -0,0 +1,55 @@
.nav-wrap {
width: min(1180px, calc(100% - 48px));
height: 92px;
margin: 0 auto;
display: flex;
align-items: center;
justify-content: space-between;
border-bottom: 1px solid var(--color-hairline);
}
.nav-right { display: flex; align-items: center; gap: 22px; }
.nav-links { display: flex; align-items: center; gap: 34px; font-size: 14px; font-weight: 600; }
.nav-links a { transition: opacity .2s; }
.nav-links a:hover { opacity: .55; }
.nav-links a.nav-cta:hover { opacity: 1; }
/* Utilities (colour mode, Discord) sit in the bar on desktop and in the
collapsible menu on small screens. */
.nav-menu-tools { display: none; }
.nav-user-menu { position: relative; }
.nav-user-menu summary { display: flex; align-items: center; gap: 6px; list-style: none; cursor: pointer; color: var(--color-muted); font-weight: 500; }
.nav-user-menu summary::-webkit-details-marker { display: none; }
.nav-user-menu summary::after { content: "▾"; font-size: 10px; }
.nav-user-menu-panel { position: absolute; right: 0; top: calc(100% + 14px); z-index: 20; display: grid; gap: 12px; min-width: 170px; padding: 16px; border-radius: 10px; background: var(--color-canvas-raised); box-shadow: 0 18px 40px rgba(23,53,45,.15); }
html[data-theme="dark"] .nav-user-menu-panel { box-shadow: 0 18px 40px rgba(0, 0, 0, .45); }
.nav-cta, .primary-button, .light-button {
display: inline-flex; align-items: center; justify-content: center; gap: 13px;
border-radius: 999px; font-weight: 600; transition: transform .2s, background .2s;
}
.nav-cta { padding: 12px 19px; color: var(--color-on-deep); background: var(--color-deep); }
.nav-cta svg, .primary-button svg, .light-button svg, .card-arrow svg { width: 18px; height: 18px; }
.nav-cta:hover, .primary-button:hover, .light-button:hover { transform: translateY(-2px); }
.brand { display: flex; align-items: center; gap: 10px; font-size: 16px; font-weight: 700; letter-spacing: .18em; }
.brand-mark { display: grid; place-items: center; width: 35px; height: 35px; border-radius: 50%; background: var(--color-deep); color: var(--color-on-deep); font-size: 21px; letter-spacing: 0; }
@media (max-width: 900px) {
.nav-links { gap: 20px; }
.nav-right { gap: 16px; }
}
@media (max-width: 650px) {
.nav-wrap { width: calc(100% - 36px); height: 74px; position: relative; z-index: 10; }
.nav-right { gap: 12px; }
.nav-links.open { display: flex; }
.nav-cta { width: 100%; }
.nav-links { display: none; position: absolute; top: 65px; left: 0; right: 0; padding: 24px; flex-direction: column; align-items: stretch; gap: 22px; border-radius: 10px; background: var(--color-canvas-raised); box-shadow: 0 18px 40px rgba(23,53,45,.15); }
.nav-menu-tools { display: flex; align-items: center; justify-content: space-between; gap: 18px; width: 100%; }
/* The menu owns these on small screens; keep them in the bar only when no
menu is rendered (prelaunch with no links). */
.nav-wrap:has(#nav-links) .nav-right > [role="radiogroup"],
.nav-wrap:has(#nav-links) .nav-right > .discord-link { display: none; }
.nav-user-menu-panel { position: static; min-width: 0; padding: 12px 0 0; background: transparent; box-shadow: none; }
html[data-theme="dark"] .nav-links { box-shadow: 0 18px 40px rgba(0, 0, 0, .45); }
}
+12
View File
@@ -0,0 +1,12 @@
.section-heading { display: grid; grid-template-columns: 1fr .65fr; align-items: end; margin-bottom: 46px; }
.section-kicker { display: block; margin-bottom: 14px; color: var(--color-coral-text); text-transform: uppercase; letter-spacing: .13em; font-size: 11px; font-weight: 700; }
.section-heading h2, .progress-banner h2 { font-size: clamp(43px, 5vw, 65px); line-height: .96; }
.section-heading > p { max-width: 390px; color: var(--color-muted); font-size: 14px; line-height: 1.7; }
@media (max-width: 900px) {
.section-heading { grid-template-columns: 1fr .8fr; }
}
@media (max-width: 650px) {
.section-heading { grid-template-columns: 1fr; gap: 25px; }
}
+60
View File
@@ -0,0 +1,60 @@
.error-page {
width: min(760px, calc(100% - 48px));
margin: 0 auto;
padding: 100px 0 130px;
text-align: center;
}
.error-code {
display: inline-flex;
align-items: center;
justify-content: center;
min-width: 68px;
padding: 7px 16px;
border: 1px solid var(--color-hairline);
border-radius: 999px;
color: var(--color-coral-text);
font-size: 12px;
font-weight: 700;
letter-spacing: .16em;
}
.error-page h1 {
max-width: 640px;
margin: 28px auto 0;
font-size: clamp(40px, 5.5vw, 60px);
line-height: 1.02;
}
.error-page p {
max-width: 48ch;
margin: 18px auto 0;
color: var(--color-muted);
font-size: 16px;
line-height: 1.7;
}
.error-page .error-hint {
margin-top: 10px;
font-size: 13px;
}
.error-actions {
display: flex;
flex-wrap: wrap;
justify-content: center;
align-items: center;
gap: 12px;
margin-top: 34px;
}
@media (max-width: 650px) {
.error-page {
width: calc(100% - 36px);
padding: 64px 0 90px;
}
.error-page h1 {
font-size: clamp(34px, 10vw, 44px);
}
}
+72
View File
@@ -0,0 +1,72 @@
.legal {
width: min(760px, calc(100% - 48px));
margin: 0 auto;
padding: 84px 0 120px;
}
.legal h1 {
max-width: none;
font-size: clamp(42px, 5vw, 62px);
line-height: 1.02;
}
.legal-meta {
margin-top: 14px;
color: var(--color-muted);
font-size: 13px;
}
.legal h2 {
margin: 42px 0 12px;
font-size: 26px;
line-height: 1.15;
}
.legal p,
.legal li {
color: var(--color-muted);
font-size: 15px;
line-height: 1.75;
}
.legal p + p {
margin-top: 12px;
}
.legal ul {
display: grid;
gap: 8px;
margin: 12px 0 0 20px;
list-style: disc;
}
.legal strong {
color: var(--color-body);
font-weight: 600;
}
.legal a {
color: var(--color-coral-text);
text-decoration: underline;
text-underline-offset: 2px;
}
.legal a:hover {
opacity: 0.75;
}
@media (max-width: 650px) {
.legal {
width: calc(100% - 36px);
padding: 56px 0 84px;
}
.legal h1 {
font-size: clamp(34px, 11vw, 44px);
}
.legal h2 {
margin-top: 34px;
font-size: 23px;
}
}
+105
View File
@@ -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();
}
+10 -2
View File
@@ -19,18 +19,24 @@
// Include phoenix_html to handle method=PUT/DELETE in forms and buttons.
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";
import { hooks as colocatedHooks } from "phoenix-colocated/chesstrainer";
import topbar from "../vendor/topbar";
import { ChessBoard } from "./hooks/chessBoard";
import { CopyFen } from "./hooks/copyFen"
import { CopyFen } from "./hooks/copyFen";
import { SessionClock } from "./hooks/sessionClock";
let Hooks = {
...colocatedHooks,
ChessBoard,
CopyFen
CopyFen,
SessionClock,
};
const csrfToken = document.querySelector("meta[name='csrf-token']").getAttribute("content");
@@ -54,6 +60,8 @@ liveSocket.connect();
// >> liveSocket.disableLatencySim()
window.liveSocket = liveSocket;
initAnalytics();
// The lines below enable quality of life phoenix_live_reload
// development features:
//
+77 -4
View File
@@ -22,7 +22,20 @@ export const ChessBoard = {
this.applyBestLineMove({ from, to, promotion, san });
});
this.handleEvent("apply_move", ({ from, to, promotion }) => {
if (this.reviewing) return;
this.executeMove(from, to, promotion);
});
this.handleKeyDown = (event) => {
if (this.pendingPromotion) {
if (event.key === "Escape") {
event.preventDefault();
this.cancelPromotion();
}
return;
}
if (!this.reviewing) return;
if (event.key === "ArrowLeft") {
@@ -31,6 +44,12 @@ export const ChessBoard = {
} else if (event.key === "ArrowRight") {
event.preventDefault();
this.pushEvent("review_next", {});
} else if (event.key === "Home") {
event.preventDefault();
this.pushEvent("review_start", {});
} else if (event.key === "End") {
event.preventDefault();
this.pushEvent("review_end", {});
}
};
@@ -185,9 +204,13 @@ export const ChessBoard = {
showPromotionDialog(orig, dest) {
this.pendingPromotion = { orig, dest };
this.previousFocus = document.activeElement;
const color = this.chess.turn() === "w" ? "white" : "black";
const overlay = document.createElement("div");
overlay.className = "promotion-overlay";
overlay.setAttribute("role", "dialog");
overlay.setAttribute("aria-modal", "true");
overlay.setAttribute("aria-label", "Choose a promotion piece");
const picker = document.createElement("div");
picker.className = "promotion-picker";
const pieces = [
@@ -198,22 +221,64 @@ export const ChessBoard = {
];
pieces.forEach(({ type, code }) => {
const btn = document.createElement("button");
btn.type = "button";
btn.className = `promotion-piece ${type} ${color}`;
btn.setAttribute("aria-label", `Promote to ${type}`);
btn.addEventListener("click", () => this.completePromotion(code));
picker.appendChild(btn);
});
overlay.addEventListener("keydown", (event) => {
if (event.key === "Escape") {
event.preventDefault();
this.cancelPromotion();
return;
}
if (event.key !== "Tab") return;
const buttons = Array.from(picker.querySelectorAll("button"));
const first = buttons[0];
const last = buttons[buttons.length - 1];
if (event.shiftKey && document.activeElement === first) {
event.preventDefault();
last.focus();
} else if (!event.shiftKey && document.activeElement === last) {
event.preventDefault();
first.focus();
}
});
overlay.appendChild(picker);
const boardContainer = this.el.closest(".shadow-inner");
boardContainer.style.position = "relative";
boardContainer.appendChild(overlay);
const container = this.el.parentElement;
container.style.position = "relative";
container.appendChild(overlay);
picker.querySelector("button")?.focus();
},
cancelPromotion() {
this.pendingPromotion = null;
const overlay = this.el.parentElement?.querySelector(".promotion-overlay");
if (overlay) overlay.remove();
this.restoreFocus();
},
restoreFocus() {
if (this.previousFocus instanceof HTMLElement) {
this.previousFocus.focus();
} else {
document.getElementById("move-input")?.focus();
}
this.previousFocus = null;
},
completePromotion(pieceType) {
const { orig, dest } = this.pendingPromotion;
this.pendingPromotion = null;
const picker = this.el.closest(".shadow-inner")?.querySelector(".promotion-overlay");
const picker = this.el.parentElement?.querySelector(".promotion-overlay");
if (picker) picker.remove();
this.executeMove(orig, dest, pieceType);
document.getElementById("move-input")?.focus();
},
executeMove(orig, dest, promotion) {
@@ -234,6 +299,7 @@ export const ChessBoard = {
san: move.san,
promotion: promotion || null,
draw: this.chess.isDraw(),
check: this.chess.isCheck(),
checkmate: this.chess.isCheckmate(),
};
@@ -252,8 +318,14 @@ export const ChessBoard = {
? { color: null, dests: new Map() }
: { color: nextTurnColor, dests: this.getValidDests() },
});
return true;
} else {
this.ground.set({ fen: this.chess.fen() });
this.pushEvent("move_input_error", {
message: "That move is not legal in this position.",
});
return false;
}
},
@@ -279,6 +351,7 @@ export const ChessBoard = {
fen: this.chess.fen(),
san: move.san,
draw: this.chess.isDraw(),
check: this.chess.isCheck(),
checkmate: this.chess.isCheckmate(),
});
},
+27
View File
@@ -0,0 +1,27 @@
// Ticks a session clock in mm:ss from its `data-started-at` (unix ms) so the
// timer advances without a server round-trip. The server renders the initial
// value, so a re-render stays in sync with the client.
export const SessionClock = {
mounted() {
this.tick();
this.timer = setInterval(() => this.tick(), 1000);
},
updated() {
this.tick();
},
destroyed() {
clearInterval(this.timer);
},
tick() {
const startedAt = parseInt(this.el.dataset.startedAt, 10);
if (!startedAt) return;
const total = Math.max(0, Math.floor((Date.now() - startedAt) / 1000));
const minutes = String(Math.floor(total / 60)).padStart(2, "0");
const seconds = String(total % 60).padStart(2, "0");
this.el.textContent = `${minutes}:${seconds}`;
},
};
+7
View File
@@ -0,0 +1,7 @@
// JavaScript for controller-rendered (non-LiveView) pages such as the landing
// page. Keep this small: no Phoenix Socket, LiveView, hooks, or topbar.
import "phoenix_html";
import "./nav";
import { initAnalytics } from "./analytics";
initAnalytics();
+103
View File
@@ -0,0 +1,103 @@
// Plain-DOM mobile navigation. It lives outside the LiveView hook system so it
// also runs on controller-rendered pages such as the landing page.
const WRAP = ".nav-wrap";
const TOGGLE = ".menu-button";
const LINKS = ".nav-links";
const USER_MENU = ".nav-user-menu";
const closeUserMenus = () => {
document.querySelectorAll(`${USER_MENU}[open]`).forEach((menu) => menu.removeAttribute("open"));
};
const setOpen = (open) => {
const wrap = document.querySelector(WRAP);
const links = wrap?.querySelector(LINKS);
const button = wrap?.querySelector(TOGGLE);
if (!links) return;
links.classList.toggle("open", open);
button?.setAttribute("aria-expanded", String(open));
};
document.addEventListener("click", (event) => {
const target = event.target instanceof Element ? event.target : null;
if (!target) return;
if (target.closest(TOGGLE)) {
const links = document.querySelector(LINKS);
setOpen(!links?.classList.contains("open"));
return;
}
if (target.closest(`${USER_MENU} a`)) {
closeUserMenus();
setOpen(false);
return;
}
if (!target.closest(USER_MENU)) {
closeUserMenus();
}
if (target.closest(`${LINKS} a`)) {
setOpen(false);
return;
}
if (!target.closest(WRAP)) {
setOpen(false);
}
});
document.addEventListener("keydown", (event) => {
if (event.key === "Escape") {
setOpen(false);
closeUserMenus();
}
});
// Flash toasts also render on controller pages (the landing page, after logging
// out, for example), where there is no LiveView to handle the component's
// phx-click. Dismiss them with plain DOM there; LiveView pages keep clearing
// the server-side flash through `lv:clear-flash`.
document.addEventListener("click", (event) => {
const target = event.target instanceof Element ? event.target : null;
const flash = target?.closest("[data-flash-dismiss]");
if (!flash) return;
if (window.liveSocket?.isConnected?.()) return;
flash.remove();
});
// Auto-dismiss real flash messages after a few seconds. Synthetic clicks reuse
// the manual dismiss path, so LiveView pages also clear the server-side flash.
// The connectivity notices (`client-error`/`server-error`) start hidden and are
// left alone: they should stay until the connection recovers.
const FLASH_TIMEOUT_MS = 5000;
const scheduledFlashes = new WeakSet();
const scheduleFlashDismiss = (flash) => {
if (scheduledFlashes.has(flash) || flash.hasAttribute("hidden")) return;
scheduledFlashes.add(flash);
setTimeout(() => flash.click(), FLASH_TIMEOUT_MS);
};
const scheduleFlashes = (root) => {
if (root.matches?.("[data-flash-dismiss]")) scheduleFlashDismiss(root);
root.querySelectorAll?.("[data-flash-dismiss]").forEach(scheduleFlashDismiss);
};
document.querySelectorAll("[data-flash-dismiss]").forEach(scheduleFlashDismiss);
// Flashes rendered later (LiveView updates, live navigation) arrive after the
// initial pass, so watch for them.
new MutationObserver((mutations) => {
for (const mutation of mutations) {
for (const node of mutation.addedNodes) {
if (node instanceof Element) scheduleFlashes(node);
}
}
}).observe(document.body, { childList: true, subtree: true });
-1214
View File
File diff suppressed because it is too large Load Diff
-9318
View File
File diff suppressed because it is too large Load Diff
+43 -1
View File
@@ -7,6 +7,22 @@
# General application configuration
import Config
# Public-facing branding. Change these values to rename the site without
# touching templates. The OTP app (`:chesstrainer`) and module namespaces are
# identity, not branding, and stay as they are.
config :chesstrainer, :branding,
name: "Inner Square Chess",
wordmark: "INNERSQUARE",
tagline: "Endgame Trainer",
support_email: "support@innersquare.app",
mail_from: "no-reply@mail.innersquare.app",
discord_invite: "https://discord.gg/Z2NfkG7thV"
# Prelaunch gating. Production sets these from PRELAUNCH and
# MAILING_LIST_ENABLED; dev and test use these defaults.
config :chesstrainer, :prelaunch, false
config :chesstrainer, :mailing_list_enabled, true
config :chesstrainer, :scopes,
user: [
default: true,
@@ -24,6 +40,16 @@ config :chesstrainer,
ecto_repos: [Chesstrainer.Repo],
generators: [timestamp_type: :utc_datetime]
# Password-login throttle. Failures are counted in fixed windows for each
# client address and each normalised login. The address bucket is deliberately
# wider so one account stays protected from distributed guessing while one
# address cannot spray many accounts.
config :chesstrainer, ChesstrainerWeb.LoginThrottle,
window_ms: :timer.minutes(15),
max_per_login: 5,
max_per_ip: 10,
confirmation_cooldown_ms: :timer.minutes(15)
# Glicko rating system.
#
# `system_constant` is the volatility constraint passed through to the Glicko
@@ -36,6 +62,22 @@ config :chesstrainer, :ratings,
window_days: 7,
rd_inflation_c: 10.0
# Puzzle selection. Difficulty is a weighted bias towards a target rating —
# `medium` targets the user's rating, `easy` 200 below it and `hard` 200 above
# it — and `spread` is how many rating points it takes for a puzzle's chance to
# fall off by a factor of e. `repeat_window_days` is how long an attempted
# puzzle stays out of the pool. Tweak `spread` to widen or narrow the served
# difficulty (e.g. 100 or 250).
config :chesstrainer, :puzzles,
spread: 150,
repeat_window_days: 30,
targets: [easy: -200, medium: 0, hard: 200]
# Public codes of the endgames pinned to the landing-page puzzle grid, in
# display order. When empty (or short) the grid is topped up with a date-seeded
# selection from the database, so it stays stable for a given day.
config :chesstrainer, :curated_endgame_codes, []
# Configure the endpoint
config :chesstrainer, ChesstrainerWeb.Endpoint,
url: [host: "localhost"],
@@ -66,7 +108,7 @@ config :esbuild,
version: "0.25.4",
chesstrainer: [
args:
~w(js/app.js --bundle --target=es2022 --outdir=../priv/static/assets/js --external:/fonts/* --external:/images/* --alias:@=.),
~w(js/app.js js/marketing.js --bundle --target=es2022 --outdir=../priv/static/assets/js --external:/fonts/* --external:/images/* --alias:@=.),
cd: Path.expand("../assets", __DIR__),
env: %{"NODE_PATH" => [Path.expand("../deps", __DIR__), Mix.Project.build_path()]}
]
+1 -1
View File
@@ -19,7 +19,7 @@ config :chesstrainer, Chesstrainer.Repo,
config :chesstrainer, ChesstrainerWeb.Endpoint,
# Binding to loopback ipv4 address prevents access from other machines.
# Change to `ip: {0, 0, 0, 0}` to allow access from other machines.
http: [ip: {127, 0, 0, 1}],
http: [ip: {0, 0, 0, 0}],
check_origin: false,
code_reloader: true,
debug_errors: true,
+10 -1
View File
@@ -15,11 +15,15 @@ config :chesstrainer, ChesstrainerWeb.Endpoint,
force_ssl: [
rewrite_on: [:x_forwarded_proto],
exclude: [
# paths: ["/health"],
paths: ["/health"],
hosts: ["localhost", "127.0.0.1"]
]
]
# Fail closed in production: the mailing list stays off until SES production
# access is granted and MAILING_LIST_ENABLED is set explicitly.
config :chesstrainer, :mailing_list_enabled, false
# Configure Swoosh API Client
config :swoosh, api_client: Swoosh.ApiClient.Req
@@ -29,5 +33,10 @@ config :swoosh, local: false
# Do not print debug messages in production
config :logger, level: :info
# Emit one JSON object per line in production so journald output can be
# filtered and shipped without parsing prose. Dev and test keep the readable
# default formatter configured in config.exs.
config :logger, :default_handler, formatter: {Chesstrainer.JSONLogFormatter, %{}}
# Runtime production configuration, including reading
# of environment variables, is done on config/runtime.exs.
+57 -6
View File
@@ -20,12 +20,42 @@ if System.get_env("PHX_SERVER") do
config :chesstrainer, ChesstrainerWeb.Endpoint, server: true
end
if prelaunch = System.get_env("PRELAUNCH") do
config :chesstrainer, :prelaunch, prelaunch in ~w(true 1)
end
if mailing_list_enabled = System.get_env("MAILING_LIST_ENABLED") do
config :chesstrainer, :mailing_list_enabled, mailing_list_enabled in ~w(true 1)
end
# Sender address override. The default lives in config/config.exs; this lets a
# deploy try a different From address (for example a new sending subdomain)
# without a rebuild.
if mail_from = System.get_env("MAIL_FROM") do
branding = Application.get_env(:chesstrainer, :branding, [])
config :chesstrainer, :branding, Keyword.put(branding, :mail_from, mail_from)
end
# SES configuration set stamped on every outgoing email. The set is what links
# a message to its SNS bounce and complaint notifications.
config :chesstrainer,
:ses_configuration_set,
System.get_env("SES_CONFIGURATION_SET", "my-first-configuration-set")
# Rewrite every recipient to one address while testing. Leave unset in normal
# operation; see `mix mail.check`.
config :chesstrainer, :mail_redirect_to, System.get_env("MAIL_REDIRECT_TO")
# Local Syzygy tablebases: set TABLEBASE_PATH to the directory holding the
# .rtbw/.rtbz files. When unset, the local backend stays disabled and lookups
# fall back to Lichess.
# fall back to Lichess. Tests are always pinned to the committed 3-piece
# fixtures by config/test.exs, so an exported TABLEBASE_PATH cannot make them
# depend on whatever tables the developer happens to have downloaded.
if config_env() != :test do
if tablebase_path = System.get_env("TABLEBASE_PATH") do
config :chesstrainer, :tablebase_path, tablebase_path
end
end
# Tablebase cache: size and the UTC time of the daily backup. Environment
# variables win over the defaults in config/config.exs so deployments can tune
@@ -81,6 +111,13 @@ config :chesstrainer, Chesstrainer.Cache,
max_size: cache_max_size,
backup_time: cache_backup_time
# Guest puzzle limit: free puzzles per UTC day for anonymous visitors. The
# visitor is identified by a keyed hash of their address held in memory only.
# Enable TRUST_FORWARDED_FOR only behind a proxy that sets the header.
config :chesstrainer, Chesstrainer.GuestLimits,
limit: String.to_integer(System.get_env("GUEST_PUZZLE_LIMIT", "5")),
trust_forwarded_for: System.get_env("TRUST_FORWARDED_FOR") in ~w(true 1)
config :chesstrainer, ChesstrainerWeb.Endpoint,
http: [port: String.to_integer(System.get_env("PORT", "4000"))]
@@ -94,6 +131,22 @@ if config_env() == :prod do
maybe_ipv6 = if System.get_env("ECTO_IPV6") in ~w(true 1), do: [:inet6], else: []
config :chesstrainer, Chesstrainer.Mailer,
adapter: Swoosh.Adapters.AmazonSES,
region:
System.get_env("SES_REGION") ||
raise("environment variable SES_REGION is missing"),
access_key:
System.get_env("SES_ACCESS_KEY_ID") ||
raise("environment variable SES_ACCESS_KEY_ID is missing"),
secret:
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,
@@ -121,11 +174,9 @@ if config_env() == :prod do
config :chesstrainer, ChesstrainerWeb.Endpoint,
url: [host: host, port: 443, scheme: "https"],
http: [
# Enable IPv6 and bind on all interfaces.
# Set it to {0, 0, 0, 0, 0, 0, 0, 1} for local network only access.
# See the documentation on https://bandit.hexdocs.pm/Bandit.html#t:options/0
# for details about using IPv6 vs IPv4 and loopback vs public addresses.
ip: {0, 0, 0, 0, 0, 0, 0, 0}
# The release runs behind Caddy, so bind to loopback and let the proxy
# handle public traffic.
ip: {127, 0, 0, 1}
],
secret_key_base: secret_key_base
+38
View File
@@ -0,0 +1,38 @@
# Reference block for the shared Caddyfile.
#
# This file is not installed automatically. On the shared VPS, add this block
# to the existing Caddy config by hand, then validate and reload Caddy.
#
# Cloudflare sits in front of Caddy. Two things matter here:
#
# 1. Only accept requests from Cloudflare's published edge ranges.
# 2. Replace X-Forwarded-For with Cloudflare's single-value CF-Connecting-IP
# header, so the app's TRUST_FORWARDED_FOR=true path sees the visitor, not a
# Cloudflare edge address.
#
# The ranges live in cloudflare-ranges.caddy next to this file. A systemd
# timer refreshes them from https://www.cloudflare.com/ips-v4 and /ips-v6;
# see deploy/update-cloudflare-ranges.sh and deploy/README.md.
innersquare.app {
encode zstd gzip
@cloudflare {
import cloudflare-ranges.caddy
}
handle @cloudflare {
reverse_proxy 127.0.0.1:4100 {
header_up X-Forwarded-For {http.request.header.CF-Connecting-IP}
}
}
# Direct-to-origin requests cannot spoof Cloudflare's client-IP header.
handle {
respond "Access Denied" 403
}
}
www.innersquare.app {
redir https://innersquare.app{uri} permanent
}
+1492
View File
File diff suppressed because it is too large Load Diff
+113
View File
@@ -0,0 +1,113 @@
#!/usr/bin/env bash
set -euo pipefail
# Activate a timestamped release on the VPS.
#
# Usage:
# sudo deploy/activate /tmp/chesstrainer-20261109.tar.gz
#
# Environment overrides:
# APP_USER, APP_ROOT, SERVICE, HEALTH_URL, KEEP_RELEASES, RELEASE_ID,
# BACKUP_BIN, SKIP_PRE_DEPLOY_BACKUP=1
if [[ "${EUID:-$(id -u)}" -ne 0 ]]; then
echo "activate: run with sudo" >&2
exit 1
fi
TARBALL="${1:-}"
if [[ -z "$TARBALL" || ! -f "$TARBALL" ]]; then
echo "usage: sudo $0 /path/to/chesstrainer-release.tar.gz" >&2
exit 1
fi
APP_USER="${APP_USER:-chesstrainer}"
APP_ROOT="${APP_ROOT:-/opt/chesstrainer}"
SERVICE="${SERVICE:-chesstrainer}"
HEALTH_URL="${HEALTH_URL:-http://127.0.0.1:4100/health}"
KEEP_RELEASES="${KEEP_RELEASES:-5}"
RELEASE_ID="${RELEASE_ID:-$(date -u +%Y%m%d%H%M%S)}"
BACKUP_BIN="${BACKUP_BIN:-/usr/local/sbin/chesstrainer-backup}"
SKIP_PRE_DEPLOY_BACKUP="${SKIP_PRE_DEPLOY_BACKUP:-0}"
if [[ ! "$RELEASE_ID" =~ ^[A-Za-z0-9._-]+$ ]]; then
echo "activate: RELEASE_ID may contain only letters, digits, dot, underscore and dash" >&2
exit 1
fi
if [[ ! "$KEEP_RELEASES" =~ ^[0-9]+$ ]] || [[ "$KEEP_RELEASES" -lt 1 ]]; then
echo "activate: KEEP_RELEASES must be a positive integer" >&2
exit 1
fi
health_check() {
curl --fail --silent --show-error \
--retry 10 --retry-delay 2 --retry-connrefused \
"$HEALTH_URL" >/dev/null
}
install -d -o "$APP_USER" -g "$APP_USER" "$APP_ROOT/releases"
PREVIOUS="$(readlink -f "$APP_ROOT/current" 2>/dev/null || true)"
RELEASE_DIR="$APP_ROOT/releases/$RELEASE_ID"
echo "activate: extracting $TARBALL -> $RELEASE_DIR"
install -d -o "$APP_USER" -g "$APP_USER" "$RELEASE_DIR"
tar -xzf "$TARBALL" -C "$RELEASE_DIR"
chown -R "$APP_USER:$APP_USER" "$RELEASE_DIR"
if [[ "$SKIP_PRE_DEPLOY_BACKUP" == "1" ]]; then
echo "activate: SKIP_PRE_DEPLOY_BACKUP=1, not taking a pre-deploy dump"
else
backup_script="$BACKUP_BIN"
if [[ ! -x "$backup_script" ]]; then
backup_script="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/backup"
fi
if [[ ! -x "$backup_script" ]]; then
echo "activate: no backup script at $BACKUP_BIN or next to activate" >&2
echo "activate: install deploy/backup or set SKIP_PRE_DEPLOY_BACKUP=1" >&2
exit 1
fi
# Migrations run in ExecStartPre after this, so the dump must exist first.
echo "activate: taking a pre-deploy dump"
if ! BACKUP_TAG=predeploy LOCK_WAIT=120 "$backup_script"; then
echo "activate: pre-deploy dump failed, aborting" >&2
echo "activate: fix the backup or re-run with SKIP_PRE_DEPLOY_BACKUP=1" >&2
exit 1
fi
fi
echo "activate: pointing current at $RELEASE_DIR"
ln -sfn "$RELEASE_DIR" "$APP_ROOT/current"
if systemctl restart "$SERVICE" && health_check; then
echo "activate: $RELEASE_ID is live"
if [[ "$KEEP_RELEASES" -gt 0 ]]; then
find "$APP_ROOT/releases" -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\n' \
| sort -nr \
| tail -n +"$((KEEP_RELEASES + 1))" \
| cut -d' ' -f2- \
| while read -r old_release; do
[[ -z "$old_release" ]] && continue
[[ "$old_release" == "$(readlink -f "$APP_ROOT/current")" ]] && continue
echo "activate: pruning $old_release"
rm -rf -- "$old_release"
done
fi
exit 0
fi
echo "activate: health check failed" >&2
if [[ -n "$PREVIOUS" && -d "$PREVIOUS" ]]; then
echo "activate: rolling back to $PREVIOUS" >&2
ln -sfn "$PREVIOUS" "$APP_ROOT/current"
systemctl restart "$SERVICE" || true
health_check || echo "activate: rollback health check also failed" >&2
fi
exit 1
Executable
+266
View File
@@ -0,0 +1,266 @@
#!/usr/bin/env bash
#
# Dump, verify, encrypt, prune and report on the production database.
#
# Installed as /usr/local/sbin/chesstrainer-backup (root-owned 0755) and run by
# chesstrainer-backup.timer. deploy/activate also calls it before migrations.
# Do not run the copy under /opt/chesstrainer/src as root: that tree belongs to
# the application user.
#
# sudo systemctl start chesstrainer-backup # daily run, as the timer does
# sudo BACKUP_TAG=manual chesstrainer-backup # ad-hoc, pruned by age
#
# Configuration lives in /etc/chesstrainer/backup.env (root:root 0600). See
# deploy/README.md §Backups. Every setting can also be passed as an environment
# variable.
#
# Each run prints exactly one JSON line (backup.completed or backup.failed) so
# journald, and #140's log shipping, can pick it up.
set -euo pipefail
umask 077
ENV_FILE="${ENV_FILE:-/etc/chesstrainer/backup.env}"
if [[ -r "$ENV_FILE" ]]; then
# shellcheck disable=SC1090
source "$ENV_FILE"
fi
DB_CONTAINER="${DB_CONTAINER:-chesstrainer-db}"
PG_USER="${PG_USER:-chesstrainer}"
PG_DB="${PG_DB:-chesstrainer_prod}"
BACKUP_DIR="${BACKUP_DIR:-/var/backups/chesstrainer}"
EXPECTED_ROLES="${EXPECTED_ROLES:-chesstrainer chesstrainer_ro}"
AGE_RECIPIENT="${AGE_RECIPIENT:-}"
HEALTHCHECK_URL="${HEALTHCHECK_URL:-}"
SKIP_HEARTBEAT="${SKIP_HEARTBEAT:-0}"
MIN_FREE_MB="${MIN_FREE_MB:-2048}"
LOCAL_PLAINTEXT_DAYS="${LOCAL_PLAINTEXT_DAYS:-3}"
LOCAL_ENCRYPTED_DAYS="${LOCAL_ENCRYPTED_DAYS:-14}"
PREDEPLOY_KEEP="${PREDEPLOY_KEEP:-5}"
BACKUP_TAG="${BACKUP_TAG:-daily}"
LOCK_WAIT="${LOCK_WAIT:-0}"
START_SECONDS=$SECONDS
FAILURE=""
log_event() {
local event="$1"
local extra="${2:-}"
printf '{"timestamp":"%s","event":"%s","tag":"%s"%s}\n' \
"$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$event" "$BACKUP_TAG" "$extra"
}
heartbeat() {
local outcome="$1"
[[ "$SKIP_HEARTBEAT" == "1" ]] && return 0
[[ -n "$HEALTHCHECK_URL" ]] || return 0
local url="${HEALTHCHECK_URL%/}"
[[ "$outcome" == "fail" ]] && url="$url/fail"
if ! curl --fail --silent --show-error \
--max-time 10 --retry 2 --retry-delay 2 \
--output /dev/null "$url"; then
echo "backup: heartbeat ping failed (run result is unaffected)" >&2
fi
}
fail() {
FAILURE="$*"
exit 1
}
on_exit() {
local status=$?
if ((status != 0)); then
find "$BACKUP_DIR" -maxdepth 1 -name '*.partial' -delete 2>/dev/null || true
log_event backup.failed ",\"reason\":\"${FAILURE:-exit $status}\""
heartbeat fail
fi
exit "$status"
}
trap on_exit EXIT
trap 'exit 143' TERM INT
if [[ "${EUID:-$(id -u)}" -ne 0 ]]; then
fail "run as root"
fi
[[ "$BACKUP_TAG" =~ ^[a-z0-9]+$ ]] || fail "BACKUP_TAG may contain only lowercase letters and digits"
[[ "$MIN_FREE_MB" =~ ^[0-9]+$ ]] || fail "MIN_FREE_MB must be an integer"
[[ "$LOCAL_PLAINTEXT_DAYS" =~ ^[0-9]+$ ]] || fail "LOCAL_PLAINTEXT_DAYS must be an integer"
[[ "$LOCAL_ENCRYPTED_DAYS" =~ ^[0-9]+$ ]] || fail "LOCAL_ENCRYPTED_DAYS must be an integer"
[[ "$PREDEPLOY_KEEP" =~ ^[0-9]+$ ]] || fail "PREDEPLOY_KEEP must be an integer"
[[ "$LOCK_WAIT" =~ ^[0-9]+$ ]] || fail "LOCK_WAIT must be an integer"
[[ "$AGE_RECIPIENT" == age1* ]] || fail "AGE_RECIPIENT is not set to an age public key"
if [[ "$SKIP_HEARTBEAT" != "1" && -z "$HEALTHCHECK_URL" ]]; then
fail "HEALTHCHECK_URL is not set (set SKIP_HEARTBEAT=1 to skip the ping)"
fi
for cmd in docker flock curl age tar sha256sum; do
command -v "$cmd" >/dev/null 2>&1 || fail "missing command: $cmd"
done
install -d -m 0711 -o root -g root "$BACKUP_DIR"
install -d -m 0755 -o root -g root "$BACKUP_DIR/offsite"
# 0711 on the vault lets the workstation user traverse to offsite/ without
# being able to list the plaintext dumps.
chmod 0711 "$BACKUP_DIR"
chmod 0755 "$BACKUP_DIR/offsite"
exec 9>/run/lock/chesstrainer-backup.lock
if ! flock -w "$LOCK_WAIT" 9; then
if [[ "$LOCK_WAIT" == "0" ]]; then
# Overlapping timer/manual runs are not failures; the other run reports.
log_event backup.skipped ',"reason":"another backup is running"'
exit 0
fi
fail "another backup is still running"
fi
free_mb="$(df -Pm "$BACKUP_DIR" | awk 'NR == 2 { print $4 }')"
[[ "$free_mb" =~ ^[0-9]+$ ]] || fail "cannot read free space for $BACKUP_DIR"
if ((free_mb < MIN_FREE_MB)); then
fail "only ${free_mb}MB free on $BACKUP_DIR, need ${MIN_FREE_MB}MB"
fi
timestamp="$(date -u +%Y%m%dT%H%M%SZ)"
if [[ "$BACKUP_TAG" == "daily" ]]; then
prefix="$timestamp"
else
prefix="$timestamp-$BACKUP_TAG"
fi
dump="$BACKUP_DIR/$prefix.dump"
globals="$BACKUP_DIR/$prefix.globals.sql"
counts="$BACKUP_DIR/$prefix.counts"
checksums="$BACKUP_DIR/$prefix.sha256"
archive="$BACKUP_DIR/offsite/$prefix.tar.age"
# Row counts first: writes between this query and the dump can only push the
# restored counts up, so the drill treats this file as a lower bound.
read -r -d '' counts_sql <<'SQL' || true
select 'users=' || count(*) from users
union all select 'endgames=' || count(*) from endgames
union all select 'attempts=' || count(*) from attempts;
SQL
docker exec "$DB_CONTAINER" psql -U "$PG_USER" -d "$PG_DB" \
-At -v ON_ERROR_STOP=1 -c "$counts_sql" >"$counts.partial" ||
fail "row count query failed"
[[ -s "$counts.partial" ]] || fail "row count query returned nothing"
docker exec "$DB_CONTAINER" pg_dump -U "$PG_USER" -d "$PG_DB" -Fc \
>"$dump.partial" || fail "pg_dump failed"
[[ -s "$dump.partial" ]] || fail "pg_dump produced an empty file"
# pg_restore -l reads the archive header and table of contents. It needs the
# Postgres client matching the server, so run it inside the container.
docker exec -i "$DB_CONTAINER" pg_restore -l \
<"$dump.partial" >/dev/null || fail "pg_restore -l rejected the dump"
docker exec "$DB_CONTAINER" pg_dumpall -U "$PG_USER" --globals-only \
>"$globals.partial" || fail "pg_dumpall --globals-only failed"
[[ -s "$globals.partial" ]] || fail "globals dump is empty"
# shellcheck disable=SC2086 # EXPECTED_ROLES is a space-separated list
for role in $EXPECTED_ROLES; do
grep -Eq "^CREATE ROLE \"?${role}\"?( |;)" "$globals.partial" ||
fail "globals dump is missing role $role"
done
# Promote only after every check passes, so a broken dump never looks finished.
mv "$counts.partial" "$counts"
mv "$dump.partial" "$dump"
mv "$globals.partial" "$globals"
(
cd "$BACKUP_DIR"
sha256sum "${dump##*/}" "${globals##*/}" "${counts##*/}" >"${checksums##*/}"
)
tar -C "$BACKUP_DIR" -cf - \
"${dump##*/}" "${globals##*/}" "${counts##*/}" "${checksums##*/}" |
age --recipient "$AGE_RECIPIENT" --output "$archive.partial" ||
fail "encrypting the dump failed"
chmod 0644 "$archive.partial"
mv "$archive.partial" "$archive"
# ---------------------------------------------------------------------------
# Retention
# ---------------------------------------------------------------------------
aged() {
[[ -n "$(find "$1" -maxdepth 0 -mtime +"$2" -print -quit 2>/dev/null)" ]]
}
remove_plaintext_set() {
local prefix="$1"
rm -f -- \
"$BACKUP_DIR/$prefix.dump" \
"$BACKUP_DIR/$prefix.globals.sql" \
"$BACKUP_DIR/$prefix.counts" \
"$BACKUP_DIR/$prefix.sha256"
}
prune_plaintext_by_age() {
local dump base prefix
while IFS= read -r dump; do
base="${dump##*/}"
prefix="${base%%.*}"
[[ "$base" == *-predeploy.dump ]] && continue
if aged "$dump" "$LOCAL_PLAINTEXT_DAYS"; then
echo "backup: pruning $prefix (plaintext older than ${LOCAL_PLAINTEXT_DAYS}d)" >&2
remove_plaintext_set "$prefix"
fi
done < <(find "$BACKUP_DIR" -maxdepth 1 -type f -name '*.dump')
}
prune_predeploy_plaintext() {
local -a dumps
local i prefix
mapfile -t dumps < <(
find "$BACKUP_DIR" -maxdepth 1 -type f -name '*-predeploy.dump' -printf '%f\n' | sort -r
)
for ((i = PREDEPLOY_KEEP; i < ${#dumps[@]}; i++)); do
prefix="${dumps[i]%%.*}"
echo "backup: pruning $prefix (keeping last ${PREDEPLOY_KEEP} pre-deploy dumps)" >&2
remove_plaintext_set "$prefix"
done
}
prune_encrypted() {
local archive
while IFS= read -r archive; do
echo "backup: pruning ${archive##*/} (encrypted older than ${LOCAL_ENCRYPTED_DAYS}d)" >&2
rm -f -- "$archive"
done < <(
find "$BACKUP_DIR/offsite" -maxdepth 1 -type f -name '*.tar.age' -mtime +"$LOCAL_ENCRYPTED_DAYS"
)
}
prune_plaintext_by_age
prune_predeploy_plaintext
prune_encrypted
dump_bytes="$(stat -c %s "$dump")"
archive_bytes="$(stat -c %s "$archive")"
log_event backup.completed ",\"dump\":\"$prefix\",\"dump_bytes\":$dump_bytes,\"offsite_bytes\":$archive_bytes,\"duration_s\":$((SECONDS - START_SECONDS))"
heartbeat ok
+33
View File
@@ -0,0 +1,33 @@
# /etc/chesstrainer/backup.env -- root:root, mode 0600.
#
# Sourced by /usr/local/sbin/chesstrainer-backup. Every value below shows the
# default; only AGE_RECIPIENT and HEALTHCHECK_URL must be set. Keep secrets out
# of the repo and out of world-readable files.
# age public key, generated on the workstation with `age-keygen`.
# The private key never leaves the workstation.
AGE_RECIPIENT=age1...
# healthchecks.io (or compatible) ping URL. The script pings it after a good
# run and pings <url>/fail after a bad one. Set SKIP_HEARTBEAT=1 to run without
# monitoring (testing only).
HEALTHCHECK_URL=https://hc-ping.com/00000000-0000-0000-0000-000000000000
# Refuse to dump when the filesystem has less than this much free space.
MIN_FREE_MB=2048
# Retention. Dumps and their globals/counts/checksum siblings disappear as a
# set; only the encrypted archives in offsite/ live for the longer window.
LOCAL_PLAINTEXT_DAYS=3
LOCAL_ENCRYPTED_DAYS=14
PREDEPLOY_KEEP=5
# Postgres coordinates. The container trusts local Unix-socket connections, so
# no password belongs here.
DB_CONTAINER=chesstrainer-db
PG_USER=chesstrainer
PG_DB=chesstrainer_prod
BACKUP_DIR=/var/backups/chesstrainer
# Roles the globals dump must be able to recreate.
EXPECTED_ROLES="chesstrainer chesstrainer_ro"
@@ -0,0 +1,7 @@
[Unit]
Description=Report a failed Inner Square Chess database backup
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
[Service]
Type=oneshot
ExecStart=/usr/bin/logger --tag chesstrainer-backup --priority daemon.err --stderr backup.unit-failed: chesstrainer-backup.service failed, see journalctl -u chesstrainer-backup
+16
View File
@@ -0,0 +1,16 @@
[Unit]
Description=Inner Square Chess database backup
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
After=network-online.target docker.service
Wants=network-online.target
OnFailure=chesstrainer-backup-failure.service
[Service]
Type=oneshot
User=root
Group=root
ExecStart=/usr/local/sbin/chesstrainer-backup
Nice=10
IOSchedulingClass=idle
TimeoutStartSec=10min
SyslogIdentifier=chesstrainer-backup
+13
View File
@@ -0,0 +1,13 @@
[Unit]
Description=Daily Inner Square Chess database backup
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
[Timer]
OnCalendar=*-*-* 03:15:00 UTC
RandomizedDelaySec=5m
AccuracySec=1m
Persistent=true
Unit=chesstrainer-backup.service
[Install]
WantedBy=timers.target
@@ -0,0 +1,11 @@
[Unit]
Description=Refresh Cloudflare CIDRs for Caddy
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/docs/security.md
After=network-online.target
Wants=network-online.target
[Service]
Type=oneshot
ExecStart=/usr/local/sbin/chesstrainer-update-cloudflare-ranges
TimeoutStartSec=2min
Nice=10
@@ -0,0 +1,11 @@
[Unit]
Description=Hourly refresh of Cloudflare CIDRs for Caddy
[Timer]
OnCalendar=hourly
RandomizedDelaySec=10m
Persistent=true
Unit=chesstrainer-cloudflare-ranges.service
[Install]
WantedBy=timers.target
+13
View File
@@ -0,0 +1,13 @@
[Unit]
Description=Probe the public Inner Square Chess app and report to healthchecks.io
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
After=network-online.target
Wants=network-online.target
[Service]
Type=oneshot
User=root
Group=root
ExecStart=/usr/local/sbin/chesstrainer-probe
TimeoutStartSec=90s
SyslogIdentifier=chesstrainer-probe
+12
View File
@@ -0,0 +1,12 @@
[Unit]
Description=Probe the public Inner Square Chess app every two minutes
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
[Timer]
OnBootSec=30s
OnUnitActiveSec=2min
AccuracySec=5s
Unit=chesstrainer-probe.service
[Install]
WantedBy=timers.target
+20
View File
@@ -0,0 +1,20 @@
[Unit]
Description=Inner Square Chess (Phoenix)
After=network.target docker.service
Wants=network.target
ConditionPathExists=/opt/chesstrainer/current/bin/server
[Service]
Type=simple
User=chesstrainer
Group=chesstrainer
EnvironmentFile=/etc/chesstrainer/env
WorkingDirectory=/opt/chesstrainer/current
ExecStartPre=/opt/chesstrainer/current/bin/migrate
ExecStart=/opt/chesstrainer/current/bin/server
Restart=always
RestartSec=5
SyslogIdentifier=chesstrainer
[Install]
WantedBy=multi-user.target
+3
View File
@@ -0,0 +1,3 @@
# Generated by deploy/update-cloudflare-ranges.sh.
# Source: https://www.cloudflare.com/ips-v4 and /ips-v6
remote_ip 173.245.48.0/20 103.21.244.0/22 103.22.200.0/22 103.31.4.0/22 141.101.64.0/18 108.162.192.0/18 190.93.240.0/20 188.114.96.0/20 197.234.240.0/22 198.41.128.0/17 162.158.0.0/15 104.16.0.0/13 104.24.0.0/14 172.64.0.0/13 131.0.72.0/22 2400:cb00::/32 2606:4700::/32 2803:f800::/32 2405:b500::/32 2405:8100::/32 2a06:98c0::/29 2c0f:f248::/32
+26
View File
@@ -0,0 +1,26 @@
# Reference only. Merge the service and volume below into the VPS's unified
# docker-compose.yml. Do not run this file as a separate Compose project.
#
# 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.6@sha256:...
services:
chesstrainer-db:
container_name: chesstrainer-db
image: postgres:18.6
restart: unless-stopped
env_file: /etc/chesstrainer/postgres.env
ports:
- "127.0.0.1:5432:5432"
volumes:
- chesstrainer_pgdata:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
interval: 5s
timeout: 5s
retries: 10
volumes:
chesstrainer_pgdata:
name: chesstrainer_pgdata
Executable
+359
View File
@@ -0,0 +1,359 @@
#!/usr/bin/env bash
#
# Probe the public Inner Square Chess app and report the verdict to
# healthchecks.io.
#
# Installed as /usr/local/sbin/chesstrainer-probe (root-owned 0755) and run by
# chesstrainer-probe.timer every two minutes. The probe deliberately goes
# through the public hostname, not loopback: DNS, Cloudflare, Caddy and the
# origin allowlist are part of what a visitor depends on. A loopback health
# URL is still consulted on failure, as evidence only.
#
# sudo /usr/local/sbin/chesstrainer-probe
# sudo /usr/local/sbin/chesstrainer-probe --dry-run # no network, no config
#
# Configuration lives in /etc/chesstrainer/probe.env (root:root 0600). See
# deploy/README.md §Monitoring and alerting. Individual settings can be passed
# as environment variables to a manual run, which is how the drills vary the
# URL and the expected tablebase.
#
# Each run prints exactly one JSON line (probe.ok, probe.degraded or
# probe.failed) so journald, and #140's log shipping, can pick it up.
set -euo pipefail
umask 077
ENV_FILE="${ENV_FILE:-/etc/chesstrainer/probe.env}"
START_SECONDS=$SECONDS
DRY_RUN=0
TMPDIR_PROBE=""
HTTP_BODY_FILE=""
HTTP_HEADER_FILE=""
HTTP_ERROR_FILE=""
usage() {
cat <<'EOF'
Usage: chesstrainer-probe [--dry-run]
--dry-run print the verdict for the success, degraded, fail, non-JSON and
unreachable fixtures without reading the env file or making a
network request
EOF
}
while (($# > 0)); do
case "$1" in
--dry-run) DRY_RUN=1 ;;
-h | --help)
usage
exit 0
;;
*)
usage >&2
echo "probe: unknown argument: $1" >&2
exit 2
;;
esac
shift
done
log_event() {
local event="$1"
local extra="${2:-}"
printf '{"timestamp":"%s","event":"%s"%s}\n' \
"$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$event" "$extra"
}
fail() {
echo "probe: $*" >&2
exit 1
}
json_escape() {
local text="$1"
text="${text//\\/\\\\}"
text="${text//\"/\\\"}"
text="${text//$'\n'/\\n}"
text="${text//$'\r'/\\r}"
text="${text//$'\t'/\\t}"
text="$(printf '%s' "$text" | LC_ALL=C tr -d '[:cntrl:]')"
printf '%s' "$text"
}
body_snippet() {
local file="$1"
if [[ -s "$file" ]]; then
head -c "$MAX_BODY_BYTES" "$file"
fi
}
json_field() {
local key="$1"
local json="$2"
if [[ "$json" =~ \"$key\"[[:space:]]*:[[:space:]]*\"([^\"]*)\" ]]; then
printf '%s' "${BASH_REMATCH[1]}"
fi
}
http_get() {
local url="$1"
local prefix="$2"
local proto="$3"
local status=""
local exit_code=0
HTTP_BODY_FILE="$prefix.body"
HTTP_HEADER_FILE="$prefix.headers"
HTTP_ERROR_FILE="$prefix.error"
: >"$HTTP_BODY_FILE"
: >"$HTTP_HEADER_FILE"
: >"$HTTP_ERROR_FILE"
if status="$(curl --silent --show-error --location \
--proto "$proto" \
--connect-timeout 5 \
--max-time "$PROBE_TIMEOUT_SECONDS" \
--output "$HTTP_BODY_FILE" \
--dump-header "$HTTP_HEADER_FILE" \
--write-out '%{http_code}' \
"$url")"; then
exit_code=0
else
exit_code=$?
fi
HTTP_STATUS="${status:-000}"
CURL_EXIT="$exit_code"
}
# Sets VERDICT (ok, degraded, failed), REASON, DB and TABLEBASE. The database is
# the only hard dependency; a missing local tablebase still serves users from
# Lichess, so it is reported as a green but degraded check-in.
evaluate() {
local status="$1"
local exit_code="$2"
local body="$3"
local trimmed=""
VERDICT="failed"
REASON=""
DB=""
TABLEBASE=""
if ((exit_code != 0)); then
REASON="unreachable: curl exit $exit_code"
return
fi
if [[ "$status" != "200" ]]; then
REASON="http $status"
return
fi
trimmed="${body#"${body%%[![:space:]]*}"}"
trimmed="${trimmed%"${trimmed##*[![:space:]]}"}"
if [[ "${trimmed:0:1}" != "{" || "${trimmed: -1}" != "}" ]]; then
REASON="non-JSON response"
return
fi
DB="$(json_field db "$body")"
TABLEBASE="$(json_field tablebase "$body")"
if [[ -z "$DB" ]]; then
REASON="response has no db field"
return
fi
if [[ "$DB" != "ok" ]]; then
REASON="db is $DB"
return
fi
if [[ "$EXPECT_TABLEBASE" != "any" && "$TABLEBASE" != "$EXPECT_TABLEBASE" ]]; then
VERDICT="degraded"
REASON="tablebase is ${TABLEBASE:-unknown}, expected $EXPECT_TABLEBASE"
return
fi
VERDICT="ok"
}
# Exactly one call site per run, and one call site per outcome, so a forced
# failure can only ever produce one fail ping.
ping_check() {
local outcome="$1"
local body="$2"
local url=""
local body_file=""
if [[ -z "$HEALTHCHECK_URL" ]]; then
echo "probe: HEALTHCHECK_URL is not set, not reporting" >&2
return 0
fi
url="${HEALTHCHECK_URL%/}"
if [[ "$outcome" == "fail" ]]; then
url="$url/fail"
fi
body_file="$(mktemp)"
printf '%s' "$body" >"$body_file"
if ! curl --silent --show-error --fail \
--max-time 10 --retry 2 --retry-delay 2 \
--header 'Content-Type: application/json' \
--data-binary "@$body_file" \
--output /dev/null "$url"; then
echo "probe: check-in ping failed (run result is unaffected)" >&2
fi
rm -f "$body_file"
}
origin_evidence() {
local prefix="$1"
http_get "$ORIGIN_URL" "$prefix" '=https,http'
ORIGIN_STATUS="$HTTP_STATUS"
ORIGIN_EXIT="$CURL_EXIT"
ORIGIN_BODY="$(body_snippet "$HTTP_BODY_FILE")"
ORIGIN_ERROR="$(body_snippet "$HTTP_ERROR_FILE")"
}
fail_evidence() {
local evidence=""
evidence="$(printf '{"probe":"failed","reason":"%s","url":"%s","http_status":"%s","curl_exit":%s' \
"$(json_escape "$REASON")" "$(json_escape "$PROBE_URL")" "$PUBLIC_STATUS" "$PUBLIC_EXIT")"
if [[ -n "$ERROR_TEXT" ]]; then
evidence+="$(printf ',"error":"%s"' "$(json_escape "$ERROR_TEXT")")"
fi
if [[ -n "$BODY" ]]; then
evidence+="$(printf ',"body":"%s"' "$(json_escape "$BODY")")"
fi
evidence+="$(printf ',"origin_url":"%s","origin_status":"%s","origin_curl_exit":%s' \
"$(json_escape "$ORIGIN_URL")" "$ORIGIN_STATUS" "$ORIGIN_EXIT")"
if [[ -n "$ORIGIN_BODY" ]]; then
evidence+="$(printf ',"origin_body":"%s"' "$(json_escape "$ORIGIN_BODY")")"
fi
if [[ -n "$ORIGIN_ERROR" ]]; then
evidence+="$(printf ',"origin_error":"%s"' "$(json_escape "$ORIGIN_ERROR")")"
fi
printf '%s}' "$evidence"
}
dry_run() {
local -a scenarios=(
'HTTP 200, healthy|200|0|{"process":"ok","status":"ok","db":"ok","tablebase":"local"}'
'HTTP 200, tablebase fallback|200|0|{"process":"ok","status":"degraded","db":"ok","tablebase":"fallback"}'
'HTTP 503, db down|503|0|{"process":"ok","status":"down","db":"down","tablebase":"local"}'
'HTTP 200, non-JSON|200|0|<html><body>502 Bad Gateway</body></html>'
'timeout, no response|000|28|'
)
local row name status exit_code body action
printf 'probe: dry run, no network calls and no configuration read\n'
printf 'probe: every fixture is evaluated with EXPECT_TABLEBASE=local\n\n'
printf '%-28s %-9s %-46s %s\n' "scenario" "verdict" "reason" "would ping"
for row in "${scenarios[@]}"; do
IFS='|' read -r name status exit_code body <<<"$row"
EXPECT_TABLEBASE="local"
evaluate "$status" "$exit_code" "$body"
case "$VERDICT" in
ok) action="success, raw /health JSON" ;;
degraded) action="success, mismatch evidence" ;;
*) action="fail, evidence JSON" ;;
esac
printf '%-28s %-9s %-46s %s\n' "$name" "$VERDICT" "${REASON:--}" "$action"
done
printf '\nprobe: dry run complete, no check-ins sent\n'
}
if ((DRY_RUN)); then
dry_run
exit 0
fi
# Overrides passed on the command line survive the env file, so the drills can
# vary the URL or the expected tablebase without editing a root-only file.
_OVERRIDE_PROBE_URL="${PROBE_URL:-}"
_OVERRIDE_EXPECT_TABLEBASE="${EXPECT_TABLEBASE:-}"
_OVERRIDE_PROBE_TIMEOUT_SECONDS="${PROBE_TIMEOUT_SECONDS:-}"
if [[ -r "$ENV_FILE" ]]; then
# shellcheck disable=SC1090
source "$ENV_FILE"
else
fail "cannot read $ENV_FILE (set ENV_FILE to override)"
fi
PROBE_URL="${_OVERRIDE_PROBE_URL:-${PROBE_URL:-}}"
EXPECT_TABLEBASE="${_OVERRIDE_EXPECT_TABLEBASE:-${EXPECT_TABLEBASE:-local}}"
PROBE_TIMEOUT_SECONDS="${_OVERRIDE_PROBE_TIMEOUT_SECONDS:-${PROBE_TIMEOUT_SECONDS:-10}}"
HEALTHCHECK_URL="${HEALTHCHECK_URL:-}"
ORIGIN_URL="${ORIGIN_URL:-http://127.0.0.1:4100/health}"
MAX_BODY_BYTES="${MAX_BODY_BYTES:-2000}"
[[ "$PROBE_URL" == https://* ]] || fail "PROBE_URL must be an https URL"
[[ -n "$HEALTHCHECK_URL" ]] || fail "HEALTHCHECK_URL is not set"
[[ "$EXPECT_TABLEBASE" =~ ^(local|fallback|not_configured|any)$ ]] ||
fail "EXPECT_TABLEBASE must be local, fallback, not_configured or any"
[[ "$PROBE_TIMEOUT_SECONDS" =~ ^[0-9]+$ ]] || fail "PROBE_TIMEOUT_SECONDS must be an integer"
command -v curl >/dev/null 2>&1 || fail "missing command: curl"
TMPDIR_PROBE="$(mktemp -d)"
cleanup() {
if [[ -n "$TMPDIR_PROBE" && -d "$TMPDIR_PROBE" ]]; then
rm -rf "$TMPDIR_PROBE"
fi
}
trap cleanup EXIT
trap 'exit 143' TERM INT
http_get "$PROBE_URL" "$TMPDIR_PROBE/public" '=https'
PUBLIC_STATUS="$HTTP_STATUS"
PUBLIC_EXIT="$CURL_EXIT"
BODY="$(body_snippet "$HTTP_BODY_FILE")"
ERROR_TEXT="$(body_snippet "$HTTP_ERROR_FILE")"
evaluate "$PUBLIC_STATUS" "$PUBLIC_EXIT" "$BODY"
case "$VERDICT" in
ok)
log_event probe.ok ",\"status\":\"$PUBLIC_STATUS\",\"tablebase\":\"$(json_escape "$TABLEBASE")\",\"duration_s\":$((SECONDS - START_SECONDS))"
ping_check ok "$BODY"
;;
degraded)
evidence="$(printf '{"expected_tablebase":"%s","health":%s}' \
"$(json_escape "$EXPECT_TABLEBASE")" "$BODY")"
log_event probe.degraded ",\"reason\":\"$(json_escape "$REASON")\",\"tablebase\":\"$(json_escape "$TABLEBASE")\",\"duration_s\":$((SECONDS - START_SECONDS))"
ping_check ok "$evidence"
;;
*)
origin_evidence "$TMPDIR_PROBE/origin"
evidence="$(fail_evidence)"
log_event probe.failed ",\"reason\":\"$(json_escape "$REASON")\",\"http_status\":\"$PUBLIC_STATUS\",\"curl_exit\":$PUBLIC_EXIT,\"duration_s\":$((SECONDS - START_SECONDS))"
ping_check fail "$evidence"
exit 1
;;
esac
+28
View File
@@ -0,0 +1,28 @@
# /etc/chesstrainer/probe.env -- root:root, mode 0600.
#
# Sourced by /usr/local/sbin/chesstrainer-probe. The check-in URL is a secret:
# anyone who has it can mark the check green, so keep it out of the repo and
# out of world-readable files.
# The public URL a visitor actually requests. Probing the edge rather than
# loopback is deliberate: DNS, TLS, Cloudflare, Caddy and the origin allowlist
# are part of the contract. Must be https.
PROBE_URL=https://innersquare.app/health
# healthchecks.io ping URL for the two-minute probe check. A healthy run posts
# to it; a failed run posts to <url>/fail.
HEALTHCHECK_URL=https://hc-ping.com/00000000-0000-0000-0000-000000000000
# The tablebase value /health should report. "local" means Syzygy files are
# loaded, "fallback" means Lichess is used, "not_configured" means
# TABLEBASE_PATH is unset. A mismatch is reported as degraded, never as down.
# Set to "any" to accept whatever the app reports.
EXPECT_TABLEBASE=local
# Whole-request timeout. The timer runs every two minutes, so keep this well
# under that.
PROBE_TIMEOUT_SECONDS=10
# Loopback health URL. It is consulted only when the public probe fails, and
# only as evidence: it does not change the verdict. Defaults to the value shown.
# ORIGIN_URL=http://127.0.0.1:4100/health
+58
View File
@@ -0,0 +1,58 @@
#!/usr/bin/env bash
set -euo pipefail
# Roll back to a previous release.
#
# Usage:
# sudo deploy/rollback # most recent previous release
# sudo deploy/rollback 20261109120000 # release id under /opt/chesstrainer/releases
# sudo deploy/rollback /opt/chesstrainer/releases/20261109120000
if [[ "${EUID:-$(id -u)}" -ne 0 ]]; then
echo "rollback: run with sudo" >&2
exit 1
fi
APP_ROOT="${APP_ROOT:-/opt/chesstrainer}"
SERVICE="${SERVICE:-chesstrainer}"
HEALTH_URL="${HEALTH_URL:-http://127.0.0.1:4100/health}"
health_check() {
curl --fail --silent --show-error \
--retry 10 --retry-delay 2 --retry-connrefused \
"$HEALTH_URL" >/dev/null
}
CURRENT="$(readlink -f "$APP_ROOT/current" 2>/dev/null || true)"
if [[ $# -gt 0 ]]; then
case "$1" in
/*) TARGET="$1" ;;
*) TARGET="$APP_ROOT/releases/$1" ;;
esac
else
TARGET="$(
find "$APP_ROOT/releases" -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\n' \
| sort -nr \
| cut -d' ' -f2- \
| while read -r release; do
if [[ "$release" != "$CURRENT" ]]; then
echo "$release"
break
fi
done
)"
fi
if [[ -z "$TARGET" || ! -d "$TARGET" ]]; then
echo "rollback: no previous release found" >&2
exit 1
fi
echo "rollback: pointing current at $TARGET"
ln -sfn "$TARGET" "$APP_ROOT/current"
systemctl restart "$SERVICE"
health_check
echo "rollback: $TARGET is live"
+20
View File
@@ -0,0 +1,20 @@
__SITE_ADDRESS__ {
root * /var/www/innersquare
encode zstd gzip
try_files {path}.html {path}
file_server
header {
X-Content-Type-Options nosniff
X-Frame-Options DENY
Referrer-Policy strict-origin-when-cross-origin
Permissions-Policy "geolocation=(), microphone=(), camera=()"
X-Robots-Tag "noindex, nofollow"
}
@immutable path /fonts/* /favicon.ico
header @immutable Cache-Control "public, max-age=31536000, immutable"
@html path / /index.html /privacy /terms-conditions
header @html Cache-Control "no-cache"
}
+167
View File
@@ -0,0 +1,167 @@
# Static coming-soon page
A self-contained branding page for the domain while the gated app (#116) and
mail delivery (#84) are still outstanding. It needs no BEAM, no database, no
newsletter form, and no JavaScript — just static files and Caddy.
```
deploy/static/
├── index.html # page + inline CSS; uses the app's real brand tokens
├── privacy.html # privacy policy, served at /privacy
├── terms-conditions.html # terms, served at /terms-conditions
├── mentions-legales.html # French legal notice, served at /mentions-legales
├── legal.css # shared styles for the legal pages
├── fonts/ # DM Sans + DM Serif Display woff2 files
├── favicon.ico # copied from priv/static
├── Caddyfile # site block template; rendered by deploy.sh --caddy
├── deploy.sh # upload files; optional marked Caddy block
└── README.md
```
The Caddyfile uses `try_files {path}.html {path}` so `/privacy`,
`/terms-conditions`, and `/mentions-legales` serve the matching `.html` files
without a redirect.
## Preview locally
```sh
python3 -m http.server 8080 --directory deploy/static
# open http://localhost:8080
```
Python maps URLs directly to files, so it serves `/privacy.html` and
`/terms-conditions.html` but not the extensionless `/privacy` or
`/terms-conditions` links. Those depend on Caddy's `try_files`.
To preview the exact production routing, run the Caddyfile locally:
```sh
sed -e 's#__SITE_ADDRESS__#:8098#' \
-e 's#/var/www/innersquare#/srv#' \
deploy/static/Caddyfile > /tmp/Caddyfile.local
docker run --rm -it -p 8098:8098 \
-v "$PWD/deploy/static:/srv:ro" \
-v /tmp/Caddyfile.local:/etc/caddy/Caddyfile:ro \
caddy:2-alpine \
caddy run --config /etc/caddy/Caddyfile --adapter caddyfile
```
Then open `http://localhost:8098/`, `/privacy` and `/terms-conditions`.
The page is deliberately light-only — it uses the brand's paper palette
regardless of the visitor's OS theme. It references `/fonts/...` and
`/favicon.ico` from the site root, so preview it at the root (as above), not
by opening `index.html` directly.
## One-time VPS setup
1. **DNS** — point an `A` record (and `AAAA` if you have IPv6) for the domain
and `www` at the VPS.
2. **SSH user** — the deploy user needs passwordless `sudo` for the commands in
`deploy.sh`, or use your normal sudo-capable user (`VPS_USER=ubuntu`).
3. **Firewall** — allow SSH, 80 and 443. With UFW:
```sh
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
```
Also open 80/443 in your provider's security group if you have one.
4. **Caddy** — install from the official apt repository:
```sh
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
| sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
| sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy
sudo systemctl enable --now caddy
```
Caddy obtains and renews the TLS certificate automatically once DNS points
at the VPS and ports 80/443 are reachable.
## Deploy
### Files only (default)
Use this when the site block is already in your Caddy config. The script
uploads the files and **never touches Caddy**.
```sh
VPS_HOST=203.0.113.10 VPS_USER=ubuntu ./deploy/static/deploy.sh
```
Re-run this to update the page.
### Let the script manage the Caddy block (`--caddy`)
Pass `--caddy` and a `SITE_ADDRESS` to have the script add or update the site
block:
```sh
SITE_ADDRESS="innersquare.app, www.innersquare.app" \
VPS_HOST=203.0.113.10 \
VPS_USER=ubuntu \
./deploy/static/deploy.sh --caddy
```
The script edits only the region between these markers in `REMOTE_CADDYFILE`
(default `/etc/caddy/Caddyfile`):
```caddyfile
# BEGIN innersquare-coming-soon (managed by deploy/static/deploy.sh)
...
# END innersquare-coming-soon
```
It backs up the file, validates the whole config, restores the backup if
validation fails, and reloads Caddy. If the domain already appears in the file
**without** the markers — for example, a block added by hand — it refuses to
touch the file rather than risk duplicating the site.
### Single shared Caddyfile
If all your server blocks live in `/etc/caddy/Caddyfile` and the innersquare
block is already there, use the default files-only mode. Don't run `--caddy`
unless you remove the manual block first and want the script to own it.
### Dedicated file / import
You can point `REMOTE_CADDYFILE` at a dedicated file and add one import line to
the main Caddyfile:
```sh
REMOTE_CADDYFILE=/etc/caddy/conf.d/innersquare.caddy \
SITE_ADDRESS=innersquare.app \
VPS_HOST=203.0.113.10 \
VPS_USER=ubuntu \
./deploy/static/deploy.sh --caddy
```
```caddyfile
import /etc/caddy/conf.d/*.caddy
```
Optional overrides: `SSH_PORT`, `WEB_ROOT` (default `/var/www/innersquare`),
`REMOTE_CADDYFILE` (default `/etc/caddy/Caddyfile`).
## What this page deliberately does not do
- **No newsletter signup** — that waits on real mail delivery (#84) and the
gated app (#116). The legal pages are linked from the footer so the public
site has a privacy policy and terms while the signup is still gated.
- **No analytics, cookies, or JavaScript.**
- **No indexing** — `robots.txt` is absent and Caddy sends
`X-Robots-Tag: noindex, nofollow` plus the page has a robots meta tag.
## Replacing it later
When the Phoenix release lands (#117), either point Caddy's reverse proxy at
the app or remove this Caddy site block. Keep the static page around as an
instant fallback if a deploy goes wrong.
Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.
Binary file not shown.
Binary file not shown.
+707
View File
@@ -0,0 +1,707 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Inner Square Chess — Endgame Trainer</title>
<meta
name="description"
content="Short, focused endgame puzzles against tablebase-perfect defence. Learn to see the winning move and make the endgame your strongest phase."
/>
<meta name="robots" content="noindex, nofollow" />
<meta name="theme-color" content="#f4f0e6" />
<meta property="og:type" content="website" />
<meta property="og:site_name" content="Inner Square Chess" />
<meta property="og:title" content="Inner Square Chess — Endgame Trainer" />
<meta
property="og:description"
content="Short, focused endgame puzzles against tablebase-perfect defence. Launching soon."
/>
<meta name="twitter:card" content="summary" />
<link rel="icon" href="/favicon.ico" />
<style>
@font-face {
font-family: "DM Sans";
font-style: normal;
font-weight: 100 1000;
font-display: swap;
src: url("/fonts/dm-sans-variable.woff2") format("woff2");
}
@font-face {
font-family: "DM Serif Display";
font-style: normal;
font-weight: 400;
font-display: swap;
src: url("/fonts/dm-serif-display.woff2") format("woff2");
}
@font-face {
font-family: "DM Serif Display";
font-style: italic;
font-weight: 400;
font-display: swap;
src: url("/fonts/dm-serif-display-italic.woff2") format("woff2");
}
:root {
--ink: #17352d;
--ink-soft: #587068;
--paper: #f4f0e6;
--cream: #fffcf4;
--mint: #b9d7c9;
--coral: #ef755d;
--coral-dark: #d95d48;
--line: rgba(23, 53, 45, 0.15);
--color-canvas: var(--paper);
--color-canvas-raised: var(--cream);
--color-body: var(--ink);
--color-muted: var(--ink-soft);
--color-hairline: var(--line);
--color-deep: var(--ink);
--color-on-deep: var(--paper);
--color-coral: var(--coral);
--color-coral-text: #b8432c;
--color-mint-chip: var(--mint);
--color-board-light: #e9e1cc;
--color-board-dark: #81a996;
--color-piece-light: #fffdf5;
--color-piece-outline: #17352d;
color-scheme: light;
}
*,
*::before,
*::after {
box-sizing: border-box;
}
html {
scroll-behavior: smooth;
}
body {
min-width: 320px;
min-height: 100vh;
min-height: 100dvh;
margin: 0;
display: flex;
flex-direction: column;
background: var(--color-canvas);
color: var(--color-body);
font-family: "DM Sans", system-ui, -apple-system, "Segoe UI", sans-serif;
-webkit-font-smoothing: antialiased;
}
a {
color: inherit;
text-decoration: none;
}
:focus-visible {
outline: 2px solid var(--color-coral-text);
outline-offset: 2px;
}
main {
flex: 1 0 auto;
overflow: hidden;
}
/* Navigation */
.nav-wrap {
width: min(1180px, calc(100% - 48px));
height: 92px;
margin: 0 auto;
display: flex;
align-items: center;
justify-content: space-between;
border-bottom: 1px solid var(--color-hairline);
}
.brand {
display: inline-flex;
align-items: center;
gap: 10px;
font-size: 16px;
font-weight: 700;
letter-spacing: 0.18em;
}
.brand-mark {
display: grid;
place-items: center;
width: 35px;
height: 35px;
border-radius: 50%;
background: var(--color-deep);
color: var(--color-on-deep);
font-size: 21px;
letter-spacing: 0;
}
.status {
display: inline-flex;
align-items: center;
gap: 8px;
padding: 8px 14px;
border: 1px solid var(--color-hairline);
border-radius: 999px;
color: var(--color-muted);
font-size: 11px;
font-weight: 700;
letter-spacing: 0.1em;
text-transform: uppercase;
white-space: nowrap;
}
.status::before {
content: "";
width: 7px;
height: 7px;
border-radius: 50%;
background: var(--color-coral);
}
/* Hero */
.hero {
width: min(1180px, calc(100% - 48px));
min-height: 650px;
margin: 0 auto;
display: grid;
grid-template-columns: 0.91fr 1.09fr;
align-items: center;
gap: 60px;
}
.hero-copy {
position: relative;
z-index: 2;
padding: 74px 0 92px;
}
.eyebrow {
display: inline-flex;
align-items: center;
gap: 8px;
color: var(--color-coral-text);
font-size: 11px;
font-weight: 700;
letter-spacing: 0.14em;
text-transform: uppercase;
}
.eyebrow::before {
content: "";
width: 7px;
height: 7px;
border-radius: 50%;
background: var(--color-coral);
}
h1 {
max-width: 590px;
margin: 18px 0 0;
font-family: "DM Serif Display", Georgia, serif;
font-size: clamp(56px, 6vw, 87px);
font-weight: 400;
letter-spacing: -0.035em;
line-height: 0.93;
}
h1 em {
color: var(--color-coral);
font-weight: 400;
}
.hero-copy > p {
max-width: 480px;
margin: 29px 0 0;
color: var(--color-muted);
font-size: 17px;
line-height: 1.65;
}
.hero-copy > .note {
margin-top: 20px;
color: var(--color-muted);
font-size: 13px;
line-height: 1.5;
}
/* Board */
.board-stage {
position: relative;
min-height: 580px;
display: grid;
place-items: center;
}
.coral-orbit,
.mint-orbit {
position: absolute;
border-radius: 50%;
}
.coral-orbit {
width: 460px;
height: 460px;
right: -34px;
top: 46px;
background: var(--color-coral);
}
.mint-orbit {
width: 230px;
height: 230px;
left: 14px;
bottom: 28px;
background: var(--color-mint-chip);
}
.board-shell {
position: relative;
z-index: 2;
width: min(458px, 85vw);
padding: 18px;
border-radius: 12px;
background: var(--color-canvas-raised);
box-shadow: 0 26px 65px rgba(23, 53, 45, 0.25);
transform: rotate(1.5deg);
}
.board-topline,
.board-caption {
display: flex;
align-items: center;
justify-content: space-between;
}
.board-topline {
padding: 1px 1px 13px;
}
.player {
display: flex;
align-items: center;
gap: 9px;
}
.player-piece {
display: grid;
place-items: center;
width: 31px;
height: 31px;
border-radius: 50%;
background: var(--color-deep);
color: var(--color-on-deep);
font-size: 20px;
}
.player span:last-child {
display: flex;
flex-direction: column;
line-height: 1.05;
}
.player small {
color: var(--color-muted);
font-size: 8px;
letter-spacing: 0.1em;
text-transform: uppercase;
}
.player strong {
font-size: 12px;
}
.piece-count {
color: var(--color-muted);
font-size: 10px;
font-weight: 600;
letter-spacing: 0.08em;
text-transform: uppercase;
}
.chessboard {
aspect-ratio: 1;
display: grid;
grid-template-columns: repeat(8, 1fr);
overflow: hidden;
border-radius: 4px;
box-shadow: inset 0 0 0 1px rgba(0, 0, 0, 0.05);
}
.square {
position: relative;
display: grid;
place-items: center;
aspect-ratio: 1;
}
.square.light {
background: var(--color-board-light);
}
.square.dark {
background: var(--color-board-dark);
}
.piece {
position: relative;
z-index: 2;
font-family: Georgia, serif;
font-size: clamp(25px, 4vw, 42px);
line-height: 1;
transform: translateY(-1px);
}
.white-piece {
color: var(--color-piece-light);
text-shadow:
0 2px 0 var(--color-piece-outline),
1px 0 0 var(--color-piece-outline),
-1px 0 0 var(--color-piece-outline),
0 -1px 0 var(--color-piece-outline);
}
.black-piece {
color: var(--color-piece-outline);
text-shadow: 0 1px 0 rgba(255, 255, 255, 0.25);
}
.rank,
.file {
position: absolute;
z-index: 3;
color: rgba(23, 53, 45, 0.65);
font-size: 7px;
font-weight: 700;
}
.rank {
top: 3px;
left: 4px;
}
.file {
right: 4px;
bottom: 2px;
}
.square.dark .rank,
.square.dark .file {
color: rgba(255, 255, 255, 0.65);
}
.board-caption {
padding: 14px 2px 0;
}
.board-caption div {
display: flex;
flex-direction: column;
}
.board-caption span {
color: var(--color-muted);
font-size: 9px;
letter-spacing: 0.1em;
text-transform: uppercase;
}
.board-caption strong {
font-size: 13px;
}
.board-themes {
color: var(--color-coral-text) !important;
font-size: 8px !important;
font-weight: 700;
letter-spacing: 0.08em;
}
/* Footer */
.site-footer {
width: min(1180px, calc(100% - 48px));
margin: 0 auto;
padding: 44px 0;
display: flex;
align-items: center;
justify-content: space-between;
gap: 30px;
border-top: 1px solid var(--color-hairline);
}
.footer-brand {
display: flex;
flex-direction: column;
gap: 12px;
}
.footer-brand p {
margin: 0;
color: var(--color-muted);
font-size: 13px;
}
.site-footer > small {
color: var(--color-muted);
font-size: 11px;
}
.footer-links {
display: flex;
gap: 18px;
color: var(--color-muted);
font-size: 12px;
}
.footer-links a:hover {
color: var(--color-body);
}
@media (max-width: 900px) {
.hero {
grid-template-columns: 1fr;
gap: 0;
}
.hero-copy {
padding-bottom: 30px;
}
.hero-copy > p {
max-width: 560px;
}
.coral-orbit {
right: 6%;
}
.mint-orbit {
left: 10%;
}
.board-stage {
min-height: 620px;
}
}
@media (max-width: 650px) {
.nav-wrap,
.hero,
.site-footer {
width: calc(100% - 36px);
}
.nav-wrap {
height: 74px;
}
.status {
padding: 7px 10px;
font-size: 9px;
}
.hero-copy {
padding: 65px 0 24px;
}
.hero-copy > p {
font-size: 15px;
}
h1 {
font-size: clamp(51px, 15vw, 68px);
}
.board-stage {
min-height: 500px;
}
.coral-orbit {
width: 340px;
height: 340px;
right: -28%;
top: 65px;
}
.mint-orbit {
width: 170px;
height: 170px;
left: -8%;
}
.board-shell {
width: min(390px, 92vw);
padding: 12px;
}
.piece {
font-size: clamp(24px, 9vw, 38px);
}
.site-footer {
flex-direction: column;
align-items: flex-start;
gap: 24px;
}
}
</style>
</head>
<body>
<header>
<nav class="nav-wrap" aria-label="Main navigation">
<a class="brand" href="/" aria-label="Inner Square Chess home">
<span class="brand-mark" aria-hidden="true">♞</span>
<span>INNERSQUARE</span>
</a>
<span class="status">Launching soon</span>
</nav>
</header>
<main id="main-content">
<section class="hero">
<div class="hero-copy">
<span class="eyebrow">Endgame training, coming soon</span>
<h1>Master the <em>endgame.</em></h1>
<p>
Short, focused endgame puzzles against tablebase-perfect defence.
Learn to see the winning move and make the endgame your strongest
phase.
</p>
<p class="note">
We&rsquo;re putting the finishing touches on the trainer.
Check back soon.
</p>
</div>
<div class="board-stage">
<div class="coral-orbit" aria-hidden="true"></div>
<div class="mint-orbit" aria-hidden="true"></div>
<div class="board-shell">
<div class="board-topline">
<div class="player">
<span class="player-piece" aria-hidden="true">♚</span>
<span>
<small>To move</small>
<strong>White</strong>
</span>
</div>
<span class="piece-count">3 pieces</span>
</div>
<div
class="chessboard"
role="img"
aria-label="Chess position: white king on d5, white rook on g3, black king on f7. White to move."
>
<div class="square light"><span class="rank">8</span></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square dark"><span class="rank">7</span></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square light"><span class="piece black-piece" aria-hidden="true">♚</span></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square light"><span class="rank">6</span></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square dark"><span class="rank">5</span></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square light"><span class="piece white-piece" aria-hidden="true">♔</span></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square light"><span class="rank">4</span></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square dark"><span class="rank">3</span></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"><span class="piece white-piece" aria-hidden="true">♖</span></div>
<div class="square light"></div>
<div class="square light"><span class="rank">2</span></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square light"></div>
<div class="square dark"></div>
<div class="square dark"><span class="rank">1</span><span class="file">a</span></div>
<div class="square light"><span class="file">b</span></div>
<div class="square dark"><span class="file">c</span></div>
<div class="square light"><span class="file">d</span></div>
<div class="square dark"><span class="file">e</span></div>
<div class="square light"><span class="file">f</span></div>
<div class="square dark"><span class="file">g</span></div>
<div class="square light"><span class="file">h</span></div>
</div>
<div class="board-caption">
<div>
<span>Sample position</span>
<strong>King and rook vs king</strong>
<small class="board-themes">Rook endgame</small>
</div>
</div>
</div>
</div>
</section>
</main>
<footer class="site-footer">
<div class="footer-brand">
<a class="brand" href="/" aria-label="Inner Square Chess home">
<span class="brand-mark" aria-hidden="true">♞</span>
<span>INNERSQUARE</span>
</a>
<p>Short, focused endgame training.</p>
</div>
<nav class="footer-links" aria-label="Legal">
<a href="/privacy">Privacy</a>
<a href="/terms-conditions">Terms</a>
<a href="/mentions-legales">Mentions légales</a>
</nav>
<small>&copy; 2026 Inner Square Chess</small>
</footer>
</body>
</html>
+299
View File
@@ -0,0 +1,299 @@
@font-face {
font-family: "DM Sans";
font-style: normal;
font-weight: 100 1000;
font-display: swap;
src: url("/fonts/dm-sans-variable.woff2") format("woff2");
}
@font-face {
font-family: "DM Serif Display";
font-style: normal;
font-weight: 400;
font-display: swap;
src: url("/fonts/dm-serif-display.woff2") format("woff2");
}
@font-face {
font-family: "DM Serif Display";
font-style: italic;
font-weight: 400;
font-display: swap;
src: url("/fonts/dm-serif-display-italic.woff2") format("woff2");
}
:root {
--ink: #17352d;
--ink-soft: #587068;
--paper: #f4f0e6;
--cream: #fffcf4;
--mint: #b9d7c9;
--coral: #ef755d;
--coral-dark: #d95d48;
--line: rgba(23, 53, 45, 0.15);
--color-canvas: var(--paper);
--color-canvas-raised: var(--cream);
--color-body: var(--ink);
--color-muted: var(--ink-soft);
--color-hairline: var(--line);
--color-deep: var(--ink);
--color-on-deep: var(--paper);
--color-coral: var(--coral);
--color-coral-text: #b8432c;
color-scheme: light;
}
*,
*::before,
*::after {
box-sizing: border-box;
}
html {
scroll-behavior: smooth;
}
body {
min-width: 320px;
min-height: 100vh;
min-height: 100dvh;
margin: 0;
display: flex;
flex-direction: column;
background: var(--color-canvas);
color: var(--color-body);
font-family: "DM Sans", system-ui, -apple-system, "Segoe UI", sans-serif;
-webkit-font-smoothing: antialiased;
}
a {
color: inherit;
text-decoration: none;
}
:focus-visible {
outline: 2px solid var(--color-coral-text);
outline-offset: 2px;
}
main {
flex: 1 0 auto;
overflow: hidden;
}
.nav-wrap {
width: min(1180px, calc(100% - 48px));
height: 92px;
margin: 0 auto;
display: flex;
align-items: center;
justify-content: space-between;
border-bottom: 1px solid var(--color-hairline);
}
.brand {
display: inline-flex;
align-items: center;
gap: 10px;
font-size: 16px;
font-weight: 700;
letter-spacing: 0.18em;
}
.brand-mark {
display: grid;
place-items: center;
width: 35px;
height: 35px;
border-radius: 50%;
background: var(--color-deep);
color: var(--color-on-deep);
font-size: 21px;
letter-spacing: 0;
}
.status {
display: inline-flex;
align-items: center;
gap: 8px;
padding: 8px 14px;
border: 1px solid var(--color-hairline);
border-radius: 999px;
color: var(--color-muted);
font-size: 11px;
font-weight: 700;
letter-spacing: 0.1em;
text-transform: uppercase;
white-space: nowrap;
}
.status::before {
content: "";
width: 7px;
height: 7px;
border-radius: 50%;
background: var(--color-coral);
}
.legal {
width: min(760px, calc(100% - 48px));
margin: 0 auto;
padding: 84px 0 120px;
}
.legal h1 {
max-width: none;
margin: 0;
font-family: "DM Serif Display", Georgia, serif;
font-size: clamp(42px, 5vw, 62px);
font-weight: 400;
letter-spacing: -0.035em;
line-height: 1.02;
}
.legal-meta {
margin-top: 14px;
color: var(--color-muted);
font-size: 13px;
}
.legal h2 {
margin: 42px 0 12px;
font-family: "DM Serif Display", Georgia, serif;
font-size: 26px;
font-weight: 400;
letter-spacing: -0.02em;
line-height: 1.15;
}
.legal p,
.legal li {
color: var(--color-muted);
font-size: 15px;
line-height: 1.75;
}
.legal p + p {
margin-top: 12px;
}
.legal ul {
display: grid;
gap: 8px;
margin: 12px 0 0 20px;
list-style: disc;
}
.legal strong {
color: var(--color-body);
font-weight: 600;
}
.legal a {
color: var(--color-coral-text);
text-decoration: underline;
text-underline-offset: 2px;
}
.legal a:hover {
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;
padding: 44px 0;
display: flex;
align-items: center;
justify-content: space-between;
gap: 30px;
border-top: 1px solid var(--color-hairline);
}
.footer-brand {
display: flex;
flex-direction: column;
gap: 12px;
}
.footer-brand p {
margin: 0;
color: var(--color-muted);
font-size: 13px;
}
.site-footer > small {
color: var(--color-muted);
font-size: 11px;
}
.footer-links {
display: flex;
gap: 18px;
color: var(--color-muted);
font-size: 12px;
}
.footer-links a:hover {
color: var(--color-body);
}
@media (max-width: 650px) {
.nav-wrap,
.site-footer {
width: calc(100% - 36px);
}
.nav-wrap {
height: 74px;
}
.status {
padding: 7px 10px;
font-size: 9px;
}
.legal {
width: calc(100% - 36px);
padding: 56px 0 84px;
}
.legal h1 {
font-size: clamp(34px, 11vw, 44px);
}
.legal h2 {
margin-top: 34px;
font-size: 23px;
}
.site-footer {
flex-direction: column;
align-items: flex-start;
gap: 24px;
}
}
+108
View File
@@ -0,0 +1,108 @@
<!doctype html>
<html lang="fr">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Mentions légales — Inner Square Chess</title>
<meta
name="description"
content="Éditeur, hébergeur et informations légales du site Inner Square Chess."
/>
<meta name="robots" content="noindex, nofollow" />
<meta name="theme-color" content="#f4f0e6" />
<meta property="og:type" content="website" />
<meta property="og:site_name" content="Inner Square Chess" />
<meta property="og:title" content="Mentions légales — Inner Square Chess" />
<meta
property="og:description"
content="Éditeur, hébergeur et informations légales du site Inner Square Chess."
/>
<meta name="twitter:card" content="summary" />
<link rel="icon" href="/favicon.ico" />
<link rel="stylesheet" href="/legal.css" />
</head>
<body>
<header>
<nav class="nav-wrap" aria-label="Main navigation">
<a class="brand" href="/" aria-label="Inner Square Chess home">
<span class="brand-mark" aria-hidden="true">♞</span>
<span>INNERSQUARE</span>
</a>
<span class="status">Launching soon</span>
</nav>
</header>
<main id="main-content">
<article class="legal" lang="fr">
<h1>Mentions légales</h1>
<p class="legal-meta">Dernière mise à jour : 10 novembre 2026</p>
<p>
Ces mentions sont publiées en application de l'article 6-III de la loi
n° 2004-575 du 21 juin 2004 pour la confiance dans l'économie numérique.
</p>
<h2>Éditeur du site</h2>
<p>
Le site <a href="/">innersquare.app</a>, édité sous le nom commercial
«&nbsp;Inner Square Chess&nbsp;», est édité par&nbsp;:
</p>
<ul>
<li><strong>Owen REES</strong>, entrepreneur individuel (EI)</li>
<li>Adresse&nbsp;: [adresse à compléter]</li>
<li>SIRET&nbsp;: 929 553 774 00019</li>
<li>Téléphone&nbsp;: <a href="tel:+33683019513">+33 6 83 01 95 13</a></li>
<li>
Courriel&nbsp;:
<a href="mailto:support@innersquare.app">support@innersquare.app</a>
</li>
<li>TVA non applicable, article 293 B du Code général des impôts.</li>
</ul>
<h2>Directeur de la publication</h2>
<p>Owen REES.</p>
<h2>Hébergeur</h2>
<p>
Hetzner Online GmbH<br />
Industriestraße 25<br />
91710 Gunzenhausen<br />
Allemagne<br />
Téléphone&nbsp;: <a href="tel:+4998315050">+49 9831 505-0</a>
</p>
<h2>Propriété intellectuelle</h2>
<p>
Les contenus du site — textes, interface, code, éléments graphiques, ainsi
que les positions et solutions d'échecs — sont protégés par le droit
d'auteur et restent la propriété de l'éditeur ou de ses concédants. Toute
reproduction ou réutilisation non autorisée est interdite.
</p>
<h2>Données personnelles</h2>
<p>
Les données traitées, les finalités, les durées de conservation et vos
droits sont décrits dans la
<a href="/privacy">politique de confidentialité</a>, disponible en anglais.
</p>
</article>
</main>
<footer class="site-footer">
<div class="footer-brand">
<a class="brand" href="/" aria-label="Inner Square Chess home">
<span class="brand-mark" aria-hidden="true">♞</span>
<span>INNERSQUARE</span>
</a>
<p>Short, focused endgame training.</p>
</div>
<nav class="footer-links" aria-label="Legal">
<a href="/privacy">Privacy</a>
<a href="/terms-conditions">Terms</a>
<a href="/mentions-legales">Mentions légales</a>
</nav>
<small>&copy; 2026 Inner Square Chess</small>
</footer>
</body>
</html>
+334
View File
@@ -0,0 +1,334 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Privacy Policy — Inner Square Chess</title>
<meta
name="description"
content="How Inner Square Chess collects, uses, and protects your personal information."
/>
<meta name="robots" content="noindex, nofollow" />
<meta name="theme-color" content="#f4f0e6" />
<meta property="og:type" content="website" />
<meta property="og:site_name" content="Inner Square Chess" />
<meta property="og:title" content="Privacy Policy — Inner Square Chess" />
<meta
property="og:description"
content="How Inner Square Chess collects, uses, and protects your personal information."
/>
<meta name="twitter:card" content="summary" />
<link rel="icon" href="/favicon.ico" />
<link rel="stylesheet" href="/legal.css" />
</head>
<body>
<header>
<nav class="nav-wrap" aria-label="Main navigation">
<a class="brand" href="/" aria-label="Inner Square Chess home">
<span class="brand-mark" aria-hidden="true">♞</span>
<span>INNERSQUARE</span>
</a>
<span class="status">Launching soon</span>
</nav>
</header>
<main id="main-content">
<article class="legal">
<h1>Privacy Policy</h1>
<p class="legal-meta">Last updated: 10 November 2026</p>
<p>
Inner Square Chess is an endgame training site. This policy explains what
information we collect when you use it, why we collect it, and the choices
you have. It covers the website and every page under it, including the
guest trainer.
</p>
<h2>Data controller</h2>
<p>
The controller responsible for your personal information is Owen REES,
an entrepreneur individuel (EI) established in France, trading as
Inner Square Chess. Our business register number (SIRET) is
929&nbsp;553&nbsp;774&nbsp;00019. You can contact us about anything in
this policy, or about your data, at
<a href="mailto:support@innersquare.app">support@innersquare.app</a>
or <a href="tel:+33683019513">+33 6 83 01 95 13</a>.
</p>
<h2>What we collect</h2>
<ul>
<li>
<strong>Account details.</strong>
If you register, we store your username, email address, and a hashed
password. We never store passwords in plain text.
</li>
<li>
<strong>Training activity.</strong>
We record the puzzles you attempt and whether you solved them, so we can
show your progress and keep the daily puzzle meaningful.
</li>
<li>
<strong>Mailing list email.</strong>
If you join the mailing list — using the form on the home page or the
checkbox when registering — we store your email address and where you
signed up, so we can send you occasional updates. You can ask to be
removed at any time.
</li>
<li>
<strong>Technical data.</strong>
We do not keep our own access logs. The companies that host the site
and run our content delivery network keep short-lived request logs
(IP address, browser, timestamps) for security, abuse prevention, and
troubleshooting, under their own retention policies.
</li>
<li>
<strong>Usage data.</strong>
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 addresses shortened before storage, and to respect
Do Not Track. We do not use user IDs, track signed-in account pages,
or share this data with third parties.
</li>
<li>
<strong>Messages you send us.</strong>
If you contact us, we keep the message and our reply for as long as
needed to help you.
</li>
</ul>
<h2>Cookies and local storage</h2>
<p>
We use a small number of cookies and local storage entries that are
required for the site to work:
</p>
<ul>
<li>a session cookie that keeps you signed in;</li>
<li>a CSRF token that protects forms from cross-site requests;</li>
<li>
a security cookie that our content delivery network, Cloudflare, may
set when it checks that a request is not automated abuse;
</li>
<li>a colour-mode preference stored in your browser.</li>
<li>
an analytics opt-out preference stored in your browser's local
storage, if you choose to opt out.
</li>
</ul>
<p>
We do not use advertising cookies, analytics cookies, or cross-site
tracking. The only cookie not set by this site is Cloudflare's security
check described above; 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.
</p>
<h2>Analytics</h2>
<p>
We use a self-hosted Matomo instance at
<a href="https://analytics.owenrees.eu/">analytics.owenrees.eu</a>
to understand aggregate use of the public site and guest trainer. It is
configured without cookies, with IP addresses shortened before storage,
and to respect Do Not Track. We do not use user IDs, track signed-in
account pages, or share this data with third parties.
</p>
<p>
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
<a href="mailto:support@innersquare.app">support@innersquare.app</a>.
</p>
<p id="analytics-status">Analytics is currently on in this browser.</p>
<div class="analytics-buttons">
<button id="analytics-opt-out" type="button">Opt out of analytics</button>
<button id="analytics-opt-in" type="button" hidden>Opt back in</button>
</div>
<h2>How we use your information</h2>
<ul>
<li>To create and secure your account and sign you in.</li>
<li>To run the trainer and remember your progress.</li>
<li>To send service emails, such as confirmation and password reset links.</li>
<li>To send occasional endgame tips and site news, if you opted in.</li>
<li>
To understand aggregate use of the public site and guest trainer, and
improve the service.
</li>
<li>To keep the site available, prevent abuse, and fix faults.</li>
<li>To respond when you ask for help.</li>
</ul>
<p>
We rely on our contract with you to provide the service, our legitimate
interests in keeping it secure and improving it, and your consent where we
ask for it. You can withdraw consent at any time.
</p>
<h2>Guest puzzle limit</h2>
<p>
Visitors who use the guest trainer without an account get a limited number
of free puzzles per UTC day. To enforce that limit and prevent abuse, we
identify each visitor by a keyed hash (HMAC-SHA256) of their IP address.
The limiter itself never stores, logs, or shares the raw address.
</p>
<p>
The hash exists only in the memory of the server that handled your request.
It is tied to the current UTC day, stops being usable at 00:00 UTC, and is
deleted by a periodic sweep shortly afterwards; it is also discarded when
the server restarts. It is never written to a database, a log, or a
backup, and no cookie or other client-side storage is involved. Signed-in
accounts are not metered this way.
</p>
<p>
We process this hash on the basis of our legitimate interests
(Article 6(1)(f) GDPR) in keeping the service available and preventing
abuse of the free tier. We do not share it with anyone. You have the right
to object to this processing; to do so, contact us using the address below.
</p>
<h2 id="hosting-and-infrastructure">Hosting and infrastructure</h2>
<p>
The site runs on a virtual private server operated for us by Hetzner
inside the European Union. Our database runs on the same server, our
transactional email is sent through Amazon SES in the EU, and our
self-hosted Matomo analytics runs on infrastructure we control in the
EU.
</p>
<p>
We also use Cloudflare as our content delivery network and security
proxy. Because Cloudflare sits between your browser and our server, it
processes your IP address, the requested URL, and request headers.
Cloudflare is a US company, so that request data may be transferred
outside the UK and EEA. The transfer relies on the EU–US Data Privacy
Framework and standard contractual clauses. Cloudflare and Hetzner each
keep their own logs under their own retention policies; we do not
receive or keep them.
</p>
<p>
These providers act as our processors under data protection law. We
share with them only what they need to run the service, and we remain
responsible for how your information is handled.
</p>
<h2>Sharing</h2>
<p>
We do not sell your personal information. We share it only with the
providers described under
<a href="#hosting-and-infrastructure">hosting and infrastructure</a>
— our hosting, content delivery, database, and email delivery providers
— and only as far as they need it to perform that work. 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.
</p>
<h2>Retention</h2>
<p>
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. We retain raw analytics data for up to 180 days.
</p>
<p>
Two exceptions are worth naming. If you unsubscribe from the mailing
list, or ask us not to email you, we keep your address on a suppression
list so that we do not contact you again; we hold only what is needed to
recognise the address. We also keep database backups for disaster
recovery, stored off the primary server, so a deleted account may remain
in a backup for some time after deletion. We do not use backups to
restore individual accounts, and we delete them once they are no longer
needed.
</p>
<h2>Your rights</h2>
<p>
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. 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.
</p>
<h2>Changes</h2>
<p>
We may update this policy as the service changes. When we do, we will
change the date at the top of this page and, for significant changes,
notify signed-in users by email or on the site.
</p>
<h2>Contact</h2>
<p>
Questions about this policy or your data can be sent to
<a href="mailto:support@innersquare.app">support@innersquare.app</a>.
</p>
</article>
</main>
<footer class="site-footer">
<div class="footer-brand">
<a class="brand" href="/" aria-label="Inner Square Chess home">
<span class="brand-mark" aria-hidden="true">♞</span>
<span>INNERSQUARE</span>
</a>
<p>Short, focused endgame training.</p>
</div>
<nav class="footer-links" aria-label="Legal">
<a href="/privacy">Privacy</a>
<a href="/terms-conditions">Terms</a>
<a href="/mentions-legales">Mentions légales</a>
</nav>
<small>&copy; 2026 Inner Square Chess</small>
</footer>
<script>
(function () {
var key = "matomo_optout";
var optOut = document.getElementById("analytics-opt-out");
var optIn = document.getElementById("analytics-opt-in");
var status = document.getElementById("analytics-status");
function optedOut() {
try {
return localStorage.getItem(key) === "1";
} catch (error) {
return true;
}
}
function update() {
var off = optedOut();
if (optOut) optOut.hidden = off;
if (optIn) optIn.hidden = !off;
if (status) {
status.textContent = off
? "Analytics is currently off in this browser."
: "Analytics is currently on in this browser.";
}
}
if (optOut) {
optOut.addEventListener("click", function () {
try {
localStorage.setItem(key, "1");
} catch (error) {}
update();
});
}
if (optIn) {
optIn.addEventListener("click", function () {
try {
localStorage.removeItem(key);
} catch (error) {}
update();
});
}
update();
})();
</script>
</body>
</html>
+181
View File
@@ -0,0 +1,181 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Terms &amp; Conditions — Inner Square Chess</title>
<meta
name="description"
content="The terms that apply when you use Inner Square Chess."
/>
<meta name="robots" content="noindex, nofollow" />
<meta name="theme-color" content="#f4f0e6" />
<meta property="og:type" content="website" />
<meta property="og:site_name" content="Inner Square Chess" />
<meta property="og:title" content="Terms &amp; Conditions — Inner Square Chess" />
<meta
property="og:description"
content="The terms that apply when you use Inner Square Chess."
/>
<meta name="twitter:card" content="summary" />
<link rel="icon" href="/favicon.ico" />
<link rel="stylesheet" href="/legal.css" />
</head>
<body>
<header>
<nav class="nav-wrap" aria-label="Main navigation">
<a class="brand" href="/" aria-label="Inner Square Chess home">
<span class="brand-mark" aria-hidden="true">♞</span>
<span>INNERSQUARE</span>
</a>
<span class="status">Launching soon</span>
</nav>
</header>
<main id="main-content">
<article class="legal">
<h1>Terms &amp; Conditions</h1>
<p class="legal-meta">Last updated: 10 November 2026</p>
<p>
These terms govern your use of Inner Square Chess. By browsing the site,
using the guest trainer, or creating an account, you agree to them. If you
do not agree, please do not use the service.
</p>
<p>
Inner Square Chess is operated by Owen REES, entrepreneur individuel (EI),
established in France, business register number (SIRET)
929&nbsp;553&nbsp;774&nbsp;00019. Full publisher details are on the
<a href="/mentions-legales">mentions légales</a> page.
</p>
<h2>The service</h2>
<p>
Inner Square Chess provides short endgame puzzles and training tools. Some
features are available without an account; others, such as saved progress
and the full puzzle list, require you to register. We may add, change, or
remove features over time.
</p>
<p>
The guest trainer is limited to a fixed number of puzzles per UTC day,
which we may change. The limit is enforced as described in our
<a href="/privacy">Privacy Policy</a>.
</p>
<h2>Accounts</h2>
<ul>
<li>You must be at least 13 years old to create an account.</li>
<li>
If you are under 16 and in the UK or EU, you may only use an account
with the consent of a parent or guardian.
</li>
<li>Give accurate information and keep it up to date.</li>
<li>Keep your password private and tell us promptly about unauthorised use.</li>
<li>You are responsible for activity that happens under your account.</li>
<li>Do not share, sell, or transfer your account to someone else.</li>
</ul>
<h2>Acceptable use</h2>
<p>You agree not to:</p>
<ul>
<li>break the law or infringe anyone else's rights;</li>
<li>interfere with the site, its servers, or other users;</li>
<li>attempt to gain access to accounts or data that are not yours;</li>
<li>scrape, crawl, or bulk-download the site without our permission;</li>
<li>copy, resell, or redistribute the service or its content;</li>
<li>use the service to send spam or malicious code.</li>
</ul>
<h2>Our content and your licence</h2>
<p>
The site, its design, text, and software are owned by Inner Square Chess or
its licensors and are protected by copyright and other laws. We grant you a
personal, non-exclusive, non-transferable licence to use the service for
your own training. You may not reproduce, modify, distribute, or create
derivative works from our content without written permission.
</p>
<p>
Chess positions and puzzle data are drawn from public sources and
tablebase material. You may use the training output for your own study,
but not to build a competing product.
</p>
<h2>Your data</h2>
<p>
You keep ownership of the information you provide. You give us permission
to store and use it as described in our <a href="/privacy">Privacy Policy</a>
so that we can run the service.
</p>
<h2>Paid plans</h2>
<p>
Some features may be offered as part of a paid plan. Prices, billing
periods, and cancellation terms will be shown before you purchase. Unless
the law requires otherwise, payments are non-refundable once a billing
period has started. We may change prices with reasonable notice.
</p>
<h2>Availability and changes</h2>
<p>
We aim to keep the site available, but we do not guarantee uninterrupted
access. Maintenance, faults, or circumstances outside our control may
interrupt it. We may suspend or discontinue the service, in whole or in
part, with reasonable notice where practical.
</p>
<h2>Disclaimer</h2>
<p>
Inner Square Chess is an educational tool. We do not promise that using it
will improve your rating or results, and puzzle solutions are provided for
training purposes only. The service is provided "as is" to the extent
permitted by law.
</p>
<h2>Limitation of liability</h2>
<p>
To the extent permitted by law, Inner Square Chess is not liable for
indirect or consequential losses, loss of data, or loss of profits arising
from your use of the service. Nothing in these terms limits liability that
cannot be limited by law, including for death, personal injury, or fraud.
</p>
<h2>Termination</h2>
<p>
You may stop using the service and delete your account at any time. We may
suspend or close an account that breaches these terms, that we reasonably
believe is being misused, or where we are required to do so by law.
</p>
<h2>Governing law</h2>
<p>
These terms are governed by the laws of France. Any dispute will be handled
by the courts of France, unless the law where you live gives you the right
to bring it elsewhere.
</p>
<h2>Contact</h2>
<p>
Questions about these terms can be sent to
<a href="mailto:support@innersquare.app">support@innersquare.app</a>.
</p>
</article>
</main>
<footer class="site-footer">
<div class="footer-brand">
<a class="brand" href="/" aria-label="Inner Square Chess home">
<span class="brand-mark" aria-hidden="true">♞</span>
<span>INNERSQUARE</span>
</a>
<p>Short, focused endgame training.</p>
</div>
<nav class="footer-links" aria-label="Legal">
<a href="/privacy">Privacy</a>
<a href="/terms-conditions">Terms</a>
<a href="/mentions-legales">Mentions légales</a>
</nav>
<small>&copy; 2026 Inner Square Chess</small>
</footer>
</body>
</html>
+115
View File
@@ -0,0 +1,115 @@
#!/usr/bin/env bash
#
# Refresh Caddy's Cloudflare origin allowlist from Cloudflare's published
# ranges. Called by chesstrainer-cloudflare-ranges.timer.
#
# The generated file is imported by /etc/caddy/Caddyfile:
#
# @cloudflare {
# import cloudflare-ranges.caddy
# }
#
# The script validates the candidate Caddyfile before reloading Caddy. If the
# download or validation fails, the previous ranges stay in place.
set -euo pipefail
CADDYFILE="${CADDYFILE:-/etc/caddy/Caddyfile}"
RANGES_FILE="${RANGES_FILE:-/etc/caddy/cloudflare-ranges.caddy}"
CADDY_BIN="${CADDY_BIN:-caddy}"
RELOAD_CMD="${RELOAD_CMD:-systemctl reload caddy}"
LOCK_FILE="${LOCK_FILE:-/run/lock/chesstrainer-cloudflare-ranges.lock}"
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
exec 9>"$LOCK_FILE"
if ! flock -n 9; then
echo "another Cloudflare range update is already running" >&2
exit 0
fi
fetch() {
local url="$1"
local output="$2"
curl --fail --silent --show-error --location \
--proto '=https' \
--retry 3 --retry-delay 2 --connect-timeout 10 \
"$url" --output "$output"
}
validate_download() {
local file="$1"
[[ -s "$file" ]] || return 1
# One CIDR per line. Caddy performs the real validation; this prevents
# obviously malformed or injected content from being written.
if grep -Evq '^[0-9A-Fa-f:.]+/[0-9]{1,3}$' "$file"; then
return 1
fi
}
fetch "https://www.cloudflare.com/ips-v4" "$tmpdir/ips-v4"
fetch "https://www.cloudflare.com/ips-v6" "$tmpdir/ips-v6"
validate_download "$tmpdir/ips-v4"
validate_download "$tmpdir/ips-v6"
ranges="$(awk 'NF { printf "%s ", $0 }' "$tmpdir/ips-v4" "$tmpdir/ips-v6" | sed -e 's/[[:space:]]*$//')"
if [[ -z "$ranges" ]]; then
echo "Cloudflare returned an empty CIDR list" >&2
exit 1
fi
candidate="$tmpdir/cloudflare-ranges.caddy"
{
echo "# Generated by deploy/update-cloudflare-ranges.sh."
echo "# Source: https://www.cloudflare.com/ips-v4 and /ips-v6"
echo "remote_ip $ranges"
} >"$candidate"
if cmp -s "$candidate" "$RANGES_FILE"; then
echo "Cloudflare ranges are unchanged"
exit 0
fi
install -d -m 0755 "$(dirname "$RANGES_FILE")"
backup="$tmpdir/previous-ranges.caddy"
if [[ -e "$RANGES_FILE" ]]; then
cp -a "$RANGES_FILE" "$backup"
fi
install -m 0644 "$candidate" "$RANGES_FILE"
if ! "$CADDY_BIN" validate --config "$CADDYFILE" --adapter caddyfile; then
echo "Caddy rejected the new Cloudflare ranges; restoring the previous file" >&2
if [[ -e "$backup" ]]; then
install -m 0644 "$backup" "$RANGES_FILE"
else
rm -f "$RANGES_FILE"
fi
exit 1
fi
read -r -a reload_command <<<"$RELOAD_CMD"
if ! "${reload_command[@]}"; then
echo "Caddy reload failed; restoring the previous ranges" >&2
if [[ -e "$backup" ]]; then
install -m 0644 "$backup" "$RANGES_FILE"
else
rm -f "$RANGES_FILE"
fi
exit 1
fi
echo "Cloudflare ranges updated and Caddy reloaded"
+190
View File
@@ -0,0 +1,190 @@
#!/usr/bin/env bash
#
# Restore the newest (or a named) archive into a throwaway Postgres container
# and prove that the dump, the roles and the row counts all came back.
#
# backup-drill # newest archive in DEST
# backup-drill 20261111T031500Z.tar.age
#
# Runs on the workstation. The production database is never contacted: the
# container is created and destroyed by this script. Results are appended to
# $DRILL_LOG (default $DEST/drills.log).
#
# Configuration: same file as backup-pull,
# ~/.config/chesstrainer/backup-pull.env.
set -euo pipefail
umask 077
CONFIG="${PULL_ENV_FILE:-${XDG_CONFIG_HOME:-$HOME/.config}/chesstrainer/backup-pull.env}"
if [[ -r "$CONFIG" ]]; then
# shellcheck disable=SC1090
source "$CONFIG"
fi
DEST="${DEST:-$HOME/chesstrainer-backups}"
AGE_KEY="${AGE_KEY:-${XDG_CONFIG_HOME:-$HOME/.config}/chesstrainer/age.key}"
EXPECTED_ROLES="${EXPECTED_ROLES:-chesstrainer chesstrainer_ro}"
DRILL_IMAGE="${DRILL_IMAGE:-postgres:18.6}"
DRILL_DB="${DRILL_DB:-chesstrainer_restore}"
DRILL_LOG="${DRILL_LOG:-$DEST/drills.log}"
DRILL_CONTAINER="${DRILL_CONTAINER:-chesstrainer-drill-$$}"
START_SECONDS=$SECONDS
FAILURE=""
TMPDIR_DRILL=""
log_event() {
local event="$1"
local extra="${2:-}"
printf '{"timestamp":"%s","event":"%s"%s}\n' \
"$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$event" "$extra"
}
record() {
local line="$1"
printf '%s\n' "$line"
printf '%s\n' "$line" >>"$DRILL_LOG"
}
fail() {
FAILURE="$*"
exit 1
}
cleanup() {
local status=$?
docker rm -f "$DRILL_CONTAINER" >/dev/null 2>&1 || true
if [[ -n "$TMPDIR_DRILL" ]]; then
rm -rf "$TMPDIR_DRILL"
fi
if ((status != 0)); then
if [[ -d "$DEST" ]]; then
record "$(log_event drill.failed ",\"reason\":\"${FAILURE:-exit $status}\"")"
else
log_event drill.failed ",\"reason\":\"${FAILURE:-exit $status}\""
fi
fi
exit "$status"
}
trap cleanup EXIT
trap 'exit 143' TERM INT
[[ -d "$DEST" ]] || fail "archive directory does not exist: $DEST"
[[ -r "$AGE_KEY" ]] || fail "age identity not readable: $AGE_KEY"
for cmd in docker age tar sha256sum; do
command -v "$cmd" >/dev/null 2>&1 || fail "missing command: $cmd"
done
if [[ $# -gt 0 ]]; then
case "$1" in
/*) archive="$1" ;;
*) archive="$DEST/$1" ;;
esac
else
archive="$(find "$DEST" -maxdepth 1 -type f -name '*.tar.age' -printf '%p\n' | sort | tail -n 1)"
[[ -n "$archive" ]] || fail "no archives in $DEST"
fi
[[ -f "$archive" ]] || fail "archive not found: $archive"
name="${archive##*/}"
[[ "$name" =~ ^[0-9]{8}T[0-9]{6}Z(-[a-z0-9]+)?\.tar\.age$ ]] ||
fail "unexpected archive name: $name"
prefix="${name%%.*}"
TMPDIR_DRILL="$(mktemp -d "${TMPDIR:-/tmp}/chesstrainer-drill.XXXXXX")"
echo "backup-drill: decrypting $name" >&2
age --decrypt --identity "$AGE_KEY" --output "$TMPDIR_DRILL/$prefix.tar" "$archive" ||
fail "could not decrypt $name"
tar -xf "$TMPDIR_DRILL/$prefix.tar" -C "$TMPDIR_DRILL" ||
fail "archive does not contain a readable tar file"
(
cd "$TMPDIR_DRILL"
sha256sum --check --strict --quiet "$prefix.sha256"
) || fail "checksum verification failed for $name"
echo "backup-drill: starting $DRILL_IMAGE" >&2
docker image inspect "$DRILL_IMAGE" >/dev/null 2>&1 ||
docker pull "$DRILL_IMAGE" >/dev/null ||
fail "could not pull $DRILL_IMAGE"
docker run --rm --detach \
--name "$DRILL_CONTAINER" \
--env POSTGRES_USER=chesstrainer \
--env POSTGRES_PASSWORD=drill \
--env POSTGRES_HOST_AUTH_METHOD=trust \
"$DRILL_IMAGE" >/dev/null || fail "could not start the drill container"
ready=0
for _ in $(seq 1 60); do
if docker exec "$DRILL_CONTAINER" pg_isready -U chesstrainer -d postgres >/dev/null 2>&1; then
ready=1
break
fi
sleep 1
done
((ready == 1)) || fail "postgres did not become ready"
# Recreating the cluster roles is half of disaster recovery. The scratch
# cluster uses the same superuser name as production (`chesstrainer`), because
# the globals dump ends with grants issued "GRANTED BY chesstrainer". The dump
# always repeats the cluster's own superuser role, so "already exists" is
# expected; anything else is a real failure.
echo "backup-drill: applying globals" >&2
docker exec -i "$DRILL_CONTAINER" psql -U chesstrainer -d postgres \
-q -v ON_ERROR_STOP=0 -f - \
<"$TMPDIR_DRILL/$prefix.globals.sql" >/dev/null 2>"$TMPDIR_DRILL/globals.err" ||
fail "applying the globals dump failed"
globals_errors="$(grep -v 'already exists' "$TMPDIR_DRILL/globals.err" | sed '/^$/d' || true)"
if [[ -n "$globals_errors" ]]; then
fail "globals restore reported errors: $(printf '%s' "$globals_errors" | head -n 1)"
fi
for role in $EXPECTED_ROLES; do
found="$(docker exec "$DRILL_CONTAINER" psql -U chesstrainer -d postgres -Atc \
"select 1 from pg_roles where rolname = '$role'")"
[[ "$found" == "1" ]] || fail "globals did not recreate role $role"
done
owner="${EXPECTED_ROLES%% *}"
docker exec "$DRILL_CONTAINER" psql -U chesstrainer -d postgres \
-q -v ON_ERROR_STOP=1 -c "create database $DRILL_DB owner $owner" ||
fail "could not create $DRILL_DB"
echo "backup-drill: restoring into $DRILL_DB" >&2
docker exec -i "$DRILL_CONTAINER" pg_restore -U chesstrainer -d "$DRILL_DB" \
--single-transaction --exit-on-error <"$TMPDIR_DRILL/$prefix.dump" ||
fail "pg_restore failed"
restored_counts=""
for table in users endgames attempts; do
expected="$(awk -F= -v key="$table" '$1 == key { print $2 }' "$TMPDIR_DRILL/$prefix.counts")"
[[ "$expected" =~ ^[0-9]+$ ]] || fail "counts file has no value for $table"
actual="$(docker exec "$DRILL_CONTAINER" psql -U chesstrainer -d "$DRILL_DB" -Atc \
"select count(*) from $table")"
[[ "$actual" =~ ^[0-9]+$ ]] || fail "could not count $table"
if ((actual < expected)); then
fail "restored $table=$actual is below the recorded $expected"
fi
echo "backup-drill: $table restored=$actual recorded=$expected drift=$((actual - expected))" >&2
restored_counts+="${restored_counts:+,}$table=$actual"
done
record "$(log_event drill.completed ",\"archive\":\"$name\",\"result\":\"pass\",\"counts\":\"$restored_counts\",\"duration_s\":$((SECONDS - START_SECONDS))")"
+248
View File
@@ -0,0 +1,248 @@
#!/usr/bin/env bash
#
# Pull the encrypted database archives from the VPS, verify them end to end,
# and apply the 7 daily / 4 weekly / 6 monthly retention policy.
#
# Runs on the workstation, never on the server. Install as
# ~/.local/bin/chesstrainer-backup-pull and enable
# chesstrainer-backup-pull.timer as a user unit.
#
# Configuration: ~/.config/chesstrainer/backup-pull.env (0600). See
# deploy/README.md §Backups.
set -euo pipefail
umask 077
CONFIG="${PULL_ENV_FILE:-${XDG_CONFIG_HOME:-$HOME/.config}/chesstrainer/backup-pull.env}"
if [[ -r "$CONFIG" ]]; then
# shellcheck disable=SC1090
source "$CONFIG"
fi
VPS_HOST="${VPS_HOST:-}"
REMOTE_DIR="${REMOTE_DIR:-/var/backups/chesstrainer/offsite}"
DEST="${DEST:-$HOME/chesstrainer-backups}"
AGE_KEY="${AGE_KEY:-${XDG_CONFIG_HOME:-$HOME/.config}/chesstrainer/age.key}"
MAX_STALENESS_HOURS="${MAX_STALENESS_HOURS:-48}"
KEEP_DAILY_DAYS="${KEEP_DAILY_DAYS:-7}"
KEEP_WEEKLY_WEEKS="${KEEP_WEEKLY_WEEKS:-4}"
KEEP_MONTHLY_MONTHS="${KEEP_MONTHLY_MONTHS:-6}"
PULL_HEALTHCHECK_URL="${PULL_HEALTHCHECK_URL:-}"
SSH_OPTIONS="${SSH_OPTIONS:--o BatchMode=yes -o ConnectTimeout=10 -o ServerAliveInterval=15}"
RSYNC_ATTEMPTS="${RSYNC_ATTEMPTS:-3}"
START_SECONDS=$SECONDS
FAILURE=""
VERIFIED=0
log_event() {
local event="$1"
local extra="${2:-}"
printf '{"timestamp":"%s","event":"%s"%s}\n' \
"$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$event" "$extra"
}
heartbeat() {
local outcome="$1"
[[ -n "$PULL_HEALTHCHECK_URL" ]] || return 0
local url="${PULL_HEALTHCHECK_URL%/}"
[[ "$outcome" == "fail" ]] && url="$url/fail"
if ! curl --fail --silent --show-error \
--max-time 10 --retry 2 --retry-delay 2 \
--output /dev/null "$url"; then
echo "backup-pull: heartbeat ping failed (run result is unaffected)" >&2
fi
}
fail() {
FAILURE="$*"
exit 1
}
cleanup() {
local status=$?
if [[ -d "$DEST" ]]; then
find "$DEST" -maxdepth 1 -name '.verify.*' -type d -exec rm -rf {} + 2>/dev/null || true
fi
if ((status != 0)); then
log_event pull.failed ",\"reason\":\"${FAILURE:-exit $status}\""
heartbeat fail
fi
exit "$status"
}
trap cleanup EXIT
trap 'exit 143' TERM INT
[[ -n "$VPS_HOST" ]] || fail "VPS_HOST is not set"
[[ -r "$AGE_KEY" ]] || fail "age identity not readable: $AGE_KEY"
[[ "$MAX_STALENESS_HOURS" =~ ^[0-9]+$ ]] || fail "MAX_STALENESS_HOURS must be an integer"
[[ "$KEEP_DAILY_DAYS" =~ ^[0-9]+$ ]] || fail "KEEP_DAILY_DAYS must be an integer"
[[ "$KEEP_WEEKLY_WEEKS" =~ ^[0-9]+$ ]] || fail "KEEP_WEEKLY_WEEKS must be an integer"
[[ "$KEEP_MONTHLY_MONTHS" =~ ^[0-9]+$ ]] || fail "KEEP_MONTHLY_MONTHS must be an integer"
[[ "$RSYNC_ATTEMPTS" =~ ^[0-9]+$ ]] || fail "RSYNC_ATTEMPTS must be an integer"
for cmd in rsync ssh age tar sha256sum curl flock; do
command -v "$cmd" >/dev/null 2>&1 || fail "missing command: $cmd"
done
# Never create DEST on the root filesystem when the backup disk is unmounted.
[[ -d "$(dirname "$DEST")" ]] ||
fail "parent directory of $DEST does not exist (is the backup disk mounted?)"
install -d -m 0700 "$DEST"
install -d -m 0700 "$DEST/.verified"
exec 9>"$DEST/.pull.lock"
if ! flock -n 9; then
# A manual run overlapping the timer is not an error; the other run reports.
log_event pull.skipped ',"reason":"another pull is running"'
exit 0
fi
archive_epoch() {
local name="$1"
local ts="${name:0:16}"
[[ "$ts" =~ ^[0-9]{8}T[0-9]{6}Z$ ]] || return 1
date -u -d "${ts:0:4}-${ts:4:2}-${ts:6:2} ${ts:9:2}:${ts:11:2}:${ts:13:2}Z" +%s
}
verify_archive() {
local archive="$1"
local name="${archive##*/}"
local marker="$DEST/.verified/$name"
local sum tmp
sum="$(sha256sum "$archive" | awk '{ print $1 }')"
if [[ -f "$marker" && "$(cat "$marker")" == "$sum" ]]; then
return 0
fi
tmp="$(mktemp -d "$DEST/.verify.XXXXXX")"
if ! age --decrypt --identity "$AGE_KEY" --output "$tmp/$name.tar" "$archive"; then
rm -rf "$tmp"
echo "backup-pull: $name failed to decrypt" >&2
return 1
fi
if ! tar -xf "$tmp/$name.tar" -C "$tmp"; then
rm -rf "$tmp"
echo "backup-pull: $name did not contain a readable tar archive" >&2
return 1
fi
if ! (cd "$tmp" && sha256sum --check --strict --quiet ./*.sha256); then
rm -rf "$tmp"
echo "backup-pull: $name failed its checksum verification" >&2
return 1
fi
rm -rf "$tmp"
printf '%s\n' "$sum" >"$marker.tmp"
mv "$marker.tmp" "$marker"
VERIFIED=$((VERIFIED + 1))
}
# ---------------------------------------------------------------------------
# Copy
# ---------------------------------------------------------------------------
attempt=1
while true; do
if rsync --archive --partial --compress --timeout=120 \
--include='*.tar.age' --exclude='*' \
--rsh "ssh $SSH_OPTIONS" \
"$VPS_HOST:$REMOTE_DIR/" "$DEST/"; then
break
fi
if ((attempt >= RSYNC_ATTEMPTS)); then
fail "rsync from $VPS_HOST failed after $attempt attempts"
fi
echo "backup-pull: rsync attempt $attempt failed, retrying" >&2
attempt=$((attempt + 1))
sleep 20
done
mapfile -t archives < <(
find "$DEST" -maxdepth 1 -type f -name '*.tar.age' -printf '%f\n' | sort
)
((${#archives[@]} > 0)) || fail "no archives in $DEST after the pull"
for name in "${archives[@]}"; do
[[ "$name" =~ ^[0-9]{8}T[0-9]{6}Z(-[a-z0-9]+)?\.tar\.age$ ]] ||
fail "unexpected file in $DEST: $name"
done
newest="${archives[${#archives[@]} - 1]}"
newest_epoch="$(archive_epoch "$newest")" || fail "cannot parse a timestamp from $newest"
age_seconds=$(($(date -u +%s) - newest_epoch))
if ((age_seconds > MAX_STALENESS_HOURS * 3600)); then
fail "newest archive $newest is $((age_seconds / 3600))h old (limit ${MAX_STALENESS_HOURS}h): VPS backups may have stopped"
fi
# ---------------------------------------------------------------------------
# Verify every archive once; unchanged ciphertext is only re-hashed.
# ---------------------------------------------------------------------------
for name in "${archives[@]}"; do
verify_archive "$DEST/$name" || fail "$name failed verification"
done
# ---------------------------------------------------------------------------
# Retention: 7 daily, then one per ISO week for 4 weeks, then one per calendar
# month for 6 months. Archives outside all three windows are deleted.
# ---------------------------------------------------------------------------
now="$(date -u +%s)"
pruned=0
declare -A kept_week=()
declare -A kept_month=()
mapfile -t newest_first < <(
find "$DEST" -maxdepth 1 -type f -name '*.tar.age' -printf '%f\n' | sort -r
)
for name in "${newest_first[@]}"; do
epoch="$(archive_epoch "$name")" || continue
age_days=$(((now - epoch) / 86400))
if ((age_days < KEEP_DAILY_DAYS)); then
continue
fi
week="$(date -u -d "@$epoch" +%G-W%V)"
if ((age_days < KEEP_WEEKLY_WEEKS * 7)) && [[ -z "${kept_week[$week]:-}" ]]; then
kept_week[$week]=1
continue
fi
month="$(date -u -d "@$epoch" +%Y-%m)"
if ((age_days < KEEP_MONTHLY_MONTHS * 31)) && [[ -z "${kept_month[$month]:-}" ]]; then
kept_month[$month]=1
continue
fi
echo "backup-pull: pruning $name" >&2
rm -f -- "$DEST/$name" "$DEST/.verified/$name"
pruned=$((pruned + 1))
done
log_event pull.completed ",\"newest\":\"$newest\",\"archives\":$(( ${#archives[@]} - pruned )),\"verified\":$VERIFIED,\"pruned\":$pruned,\"duration_s\":$((SECONDS - START_SECONDS))"
heartbeat ok
@@ -0,0 +1,37 @@
# ~/.config/chesstrainer/backup-pull.env -- mode 0600.
#
# Sourced by ~/.local/bin/chesstrainer-backup-pull. Values below are the
# defaults; VPS_HOST and AGE_KEY must be right. Quote anything containing
# spaces.
VPS_HOST=owen@159.69.21.225
REMOTE_DIR=/var/backups/chesstrainer/offsite
DEST="/mnt/Mint Data/chesstrainer-backups"
# Private half of the age key. Back this file up somewhere safe: without it
# every archive is unreadable.
AGE_KEY="$HOME/.config/chesstrainer/age.key"
# Fail the pull when the newest archive from the VPS is older than this, which
# means the VPS backup timer has stopped.
MAX_STALENESS_HOURS=48
# Keep every archive from the last 7 days, then one per ISO week for 4 weeks,
# then one per calendar month for 6 months.
KEEP_DAILY_DAYS=7
KEEP_WEEKLY_WEEKS=4
KEEP_MONTHLY_MONTHS=6
# Restore drill. It runs in a throwaway container matching the production
# Postgres major and appends results to DRILL_LOG.
# DRILL_IMAGE=postgres:18.6
# DRILL_DB=chesstrainer_restore
# DRILL_LOG="$DEST/drills.log"
EXPECTED_ROLES="chesstrainer chesstrainer_ro"
# Optional second heartbeat check with a long period (for example 72h), so you
# hear about it when the workstation stops pulling. Leave empty to disable.
# PULL_HEALTHCHECK_URL=https://hc-ping.com/00000000-0000-0000-0000-000000000000
# Extra ssh options, space separated.
# SSH_OPTIONS="-o BatchMode=yes -o ConnectTimeout=10 -o ServerAliveInterval=15"
@@ -0,0 +1,7 @@
[Unit]
Description=Report a failed Inner Square Chess backup unit
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
[Service]
Type=oneshot
ExecStart=/usr/bin/logger --tag chesstrainer-backup --priority user.err --stderr backup.unit-failed: %i failed, see journalctl --user -u %i
@@ -0,0 +1,13 @@
[Unit]
Description=Monthly restore drill for Inner Square Chess backups
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
OnFailure=chesstrainer-backup-alert@%N.service
[Service]
Type=oneshot
ExecStart=%h/.local/bin/chesstrainer-backup-drill
WorkingDirectory=%h
Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin
Nice=10
TimeoutStartSec=20min
SyslogIdentifier=chesstrainer-backup-drill
@@ -0,0 +1,13 @@
[Unit]
Description=Monthly restore drill for Inner Square Chess backups
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
[Timer]
OnCalendar=*-*-01 09:00:00
RandomizedDelaySec=30m
AccuracySec=5m
Persistent=true
Unit=chesstrainer-backup-drill.service
[Install]
WantedBy=timers.target
@@ -0,0 +1,15 @@
[Unit]
Description=Pull encrypted Inner Square Chess backups from the VPS
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
After=network-online.target
Wants=network-online.target
OnFailure=chesstrainer-backup-alert@%N.service
[Service]
Type=oneshot
ExecStart=%h/.local/bin/chesstrainer-backup-pull
WorkingDirectory=%h
Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin
Nice=10
TimeoutStartSec=15min
SyslogIdentifier=chesstrainer-backup-pull
@@ -0,0 +1,14 @@
[Unit]
Description=Daily pull of encrypted Inner Square Chess backups
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
[Timer]
OnCalendar=*-*-* 12:00:00
OnBootSec=10m
RandomizedDelaySec=10m
AccuracySec=1m
Persistent=true
Unit=chesstrainer-backup-pull.service
[Install]
WantedBy=timers.target
+1 -1
View File
@@ -1,7 +1,7 @@
services:
db:
container_name: chesstrainer_dev-db
image: postgres:18.0
image: postgres:18.6
restart: unless-stopped
environment:
- POSTGRES_USER=postgres
+27
View File
@@ -0,0 +1,27 @@
# The landing page is a server-rendered dead view
The marketing home page is a controller-rendered page (a "dead view") rather
than a LiveView. It shows a static board preview of the first curated endgame
and links to `/endgames/<public code>/play`; the puzzle is not playable on the
home page. Curated puzzle cards are ordinary links, and the puzzle count in the
learning strip is read from the database on each request.
LiveView renders its first response on the server too, so the SEO argument is
mostly about certainty: a dead view guarantees crawlers receive a complete
document without a websocket connecting. It also drops the LiveSocket round
trip and live-diff overhead from the page whose job is to be fast and
indexable. The cost is losing the interactive demo: visitors must follow a
link to try a puzzle, which is where attempts are recorded anyway.
## Consequences
- `HomeLive` and `HomeBoardComponent` are removed; all solving happens on
`/endgames/:public_code/play`.
- The board on the home page is `LandingComponents.board_preview/1` and is
deliberately inert.
- The "Try today's puzzle", "Begin with the basics", and each puzzle card link
straight to the first/selected endgame's player URL, using its public code.
- The puzzle count is request-time, not baked at build time, so it cannot go
stale between deploys.
- If the page feels slow in practice, the next step is a lighter
marketing-only JS bundle without the LiveSocket — deferred until measured.
+40
View File
@@ -0,0 +1,40 @@
# Colour modes use a branded-inverse palette with role tokens
UI colour mode (`system`, `light`, `dark`) is a per-browser preference stored in
`localStorage["phx:theme"]`; `system` follows `prefers-color-scheme` and updates
live when the OS setting changes. The switch lives in the navbar
(`Layouts.colour_mode_toggle/1`) and the mode is applied before first paint by
the inline script in `root.html.heex`.
Dark mode is a branded inverse of the landing page's paper/ink/mint/coral
palette, not Phoenix's stock slate. The raw swatches are role-overloaded —
`--ink` is both body text and the fill behind white text; `--coral-dark` is both
small text on paper and the hover fill under white text — so `app.css` defines a
role layer (`--color-canvas`, `--color-body`, `--color-coral-control`, …) that
templates and stylesheets use. A colour mode overrides only the roles; light
mode reads them from the raw palette. The roles are exposed as `--color-*`, so
they also generate Tailwind utilities (`bg-canvas`, `text-muted`,
`border-hairline`) for templates that use utilities instead of named classes.
The chessboard is deliberately excluded. Chessground's brown board and cburnett
pieces stay identical in both modes, as does the landing-page preview board.
The board is content: recolouring it would make the same position look
different without helping the player, and the piece SVGs are tuned for the
brown board. Only the furniture around it — frame, time pill, promotion
picker — adapts.
## Consequences
- Adding or changing a colour mode means redefining role values, not hunting
selectors. Templates and `app.css` never reference the raw swatches.
- The Phoenix semantic tokens (`primary`, `base-*`, `accent`, …) are retuned to
the brand in both modes, so admin and auth screens do not turn blue in dark
mode. The missing `warning` and `error` dark values are now defined.
- Content colours (`--color-board-*`, `--color-piece-*`,
`--color-on-deep-*`) are intentionally identical across modes.
- The admin preview board (`assets/css/_board.css`) was left out of scope; it
remains light-only until revisited.
- Light-mode WCAG contrast failures are a knowing deferral, tracked in #61. The
role split means fixing them is a value change, not a refactor.
- The GDPR/ePrivacy position for the `localStorage` preference is tracked in
#60.
@@ -0,0 +1,31 @@
# Puzzle sessions are ephemeral and share one play surface
A session — one continuous spell of puzzle play, started by choosing a
difficulty — carries a start time and a rating baseline for the timer and
rating-gain monitor, and lives only in the running `Train` LiveView. Nothing is
persisted: attempts are still recorded per endgame, but the session itself has
no table.
The alternative was to keep `EndgameLive.Play` as the play surface and navigate
from puzzle to puzzle (e.g. `/endgames/:code/play?session=...`), carrying the
session in the URL or a short-lived server token. Navigation kills the LiveView
socket, so the timer, per-puzzle times, baseline and completed count would all
have to be carried or re-derived; that fights the "ephemeral" decision and
leaks session state into URLs. Instead the session owns one socket and swaps the
current endgame in place, which keeps every session value in one place.
To avoid a second copy of the move grading and best-line review, the play
surface (board, grading, opponent reply, review, retry) is extracted into a
shared module used by both `EndgameLive.Play` (standalone, optional auth, used
by daily/curated deep links) and the new `EndgameLive.Train` (session, login
only). Both keep their own `handle_event` entry points, which delegate to the
shared logic, so the existing play tests and event contract are unchanged.
## Consequences
- `/endgames/:public_code/play` stays a standalone play surface; `/train` is the
session front door.
- Session state (difficulty, start time, baseline, completed count, per-puzzle
timing) never leaves the `Train` socket and disappears when the page closes.
- Difficulty is relative to the current user's rating, not an absolute property
of an endgame; its band width is a config constant.
+38
View File
@@ -0,0 +1,38 @@
# Guest puzzles are capped per UTC day by a hashed address
`/guest-train` gives anonymous visitors 5 puzzles per UTC day. The budget is per
client address, but the address is never stored: the limiter keys an in-memory
ETS table by `HMAC-SHA256(boot_secret, "<gregorian_day>|<address>")`. The secret
is generated when the node boots, so digests are not stable across restarts and
cannot be correlated with anything else. The table is swept when the day rolls
over, and no entry is ever written to the database, a log, or a backup.
## Why a daily UTC reset
A fixed 00:00 UTC boundary makes the rule easy to state ("5 free puzzles a
day"), gives every visitor the same reset instant, and removes the need for
per-entry timestamps: the UTC date is part of the key, so yesterday's entries
simply stop matching. That also means the stored data's lifetime is bounded by
the calendar day.
## Why not an IP address
The raw address is never persisted; only the digest is, and only until the day
rolls over or the node restarts. This is abuse prevention with data
minimisation, not tracking, and needs no cookie or client-side storage. The
processing is disclosed in the privacy policy (see #87).
## Consequences
- Visitors behind one NAT share a budget. Masking to a subnet would make that
worse, so the full address is hashed.
- The budget lives in one node's memory: a restart resets it, and a second node
would keep its own. Move the counter to Postgres or Redis if that matters.
- The unit being metered is a puzzle load, not a move. A LiveView reconnect
re-runs the connected mount and therefore consumes one puzzle.
- Retry and review never consume a puzzle because they reuse the loaded
position.
- Signed-in visitors are redirected to `/train` and are never metered.
- Behind a proxy, set `TRUST_FORWARDED_FOR=1` and make sure the proxy overwrites
or appends `X-Forwarded-For`; otherwise every visitor shares the proxy's
budget. `GUEST_PUZZLE_LIMIT` changes the daily allowance.
+55
View File
@@ -0,0 +1,55 @@
# Eight-or-more-piece endgames are trained from engine-sourced corridors that hand off to the tablebase at seven
_Status: accepted. Extends ADR-0005: the ≤7-piece source split stands; this adds a source for 8+._
Syzygy stops at seven pieces and there is no tablebase for eight or more. To
train such endgames without pretending to a completeness they lack, each 8+
endgame is backed by a **corridor**: one or two winning lines, generated offline
with a chess engine (Stockfish), that stay clearly winning at every step. The
corridor is stored as solved positions keyed by position key and served by a new
tablebase backend, so the play loop and grading are unchanged.
The corridor ends at the first capture that brings the board to seven pieces or
fewer. From that position the existing router answers from Syzygy (≤5, local) or
Lichess (6–7), so the tail of every puzzle is tablebase-optimal. Generation
verifies the handoff: it probes the ≤7 position and asserts it is still a win for
the winning side. A promotion does not end the corridor, because it does not
reduce the piece count; only a capture does.
A second line is stored only when both lines are clearly winning — the engine's
evaluation stays above the winning threshold throughout. A line that dips is
discarded rather than shipped as a dubious alternative.
## Grading
Inside the corridor grading is binary: a move on a stored line passes, a move
off the lines fails. The stored move list is deliberately incomplete, so it
cannot support the "any winning move passes" rule the tablebase enables; the
user must find the technique the corridor encodes. Once the position reaches
seven pieces, grading returns to the existing optimal/winning/losing model.
## Why not the alternatives
- **Engine at runtime.** Removes the offline step but adds per-move latency, a
rate limit if it is a remote service, and non-determinism in what counts as
"winning". The corridor is deterministic and free at play time.
- **Hand-authored book.** The same shape without an engine to generate it:
fragile, narrow, and prone to grading a move as losing only because nobody
wrote it down.
- **Solving the whole 8+ region.** Infeasible. The corridor trades completeness
for a short, verified path to a position the tablebase can finish.
## Consequences
- Endgames gain an `oracle` (`:tablebase` or `:corridor`). The changeset admits
8+ FENs only for corridor endgames.
- A corridor-position store (keyed by position key) and a tree backend join the
existing Fathom/Lichess backends. Eight-plus positions without a corridor are
still rejected.
- Generation depends on a Stockfish binary at build/curation time, not at
runtime.
- The corridor is engine-best, not proven-optimal. Honest wording ("engine-best
defence") is required in player-facing copy, and GLOSSARY's *optimal move* and
*winning move* need a corridor-aware distinction.
- An off-corridor legal move fails the attempt; this is a deliberate departure
from tablebase grading and must be reflected in the play surface.
@@ -0,0 +1,65 @@
# Launch observability is the probe, honest error states, and the runbook
_Status: accepted._
At launch, observability means three things and no more: an external check that
the public app answers, error states that are honest and recoverable, and a
written runbook for when either fails. Everything else is deferred with a named
trigger, so the gaps are explicit rather than ambient.
## The launch bar
- **Probe.** A healthchecks.io check with a two-minute period and grace, fed by
an on-box prober with off-box alerting (#160, #161). It curls the public
`/health` through Cloudflare, so DNS, TLS, Caddy, the origin allowlist,
Phoenix and one Postgres query are covered. The loopback cross-check in a
failure body is evidence only. The prober shares a host with the app, so host
death is caught by silence, not by a ping.
- **Error states.** The audit (#162) and its fixes (#163), verified by #164.
Every failure mode has copy and a retry or a way home; exception details and
raw error terms do not reach the page.
- **Runbook.** `deploy/README.md` §Monitoring and alerting: the check, install,
what `/health` proves and does not, Beszel's blind spot, the drills, and the
dated drill log.
## Deferred, with triggers
- **Error tracking (#109, GlitchTip/Sentry).** Deferred because JSON logs
already carry the crash reason and stacktrace per request, and there is no
traffic to aggregate over. Revisit when the first production 500 cannot be
diagnosed from its journal line (missing or truncated stacktrace), or a user
reports an error without a request id, or unexplained errors exceed roughly
50 a day and per-line grep stops being practical.
- **Metrics and LiveDashboard (#111).** Deferred because Beszel covers host
resources and the probe covers the HTTP contract. Revisit when a capacity
question needs a number neither can answer (database pool saturation, p95
latency, queue depth), or daily active users pass 100, or a performance
incident takes more than an hour to localise.
- **Off-box log shipping and error-rate alerts (#140).** Deferred because
journald is persistent on the host and the probe alerts on downness. Revisit
when an alert must fire on a log pattern (error rate, authentication
failures), or the journal retention budget cannot cover a 30-day
investigation, or the host is rebuilt and local logs would be lost in the same
incident.
## Why journald and backups are enough at launch
Persistent journald (`Storage=persistent`, `SystemMaxUse`) holds one JSON object
per line: crashes carry a reason and stacktrace, access lines carry status and
duration, and token-shaped paths, emails and credentials are redacted. Off-box
encrypted backups cover the data.
The accepted risk: losing the host loses the logs with it, and there is no
aggregate error rate. At launch that is acceptable — one host, one operator,
low traffic, and an incident is diagnosed from the journal on the box or from
the probe's alert body. The triggers above are the point at which that risk
stops being acceptable.
## Consequences
- Investigation starts with `journalctl -u chesstrainer -o cat | jq`, not a
dashboard.
- Error tracking, metrics and log shipping stay explicit backlog items with
triggers rather than ambient gaps.
- The probe is an on-box prober with off-box alerting; it is not external
uptime monitoring and the runbook says so.
+93
View File
@@ -0,0 +1,93 @@
# Analytics
We use a self-hosted Matomo instance for privacy-conscious analytics on public
pages and the guest trainer.
## What is collected
- Page views on anonymous public pages and the guest trainer.
- Standard request data Matomo needs to count a visit, with IP anonymisation.
We do **not**:
- set Matomo cookies,
- use user IDs,
- track signed-in account, profile, or admin pages,
- enable cross-site or advertising features,
- share analytics data with third parties.
## Configuration
The app reads these environment variables at boot:
```sh
MATOMO_URL=https://analytics.owenrees.eu/
MATOMO_SITE_ID=6
```
They are configured in `config/runtime.exs` for production only. If either is
missing, no analytics config is rendered and no tracker is loaded.
The root layout renders a hidden `#matomo-config` element only when the visitor
is anonymous. `assets/js/analytics.js` initialises Matomo cookieless from that
element. Signed-in users never receive the element.
## Matomo settings
In the Matomo administration UI:
1. **Administration → Websites → Manage**
- URL: `https://innersquare.app`
- Site ID: `6`
- Timezone: match the site
2. **Administration → Privacy → Anonymize data**
- Enable IP anonymisation (at least the last byte; 2 bytes is safer)
- Disable tracking cookies
- Respect Do Not Track
- Do not use user IDs
- Set raw data retention to **180 days**
3. **Administration → System check / trusted hosts**
- Add `innersquare.app` and `www.innersquare.app` if host validation is on.
4. Do not enable ecommerce, advertising, or cross-domain tracking.
The JavaScript also calls:
```js
_paq.push(["disableCookies"]);
_paq.push(["setDoNotTrack", true]);
```
## Opt-out
The privacy page has an **Analytics** section with an opt-out control. The
preference is stored in `localStorage["matomo_optout"]`, not a cookie. When set,
the tracker is never loaded and LiveView page views are skipped.
The preference is local to the browser. Clearing site data resets it. Users can
also object by emailing `support@innersquare.app`.
## Verification
On an anonymous public page:
```sh
curl -s https://innersquare.app/ | grep -c matomo-config
```
should return `1`.
In the browser:
- `matomo.js` and `matomo.php` load once.
- Matomo Real-time shows the page view.
- No `_pk_*` cookies are created.
- Opting out sets `matomo_optout=1` in localStorage and stops further requests.
- Signed-in pages produce no Matomo config or requests.
- A DNT browser setting suppresses tracking.
## Legal basis
Analytics runs on the basis of legitimate interests in improving the service.
The privacy policy discloses it, explains the data, and provides the opt-out.
This document is an engineering configuration guide, not legal advice; keep a
short legitimate-interest assessment on file.
+84
View File
@@ -0,0 +1,84 @@
# Asset bundle sizes
What the browser downloads, measured rather than guessed. Numbers below are
from the last production build (`mix assets.deploy`, minified and digested) and
were read with `mix assets.sizes`.
Re-measure after any asset change:
```sh
mix assets.deploy
mix assets.sizes
```
`mix assets.sizes` prints raw, gzip and brotli sizes for every built JS and CSS
file. Brotli shows as `-` when the `brotli` CLI is not installed.
## Current bundles
| File | Raw | Gzip |
| --- | ---: | ---: |
| `assets/js/app.js` (LiveView entry) | 219.7 KB | 69.2 KB |
| `assets/js/marketing.js` (controller pages) | 4.8 KB | 1.9 KB |
| `assets/css/app.css` | 94.2 KB | 17.3 KB |
Cached font files, served only when used: DM Sans variable 62.5 KB, DM Serif
Display 24.5 KB, DM Serif Display italic 24.4 KB, DM Sans italic 14.6 KB
(woff2, already compressed).
## What is in each bundle
`app.js` is a single entry loaded by every LiveView page. It contains:
| Part | Raw | Gzip |
| --- | ---: | ---: |
| `phoenix`, `phoenix_live_view`, `phoenix_html` | — | ~30 KB |
| `chessground` (`dist/chessground.min.js`) | 30.0 KB | 11.0 KB |
| `chess.js` (`dist/esm/chess.js`) | 107.1 KB | 23.9 KB |
| `topbar` | 4.3 KB | 1.5 KB |
| `nav`, `analytics`, hooks | ~8 KB | ~3 KB |
The library figures are the packages' own builds; esbuild's minification and
tree shaking mean the bundle total is smaller than the naive sum.
`marketing.js` is deliberately tiny: `phoenix_html`, the nav toggle and the
cookieless analytics loader. It has no LiveView, socket, hooks or topbar.
Controller pages (landing page, legal pages, 404) load it instead of `app.js`.
`app.css` is one Tailwind build for the whole site, including the three
chessground stylesheets (`chessground.base.css` 3.3 KB, `chessground.brown.css`
2.8 KB, `chessground.cburnett.css` 11.5 KB raw, ~4.7 KB gzipped together).
## Findings
1. **Board code is about half of `app.js` and most pages do not use it.**
chessground and chess.js are ~35 KB of the 69 KB gzip payload. They are
needed only by pages that render `ChessBoard`: guest training, play, review.
Profile, settings, the endgame list and every admin screen pay for them and
never instantiate a board.
2. **The marketing/public split is already right.** Public pages do not load
the LiveView runtime at all.
3. **Board CSS is in the global stylesheet.** ~4.7 KB gzipped of chess piece
and board styling reaches every page, including the landing page.
4. **Stale digested bundles accumulate.** `priv/static/assets` currently holds
three generations of `app-*.js` and `app-*.css`. They are not linked but do
bloat the release. `mix phx.digest.clean --age 0` (or deploying from a clean
build) removes them.
## Recommendation (not applied)
Split the board libraries out of the LiveView entry:
- Load `chessground` and `chess.js` with a dynamic `import()` inside
`assets/js/hooks/chessBoard.js` and build with esbuild `--splitting
--format=esm`. Pages without a board then never fetch the chunk; board pages
fetch it once, in parallel with the hook mounting.
- Expected result: `app.js` drops from ~69 KB to ~35 KB gzip on most
authenticated pages, with a separate ~35 KB board chunk fetched only where
needed.
- Move the chessground stylesheets into the board chunk's CSS (or a second CSS
entry loaded only on board pages) to take ~4.7 KB off every page.
- Set a budget in CI once the split lands: `app.js` ≤ 40 KB gzip, board chunk
≤ 40 KB gzip, `marketing.js` ≤ 2 KB gzip, `app.css` ≤ 20 KB gzip.
No build configuration was changed as part of this measurement.
+61
View File
@@ -0,0 +1,61 @@
# Error-state verification
The #162 checklist, walked on 2026-11-13 against a local production-like build.
Failures were filed as #171 and fixed in the follow-up for that issue; this page
records the verification run, not the current state. It is linked from the
audit.
## Method
- **Build:** `MIX_ENV=prod` `mix phx.server` on `127.0.0.1:4010`, commit
`021e412` plus this branch's documentation.
- **Database:** a scratch `postgres:18.6` on port 55432. Empty at first, then
one confirmed user and one 8+ piece endgame (inserted directly, because the
admin changeset rejects positions beyond seven pieces).
- **Configuration:** `PRELAUNCH=false`, `MAILING_LIST_ENABLED=true`,
`TABLEBASE_PATH` pointing at a missing directory, dummy SES credentials.
- **Forced failures:** Postgres stopped, missing tablebase directory, empty
puzzle pool, expired reset and confirmation tokens (backdated
`users_tokens.inserted_at`), stale and invalid mailing-list forms, guest
budget exhausted, unknown public play code.
- **Observation:** `curl` for controller-rendered pages, headless Chrome over
the DevTools Protocol for LiveView-connected pages, and `mix test` for the
interactive states that need a click. Each row names its evidence.
- **Not forced:** a real Lichess 429 (the cooldown and classifier paths were
exercised by the tests), a crash after connect, and the two admin-only import
leaks (code inspection and tests). The first run rejected the socket origin
because `PHX_HOST` defaulted to `example.com`; setting `PHX_HOST=127.0.0.1`
fixed it. That was local configuration, not a product finding.
## Results
| Checklist row | Result | Evidence |
|---|---|---|
| T1 cooldown | **pass** | LiveView test: mount with a cooldown shows "Tablebase cooling down"; Retry re-fetches and returns to play. |
| T2 429 | **pass** | LiveView test: classifier maps 429 to "Tablebase rate-limited"; HTML carries no `429`, `too_many_requests` or upstream body. |
| T3 not covered | **pass** | Prod run: guest page with a 12-piece endgame shows "Position not covered… can't be graded", no `not_covered` in the DOM, Next puzzle or back available. |
| T4 generic | **pass** | LiveView test: classifier returns "Tablebase unavailable"; the reason is logged and never rendered. |
| T5/T6 load and reply failure | **pass** | T5 covered by the cooldown-at-mount test and Retry. T6 shares the blocked panel and `reset/1` path; not separately forced. |
| T8 invalid FEN | **fail** | Existing test: the flash still contains the client message and the raw FEN. #171. |
| S1/S2/S3/S5 empty pools | **pass** | S1 prod: Medium picker shows the in-page empty state and Retry. S5 prod: guest shows "No endgames are available yet" and Retry. S2/S3 tests: exhausted state, Retry and Change difficulty. |
| S4 guest limit | **pass** | Prod run: five visits exhaust the budget; the wall shows the reset time, Sign up free and Log in. |
| A1 reset token | **pass** | Prod run: an expired token flashes "Reset password link is invalid or it has expired." on the log-in page, with Forgot your password available. |
| A2 confirmation token | **fail** | Prod run: an expired token flashes "User not found or token is invalid." and lands on registration, not log in. #171. |
| A3/A4 login | **pass** | Tests: invalid credentials use one message; the throttle reports the remaining minutes. |
| M1–M5 mailing list | **pass** | Prod run: invalid confirmation link, removed address, stale form, invalid email and an SES send failure each show their specific copy with the form reachable. |
| W1/W2 404 and 500 | **pass** | Prod run: styled 404 for an unknown path; with Postgres stopped, `/` returns the styled 500 with no exception or stacktrace. |
| W3 crash | **fail** | The server-error banner has no reload action; a repeating crash has no manual escape. Not separately forced; same banner as W4. #171. |
| W4 disconnect | **pass** | Observed "Something went wrong! Attempting to reconnect" while the socket was rejected, with automatic retries; the banner hides on reconnect. |
| W5 database down | **pass** | Prod run: `/health` returns 503 `db:down`; `/` returns the 500 page. Note the loop: the home link also needs the database, so it 500s too. |
| D1/D2 export | **fail** | Prod run: an export with the database stopped returns the 500 page (no export-specific copy); `/users/profile/export/xml` returns plain text "Unknown export format". #171. |
| H1 empty-database home | **fail** | Prod run: the fallback board renders, but "Try today's puzzle" points at the auth-gated `/endgames`. #171. |
| X1 unknown play code | **pass** | Prod run: `/endgames/nope/play` returns the styled 404 page. This corrects the audit's earlier claim that it 500ed. |
| X2/X3 admin leaks | **fail** | Code inspection and tests: both importer messages still interpolate `inspect(reason)`. Not forced. #171. |
## Tally
- 14 checklist rows pass, 6 fail (8 individual regressions, because D1/D2 and
X2/X3 share a row).
- Every failure row is a state that was already listed as "improve" in the
audit and was outside #163; no new regression came from the #163 changes.
- The regressions are filed together in #171 rather than fixed silently.
+152
View File
@@ -0,0 +1,152 @@
# User-facing error states
What a player sees when something fails, with a verdict for every state and the
concrete change each one needs. This is the audit required by #162; #163
implements the tablebase and empty-pool items, and #164 walks the sign-off
checklist on a production-like build.
Verdicts:
- **keep** — the state is honest, recoverable and leak-free as it stands
- **improve** — a state exists but needs different copy, a recovery action, or
both
- **add** — there is no user-facing state today
"Internal detail" means an exception term, an `inspect/1` result, a raw HTTP
status body, a stacktrace, or a raw FEN appearing in rendered HTML.
**Status:** #163 implements T1–T6, S1–S3 and S5. The rows below describe the
state before that change. #164 walked this checklist on a local prod build:
see [error-states-verification.md](error-states-verification.md).
## Play and tablebase
| ID | State | Trigger | What the user sees today | Verdict | Action |
|---|---|---|---|---|---|
| T1 | Cooldown | A previous 429 put Lichess in cooldown; `Tablebase.new/1` returns `{:cooldown, ms}` (`play_core.ex:386`) | Panel headed **Tablebase unavailable**, body "The tablebase is rate-limited. Try again in about Ns."; move hint "The tablebase is unavailable, so moves cannot be entered."; **Reset** | improve | Heading per failure class ("Tablebase cooling down"), keep the countdown, and relabel Reset to **Retry** while blocked. Fold into #163. |
| T2 | Lichess 429 | Lichess returns 429; the parser records a cooldown (`tablebase/parser.ex:69`) | Same panel; "The tablebase is rate-limited. Try again in a minute." | improve | Same class as T1, with the real countdown once known. Never show `429` or the response body. Fold into #163. |
| T3 | Position not covered | More than seven pieces, Lichess 404, or `:not_covered` (`play_core.ex:394-401`) | Panel headed **Tablebase unavailable**, body "This position is not covered by the tablebase."; **Reset** | improve | Say the puzzle cannot be graded, and offer **Try another puzzle** (session) or **Browse endgames** (single). Retry is futile here, so do not present it as the primary action. Fold into #163. |
| T4 | Generic tablebase failure | 5xx, transport error, malformed response (`play_core.ex:403`) | **"The tablebase is unavailable (#{inspect(reason)})."** | improve | Replace with "The tablebase is unavailable right now. Try again in a moment." and log the reason. This is the leak #163 calls out. Also applies to the review panel's `review_blocked` copy. |
| T5 | Load failure at session start | `Tablebase.new/1` fails in `PlayCore.init/2` → `load_attempt/1` | Board non-interactive; blocked panel and reason; **Reset** | improve | Class-correct copy plus **Retry**; `reset/1` already re-fetches, so this is a label and copy change. Fold into #163. |
| T6 | Fetch failure for the opponent's reply | `start_opponent_reply/2` cannot fetch the new position (`play_core.ex:457`) | Play stops; blocked panel; the move already played is still on the board; **Reset** | improve | Explain that the puzzle is paused and **Retry** resumes from the current position. Fold into #163. |
| T7 | Move while blocked | A move event arrives while `status == :blocked` (`play_core.ex:76`) | Flash "The tablebase is unavailable, so this move cannot be graded." | keep | Defensive guard; the board should already be non-interactive. #164 asserts that. |
| T8 | Invalid FEN from the board hook | `chess_fen_invalid` (`play_core.ex:184`) | Flash **"Endgame FEN is invalid and the board cannot be loaded: #{message} (#{fen})"** | improve | Generic copy ("The board couldn't load this position. Reset to try again."), log the details, and keep **Reset** visible. Leak: client message and raw FEN. |
## Sessions and puzzle pools
| ID | State | Trigger | What the user sees today | Verdict | Action |
|---|---|---|---|---|---|
| S1 | No puzzles available | `Puzzles.next_endgame/3` returns `nil` on start (`train.ex:201`) | Flash error "No puzzles are available right now."; the difficulty picker stays behind it | improve | Replace the flash with an in-page state inside the picker: what happened, **Retry**, and a way to pick another difficulty. Fold into #163. |
| S2 | No more puzzles at this difficulty | `next_endgame` returns `nil` with `exclude_ids` (`train.ex:232`) | Flash info "No more puzzles at this difficulty."; the finished puzzle and **Next puzzle** remain | improve | In-page end-of-run panel: "You've finished every puzzle at this difficulty" with **Retry**, **Change difficulty** (stop session) and the existing Stop session. Hide or disable Next. Fold into #163. |
| S3 | Guest: no more puzzles | Guest `next_puzzle` finds nothing (`guest_train.ex:137`) | Flash info "No more puzzles are available right now." | improve | In-page state with **Retry** and the sign-up/log-in actions, matching the guest-limit panel's tone. Fold into #163. |
| S4 | Guest limit reached | `GuestLimits.take/1` returns `{:limit_reached, ms}` (`guest_train.ex:45-70`) | In-page panel: used N free puzzles, reset time, **Sign up free**, **Log in** | keep | This is the reference state for tone and recovery. |
| S5 | Guest pool empty on load | Random endgame is `nil` (`guest_train.ex:98`) | In-page "No endgames are available yet. Please check back soon." | improve | Add a **Retry** action so the state is not a dead end. Fold into #163. |
## Accounts and email
| ID | State | Trigger | What the user sees today | Verdict | Action |
|---|---|---|---|---|---|
| A1 | Reset token invalid or expired | `get_user_by_reset_password_token/1` returns `nil` (`reset_password.ex:66`) | Flash "Reset password link is invalid or it has expired." then the log-in page, where **Forgot your password?** is available | keep | Honest and recoverable in two clicks. |
| A2 | Confirmation token invalid or expired | `Accounts.confirm_user/1` returns `:error` (`user_confirmation_controller.ex:17`) | Flash **"User not found or token is invalid."** then the registration page | improve | Say "That confirmation link is invalid or has expired." and send the user to log in, where an unconfirmed account triggers a fresh confirmation email. No "user not found" phrasing. |
| A3 | Invalid credentials | `get_user_by_login_and_password/2` returns `nil` | Flash "Invalid email, username or password"; email is prefilled | keep | Deliberately identical for unknown and wrong-password logins, so it does not enumerate accounts. |
| A4 | Login throttle | 5 failures per login or 10 per address in 15 minutes (`LoginThrottle`) | Flash "Too many attempts. Try again in N minutes." | keep | Accurate countdown, no account information. |
## Mailing list
| ID | State | Trigger | What the user sees today | Verdict | Action |
|---|---|---|---|---|---|
| M1 | Confirmation link invalid or expired | Token fails verification (`mailing_list_controller.ex:36`) | Flash "That confirmation link is invalid or has expired." → `/#mailing-list` | keep | The signup form is on the destination page. |
| M2 | Confirmed address no longer subscribed | `MailingList.confirm/1` returns `:not_found` (`:52`) | Flash "That address is no longer on the mailing list. Please sign up again." → `/#mailing-list` | keep | Actionable and specific. |
| M3 | Stale signup form | `MailingListFormToken.verify/1` fails (`:126`) | Flash "Please refresh the page and try again." → `/#mailing-list` | keep | The form is on the page; refresh is the fix. |
| M4 | Invalid email | Missing or invalid address (`:132`) | Flash "Enter a valid email address." | keep | Specific and actionable. |
| M5 | Confirmation email send failure | `Notifier.deliver_confirmation_instructions/2` returns an error (`:111`) | Flash "We couldn't send the confirmation email. Please try again." | improve | Keep the copy, add "If it keeps happening, email …" from `Branding.support_email/0`, and log the reason — the controller currently discards it. |
| M6 | List closed / honeypot / already subscribed | Feature flag, honeypot, or existing address | "The mailing list isn't open yet." / success copy / "You're already on the mailing list." | keep | Closed and honeypot are deliberate; the existing-address message is honest. |
## Site-level
| ID | State | Trigger | What the user sees today | Verdict | Action |
|---|---|---|---|---|---|
| W1 | 404 | Unknown route (`ErrorHTML`, catch-all route) | Styled page: "This page isn't on the board", **Back to home**, plus **Browse puzzles** for premium users | keep | Uses the shared `error_page/1`. |
| W2 | 500 | Controller or render crash | Styled page: "Something went wrong", **Back to home**, **Browse puzzles**, support email | keep | Honest, no exception detail. |
| W3 | LiveView crash | Raise in `mount` or `handle_event` | Mount crash → the 500 page. A crash after connect → the **"Something went wrong!"** banner, automatic reconnect, no manual action | improve | Add a **Reload** action (and keep home) to the server-error banner so a crash that repeats on reconnect has an escape. The banner lives in `layouts.ex:274`. |
| W4 | Disconnect | Socket or network loss | **"We can't find the internet"** banner with a spinner; hides on reconnect | keep | Automatic recovery, no action needed. |
| W5 | Database unavailable | Postgres stopped or pool exhausted | DB-backed pages and LiveView mounts raise → the 500 page; `/health` returns 503 | keep | The 500 page is the right state, but note the loop: the home page also needs the database, so "Back to home" fails too. The probe is the operational signal. No app change proposed here. |
## Data and landing
| ID | State | Trigger | What the user sees today | Verdict | Action |
|---|---|---|---|---|---|
| D1 | Export failure | `Attempts.list_attempts_for_user/1` raises in `UserDataController.export/2` | The 500 page, with no export-specific explanation | improve | Rescue, log, and redirect to `/users/profile/data` with "We couldn't build your export. Try again; if it keeps failing, email …". |
| D2 | Unknown export format | `/users/profile/export/<anything else>` | Plain text `404 "Unknown export format"` with no chrome, links, or home | improve | Return the styled 404 page instead. |
| D3 | Export of an empty account | No attempts | CSV with the header and an empty row; JSON with an empty list | keep | Deliberate and documented by the shape. |
| H1 | Home page with an empty database | No endgames (`PageController.home/2`) | Fallback KRK board, "Featured position", "0 players training", and a **Try today's puzzle** button pointing at `/endgames` | improve | When `active_endgame` is `nil`, do not send the visitor to an auth-gated page with no puzzles: point the call to action at `/guest-train` (which has its own empty state) or disable it with "New puzzles are coming". |
## Admin surfaces (extra)
| ID | State | Trigger | What the user sees today | Verdict | Action |
|---|---|---|---|---|---|
| X1 | Unknown public play code | `/endgames/:code/play` with a code that does not exist (`play.ex:79`) | The styled 404 page: `Ecto.NoResultsError` maps to 404 through `Plug.Exception` | keep | Verified by #164; no change. |
| X2 | Bulk import lookup crash | `handle_async` exits (`import.ex:271`) | Flash **"Could not look up the FENs: #{inspect(reason)}"** | improve | Generic copy plus a logged reason. Admin-only, but still an internal leak. |
| X3 | Bulk import tablebase load failure | `Local.check/0` returns an unexpected error (`import.ex:287`) | **"Local tablebase failed to load: #{inspect(reason)}"** | improve | Generic copy plus a logged reason. Admin-only, but still an internal leak. |
## Internal-detail leaks
These are the only places where an exception term, a raw HTTP status or a raw
FEN can reach rendered HTML. T4 is the one #162 calls out; the rest are smaller
but real.
| Where | Leak | Fix |
|---|---|---|
| `play_core.ex:404` | `inspect(reason)` in the blocked panel | T4 |
| `play_core.ex:189` | client message and raw FEN in a flash | T8 |
| `import.ex:271` | `inspect(reason)` in a flash | X2 |
| `import.ex:287` | `inspect(reason)` in the tablebase status | X3 |
| `user_data_controller.ex:21` | plain-text "Unknown export format" | D2 |
Server logs already carry the real reasons, so none of these fixes lose
diagnostic information.
## Sign-off checklist
For #164 to walk against a production-like build. Every row passes only if the
state offers **retry or a way home** and rendered HTML contains no exception,
stacktrace, raw error term, or raw FEN.
- [ ] **T1 cooldown** — force a cooldown: class-correct heading, countdown, Retry re-fetches.
- [ ] **T2 429** — make Lichess return 429: rate-limit copy, no `429` or response body.
- [ ] **T3 not covered** — play a position with more than seven pieces: explanation, another puzzle or home, no futile Retry.
- [ ] **T4 generic** — make Lichess fail (network off or 5xx): generic copy, Retry works when it recovers, no `inspect`.
- [ ] **T5/T6 load and reply failure** — start a puzzle and lose the tablebase mid-game: paused explanation, Retry resumes.
- [ ] **T8 invalid FEN** — force `chess_fen_invalid`: no client message or raw FEN, Reset visible.
- [ ] **S1/S2/S3/S5 empty pools** — empty the pool: in-page states on train and guest, Retry and change-difficulty reachable.
- [ ] **S4 guest limit** — exhaust the guest allowance: panel, reset time, sign-up and log-in reachable.
- [ ] **A1 reset token** — use an expired link: message, log-in page, forgot-password reachable.
- [ ] **A2 confirmation token** — use an expired link: message, log-in page, fresh confirmation email on next login.
- [ ] **A3/A4 login** — wrong password and throttled login: no account enumeration, countdown.
- [ ] **M1-M5 mailing list** — expired confirmation, stale form, invalid address, send failure: specific copy and the form reachable.
- [ ] **W1/W2 404 and 500** — unknown path and forced crash: styled page, home and browse reachable, no exception.
- [ ] **W3 crash** — raise in a `handle_event`: reload action reachable.
- [ ] **W4 disconnect** — drop the socket: reconnect banner and automatic recovery.
- [ ] **W5 database down** — stop Postgres: 500 pages, `/health` 503, no stacktrace; note that home is also down.
- [ ] **D1/D2 export** — force an export error and an unknown format: flash or 404 page, home reachable.
- [ ] **H1 empty database** — empty the pool: home renders, call to action is not an auth-gated dead end.
- [ ] **X1 unknown play code** — open a stale link: 404 page, not a 500.
- [ ] **X2/X3 admin leaks** — force an import crash and a tablebase error: no `inspect` output.
## Fix list
Fold into **#163** (tablebase and empty-pool recoverability): T1, T2, T3, T4,
T5, T6, S1, S2, S3, S5.
Separate changes, each independently testable:
- **T8** — generic invalid-FEN flash; log the details.
- **A2** — confirmation-token copy and destination.
- **M5** — support fallback on send failure; log the reason.
- **W3** — reload action in the server-error banner.
- **D1** — rescue export errors into a flash on the data tab.
- **D2** — styled 404 for unknown export formats.
- **H1** — empty-database call to action.
- **X2/X3** — generic admin import copy; log the details.
No code changes are part of this audit.
+223
View File
@@ -0,0 +1,223 @@
# Logging
Production writes one JSON object per line to standard output, which systemd
captures in journald. Development and test keep the readable
`[level] message` formatter.
## Configuration
`config/prod.exs` swaps the default handler's formatter for
`Chesstrainer.JSONLogFormatter`; nothing else changes per environment. The
formatter adds no runtime dependency beyond `Jason`, which the app already uses
for Phoenix JSON.
## Line shape
```json
{
"timestamp": "2026-11-10T21:36:28.489000Z",
"level": "error",
"message": "GET /endgames 500 in 12.5ms",
"request_id": "F7x...",
"method": "GET",
"path": "/endgames",
"status": 500,
"duration_ms": 12.5,
"error": {
"kind": "RuntimeError",
"reason": "bad thing",
"stacktrace": ["lib/foo.ex:10: Foo.bar/1"]
}
}
```
`timestamp`, `level` and `message` are always present. Metadata keys are
flattened into the object; reserved internal keys (`time`, `gl`, `report_cb`,
`error_logger`, `exception`, `stacktrace`, `crash_reason`, `reason`, `kind`)
are either unpacked into the line or omitted. Fixed fields win over metadata
with the same name.
| Field | When | Meaning |
|---|---|---|
| `timestamp` | always | ISO-8601 UTC, microsecond precision |
| `level` | always | `debug`, `info`, `notice`, `warning`, `error`, … |
| `message` | always | Rendered log message, truncated to 8 KiB |
| `request_id` | request-scoped logs | `Plug.RequestId` value, including LiveView processes |
| `method`, `path`, `status`, `duration_ms` | access lines | One HTTP request; no query string or body |
| `error.kind` | exceptions/crashes | Exception module, or the crash reason's kind |
| `error.reason` | exceptions/crashes | `Exception.message/1` or an inspected reason |
| `error.stacktrace` | exceptions/crashes | Array of formatted frames, capped at 50 |
| everything else | as supplied | Flattened atom metadata, sanitised and redacted |
Exceptions (`Logger.error(..., exception: ..., stacktrace: ...)`) and OTP crash
reports (`meta.crash_reason`, including Bandit request crashes and GenServer
terminations) become the `error` object. Stacktrace frames are an array of
strings so `jq -r '.error.stacktrace[]'` prints them readably.
## Redaction
The formatter redacts:
- metadata keys named `email`, `*_email`, `email_address`, `contact_email` or
`recipient`;
- any email-shaped string anywhere in metadata, nested `params`, or the rendered
message;
- credentials in `password`, `secret`, `token`, `authorization`, `cookie`,
`api_key`, `private_key` and `credential` keys;
- `token=...`/`password=...` assignments in messages.
Path segments of 20 or more URL-safe characters (reset/confirmation tokens,
UUIDs) are replaced with `[REDACTED]` in access lines. Query parameters and
request bodies are never logged.
## Access lines
`ChesstrainerWeb.RequestLogger` listens to `[:phoenix, :endpoint, :stop]` and
emits one `:info` line per HTTP request that reaches the endpoint, including a
LiveView's initial request. Phoenix's own endpoint start/stop pair is disabled
with `log: false` in `ChesstrainerWeb.Endpoint` so there is exactly one line.
`ChesstrainerWeb.Plugs.PutRequestId` copies `Plug.RequestId`'s id into the
session, and `UserAuth.mount_current_scope/2` puts it into `Logger.metadata/1`,
so logs from the LiveView process keep the id after the HTTP request ends.
## Writing logs
Normal `Logger` calls need no changes. Atom metadata keys are flattened into the
JSON object:
```elixir
require Logger
Logger.info("tablebase cache miss", table: :tablebase, key: key)
Logger.warning("tablebase fetch failed", status: 503, reason: reason)
```
For a caught exception, pass the exception and stacktrace so the formatter can
build the `error` object:
```elixir
Logger.error("cache backup failed", exception: exception, stacktrace: __STACKTRACE__)
```
For background work, wrap the body so `{:error, reason}` returns, throws, exits
and crashes all produce a log line:
```elixir
Task.Supervisor.start_child(Chesstrainer.Cache.BackupSupervisor, fn ->
Chesstrainer.Background.run("send digest", [user_id: user.id], fn ->
send_digest(user)
end)
end)
```
Prefer identifiers such as `user_id` or `table` over emails, and never log
params or request bodies. The formatter is a safety net, not a licence to log
PII.
## Authentication events
`ChesstrainerWeb.UserSessionController` emits warning lines consumed by
host-level tooling such as fail2ban:
| Message | Metadata | Meaning |
|---|---|---|
| `auth.login.failed` | `reason` (`invalid_credentials` / `unconfirmed`), `ip` | A password login failed. |
| `auth.login.throttled` | `reason` (`ip` / `login`), `ip` | The address or login bucket blocked the attempt before bcrypt. |
`ip` is a boot-scoped HMAC of the client address, not the address itself. The
raw login identifier and password are never included. The login throttle is
configured in `config/config.exs` and defaults to five failures per login and
ten per address in a fifteen-minute window.
## Querying logs
`journalctl` prints the raw line only with `-o cat`; the default output wraps it
in journald fields. Install `jq` once on the VPS with
`sudo apt-get install -y jq`, then:
```sh
# Pretty-print recent lines
sudo journalctl -u chesstrainer -o cat -n 50 --no-pager | jq .
# Errors only
sudo journalctl -u chesstrainer -o cat --since "1 hour ago" \
| jq 'select(.level == "error")'
# Everything from one request id
sudo journalctl -u chesstrainer -o cat \
| jq 'select(.request_id == "REQUEST_ID")'
# Crash reason and stacktrace
sudo journalctl -u chesstrainer -o cat \
| jq -r 'select(.error) | "\(.timestamp) \(.error.kind): \(.error.reason)\n\((.error.stacktrace // []) | join("\n"))"'
# Slow requests
sudo journalctl -u chesstrainer -o cat \
| jq 'select(.duration_ms > 1000) | {timestamp, method, path, status, duration_ms}'
# Most common error kinds in the current boot
sudo journalctl -u chesstrainer -o cat -b \
| jq -r 'select(.error.kind) | .error.kind' | sort | uniq -c | sort -rn
```
`Plug.RequestId` also returns the id in the `x-request-id` response header, so a
user can report the id from a failed request and you can filter straight to it.
## Local checks
The formatter tests run without a production release:
```sh
mix test test/chesstrainer/json_log_formatter_test.exs \
test/chesstrainer/background_test.exs \
test/chesstrainer_web/request_logger_test.exs
```
To render one event without touching the Logger configuration:
```sh
mix run --no-start -e '
event = %{
level: :error,
msg: {:string, "boom"},
meta: %{
time: System.system_time(:microsecond),
request_id: "req-1",
email: "user@example.com",
exception: %RuntimeError{message: "bad"},
stacktrace: [{Foo, :bar, 1, [file: ~c"lib/foo.ex", line: 10]}]
}
}
IO.puts(Chesstrainer.JSONLogFormatter.format(event, %{}))
'
```
That prints one JSON line with the email redacted and the exception unpacked
into `error`.
## Background work audit (#107)
Checked:
- `Chesstrainer.Cache` scheduled backup: `Task.Supervisor.start_child` ignored
the task's return value and `Persist.backup/1` returns `{:error, reason}`
without logging. Now wrapped in `Chesstrainer.Background.run/3`, which logs
`{:error, reason}` returns and crashes (with exception, reason and
stacktrace). A failure to start the task is logged too.
- `Chesstrainer.Cache.Persist.restore/1`: an unreadable backup was silently
skipped. It now logs a warning with the reason and starts with an empty cache.
- `Chesstrainer.Endgames.Tablebase.Parser`: Lichess 5xx and network failures
were returned to the caller (which shows a flash) but never logged. They now
log a warning with the status or reason. 429 cooldowns stay quiet because they
are expected.
- `Mix.Tasks.Tablebase.Fetch`: already aborts loudly with `Mix.raise` on HTTP or
network failure; no change.
- Email delivery: sends are synchronous and their error is returned to the
controller, so nothing is silent today. Future background sends should use
`Chesstrainer.Background.run/3`.
## Reading logs on the VPS
See the "Reading production logs" and "Keep the journal" sections in
[`deploy/README.md`](../deploy/README.md).
+191
View File
@@ -0,0 +1,191 @@
# Login and edge security
The login surface is protected in layers. The application throttle is the
primary control; Cloudflare is the edge backstop for volume. There is no
origin-level fail2ban for HTTP logins, because it would require storing raw IP
addresses and would ban Cloudflare edge addresses on this deployment.
## Current production configuration
- Caddy accepts only Cloudflare's published ranges and forwards
`CF-Connecting-IP` as `X-Forwarded-For`. The ranges are refreshed hourly by
`chesstrainer-cloudflare-ranges.timer`.
- `TRUST_FORWARDED_FOR=true`, so the app throttles by the real visitor address.
- Cloudflare Bot Fight Mode is off. The Caddy origin allowlist above stays in
force; re-enabling is tracked in #153.
- The free-plan login flood rule allows 10 login POSTs per 10 seconds per IP and
blocks for 10 seconds.
The short Cloudflare block is rate smoothing, not a credential lockout. The
application's 5-per-login and 10-per-address failures in a 15-minute window are
the real control.
## 1. Application login throttle
`ChesstrainerWeb.LoginThrottle` counts failures in two buckets:
| Bucket | Limit | Window |
|---|---|---|
| Normalised login (email or username) | 5 failures | 15 minutes |
| Client address | 10 failures | 15 minutes |
Blocked attempts are rejected before the database lookup and bcrypt, so they do
not consume password-hashing CPU. A successful login clears the login bucket
only, keeping the address bucket in place so one address cannot spray many
accounts.
The bucket keys are boot-scoped HMACs. Raw addresses and raw login identifiers
are never stored in ETS or written to the application logs. The login form
returns the same generic error for unknown accounts, bad passwords and
unconfirmed accounts.
Configured in `config/config.exs`:
```elixir
config :chesstrainer, ChesstrainerWeb.LoginThrottle,
window_ms: :timer.minutes(15),
max_per_login: 5,
max_per_ip: 10,
confirmation_cooldown_ms: :timer.minutes(15)
```
`auth.login.failed` and `auth.login.throttled` are documented in
`docs/logging.md`.
## 2. Real client IPs behind Cloudflare and Caddy
The production chain is:
```text
Internet
└─ Cloudflare
└─ Caddy :443
└─ Phoenix 127.0.0.1:4100
```
Caddy ignores incoming `X-Forwarded-*` values by default and replaces them with
the immediate peer address. Behind Cloudflare that peer is a Cloudflare edge
node, so without configuration the app would throttle whole Cloudflare POPs
rather than individual visitors.
`deploy/Caddyfile` fixes this by:
1. accepting only Cloudflare's published ranges, and
2. setting `X-Forwarded-For` from Cloudflare's single-value `CF-Connecting-IP`
header.
That keeps `TRUST_FORWARDED_FOR=true` safe: direct clients cannot reach the app
through Caddy, so they cannot forge the header.
`deploy/Caddyfile` imports `cloudflare-ranges.caddy`. The file is generated by
`deploy/update-cloudflare-ranges.sh`; do not edit it by hand.
The script is run hourly by `chesstrainer-cloudflare-ranges.timer`. It:
- downloads <https://www.cloudflare.com/ips-v4> and
<https://www.cloudflare.com/ips-v6>,
- rejects empty or malformed responses,
- validates the candidate Caddyfile,
- reloads Caddy only when the ranges changed.
If the download, validation or Caddy reload fails, the previous ranges stay in
place.
Install and run it:
```sh
sudo install -m 0755 /opt/chesstrainer/src/deploy/update-cloudflare-ranges.sh \
/usr/local/sbin/chesstrainer-update-cloudflare-ranges
sudo install -m 0644 /opt/chesstrainer/src/deploy/cloudflare-ranges.caddy \
/etc/caddy/cloudflare-ranges.caddy
sudo install -m 0644 /opt/chesstrainer/src/deploy/chesstrainer-cloudflare-ranges.service \
/etc/systemd/system/chesstrainer-cloudflare-ranges.service
sudo install -m 0644 /opt/chesstrainer/src/deploy/chesstrainer-cloudflare-ranges.timer \
/etc/systemd/system/chesstrainer-cloudflare-ranges.timer
sudo systemctl daemon-reload
sudo systemctl enable --now chesstrainer-cloudflare-ranges.timer
sudo systemctl start chesstrainer-cloudflare-ranges.service
```
If `/opt/chesstrainer/src/deploy` is not present on the VPS, create the same
four files directly with `sudo tee` from the canonical contents in `deploy/`.
The timer only uses the installed copies.
Check the timer and last run:
```sh
systemctl list-timers chesstrainer-cloudflare-ranges.timer
systemctl status chesstrainer-cloudflare-ranges.service
journalctl -u chesstrainer-cloudflare-ranges.service --since "24 hours ago"
```
Apply the site block by hand on the shared Caddy host, then validate and
reload:
```sh
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```
Direct requests to the origin with a spoofed `CF-Connecting-IP` must receive
`403 Access Denied`; only Cloudflare's ranges should reach the Phoenix app. A
host firewall allowlist for Cloudflare on ports 80 and 443 is a useful
defence-in-depth addition.
## 3. Cloudflare edge rate limiting
This is for connection and request floods, not credential guessing. The
application already stops password attempts cheaply.
The production rule is the free-plan version:
| Setting | Value |
|---|---|
| Name | Login POST flood |
| Expression | `(http.request.method eq "POST" and http.request.uri.path in {"/admin/log-in" "/users/log-in"})` |
| Characteristic | IP |
| Period | 10 seconds |
| Requests | 10 |
| Action | Block |
| Duration | 10 seconds |
Because the free plan only offers a 10-second period and a 10-second block, this
is a burst limiter rather than a lasting ban. An attacker can retry after ten
seconds, but the application still stops that login after five failures and that
address after ten failures within fifteen minutes. A slow attacker staying under
10 requests per 10 seconds never gets to make useful guesses because of the app
throttle.
Bot Fight Mode is off. On the free plan it cannot be skipped for CI or for the
on-box health probe, so a datacenter `curl` gets a 403 while the site itself is
healthy; #153 covers the gate and probe changes needed before it goes back on.
If the plan later gains longer rate-limit windows or managed WAF rules, raise
the block duration and consider a broader site-wide rule, such as 100 requests
per 10 seconds per IP with a managed challenge. Use Under Attack Mode during an
active incident.
### Registration cannot be limited this way
`/users/register` is a LiveView. The form submit is a LiveView event sent over
the shared `/live/websocket` connection, not a `POST /users/register` request.
Cloudflare therefore cannot count account creations with a rule on the
registration path.
A Cloudflare rule on `GET /users/register` only limits page opens; a bot can
open one page and submit many registrations over the socket. If registration
spam becomes a problem, add an application-level registration throttle keyed by
`ChesstrainerWeb.ClientAddress.from_socket/1`, and/or add Cloudflare Turnstile
to the form.
While `PRELAUNCH=true`, registration is blocked entirely by the prelaunch plug
and LiveView mount redirect.
## 4. Why not fail2ban for HTTP?
fail2ban needs the raw client address to build a firewall rule. The application
deliberately logs only a boot-scoped HMAC, and this deployment sits behind
Cloudflare. Banning the address that reaches the origin would ban Cloudflare
edges, not attackers.
fail2ban remains useful for services that terminate connections directly on the
VPS, such as SSH. It is not part of the HTTP login defence.
+19 -2
View File
@@ -23,10 +23,27 @@ machine and a VPS will point at different copies.
export TABLEBASE_PATH=/home/you/Downloads/tablebase
mix phx.server
# Production (release)
TABLEBASE_PATH=/data/syzygy/3-4-5 bin/chesstrainer start
# Production (release), behind systemd
TABLEBASE_PATH=/opt/chesstrainer/tablebases bin/chesstrainer start
```
On the production VPS the directory is `/opt/chesstrainer/tablebases`, owned by
the `chesstrainer` user. Set `TABLEBASE_PATH` in `/etc/chesstrainer/env` rather
than an interactive shell, then restart `chesstrainer.service` — the value is
read at boot.
```sh
sudo chown -R chesstrainer:chesstrainer /opt/chesstrainer/tablebases
sudo chmod -R u=rwX,g=rX,o= /opt/chesstrainer/tablebases
sudo systemctl restart chesstrainer
curl -s http://127.0.0.1:4100/health
```
Healthy local tablebases report `tablebase: "local"` and `status: "ok"`. A
missing, empty, or unreadable directory reports `tablebase: "fallback"` or
`"not_configured"` and `status: "degraded"`, still with HTTP 200 because the
Lichess fallback is available.
The value must reach the process. A bare `TABLEBASE_PATH=...` line in bash
only sets a shell variable and is **not** exported to `mix` or the release —
use `export`, or prefix the command. For a release, systemd unit or container,
+438 -4
View File
@@ -4,9 +4,13 @@ defmodule Chesstrainer.Accounts do
"""
import Ecto.Query, warn: false
require Logger
alias Chesstrainer.Repo
alias Chesstrainer.Accounts.{User, UserToken, UserNotifier}
alias Chesstrainer.Accounts.{Policy, Role, Scope, User, UserToken, UserNotifier}
alias Chesstrainer.MailingList
@admin_users_per_page 25
## Database getters
@@ -98,9 +102,6 @@ defmodule Chesstrainer.Accounts do
def register_user(attrs) do
%User{}
|> User.registration_changeset(attrs)
# Accounts are usable straight away; email confirmation is intentionally off
# because no production mailer adapter is configured yet.
|> Ecto.Changeset.put_change(:confirmed_at, DateTime.utc_now(:second))
|> Repo.insert()
end
@@ -113,6 +114,48 @@ defmodule Chesstrainer.Accounts do
User.registration_changeset(user, attrs, opts)
end
@doc ~S"""
Delivers the confirmation email instructions to the given user.
## Examples
iex> deliver_user_confirmation_instructions(user, &url(~p"/users/confirm/#{&1}"))
{:ok, %{to: ..., body: ...}}
iex> deliver_user_confirmation_instructions(confirmed_user, &url(~p"/users/confirm/#{&1}"))
{:error, :already_confirmed}
"""
def deliver_user_confirmation_instructions(%User{} = user, confirmation_url_fun)
when is_function(confirmation_url_fun, 1) do
if user.confirmed_at do
{:error, :already_confirmed}
else
{encoded_token, user_token} = UserToken.build_email_token(user, "confirm")
Repo.insert!(user_token)
UserNotifier.deliver_confirmation_instructions(user, confirmation_url_fun.(encoded_token))
end
end
@doc """
Confirms a user by the given token.
If the token matches, the user account is marked as confirmed and the token is
deleted. The token is valid for one day.
"""
def confirm_user(token) do
with {:ok, query} <- UserToken.verify_confirmation_token_query(token),
%UserToken{sent_to: email} <- Repo.one(query),
%User{} = user <- Repo.get_by(User, email: email),
{:ok, user} <- Repo.update(User.confirm_changeset(user)),
{_count, _result} <-
Repo.delete_all(from(UserToken, where: [user_id: ^user.id, context: "confirm"])) do
{:ok, user}
else
_ -> :error
end
end
@doc """
Updates a user's authority role.
@@ -125,6 +168,320 @@ defmodule Chesstrainer.Accounts do
|> Repo.update()
end
@doc """
Updates a user's subscription plan.
Plans are programmatic values; registration never casts `plan`, so a user
cannot upgrade themselves.
"""
def update_user_plan(%User{} = user, plan) do
user
|> User.plan_changeset(%{plan: plan})
|> Repo.update()
end
## Admin user management
@doc """
Returns a page of users the scope may administer, newest first.
Options:
* `:search` - case-insensitive match on email or username
* `:page` - 1-based page number (defaults to 1)
* `:per_page` - page size (defaults to 25, capped at 100)
Admins only see members and moderators; super admins see every role.
Returns `{:error, :unauthorized}` when the scope lacks user management.
"""
def list_users_for_admin(scope, opts \\ []) do
with :ok <- ensure_manage_users(scope) do
page = normalize_page(Keyword.get(opts, :page, 1))
per_page = normalize_per_page(Keyword.get(opts, :per_page, @admin_users_per_page))
offset = (page - 1) * per_page
users =
scope
|> admin_users_query(opts)
|> order_by([u], desc: u.inserted_at, desc: u.id)
|> limit(^per_page)
|> offset(^offset)
|> Repo.all()
{:ok, users}
end
end
@doc """
Counts the users visible to the scope, using the same filters as
`list_users_for_admin/2`.
"""
def count_users_for_admin(scope, opts \\ []) do
with :ok <- ensure_manage_users(scope) do
count =
scope
|> admin_users_query(opts)
|> select([u], count(u.id))
|> Repo.one()
{:ok, count}
end
end
@doc """
Fetches a user for the admin detail page.
Returns `{:error, :unauthorized}` when the scope may not view the target and
`{:error, :not_found}` for an unknown id.
"""
def get_user_for_admin(scope, id) do
with :ok <- ensure_manage_users(scope) do
case fetch_user(id) do
nil ->
{:error, :not_found}
%User{} = user ->
if Policy.can_view_user?(scope, user) do
{:ok, user}
else
{:error, :unauthorized}
end
end
end
end
@doc """
Returns an `%Ecto.Changeset{}` for the admin-editable fields (role and plan).
"""
def change_user_as_admin(%User{} = user, attrs \\ %{}) do
User.admin_changeset(user, attrs)
end
@doc """
Updates a user's role and plan after enforcing the admin capability matrix.
The last-super-admin check runs inside the update transaction with a row lock,
so concurrent demotions cannot remove the final super admin.
Returns `{:error, :unauthorized}`, `{:error, :own_role}`,
`{:error, :last_super_admin}` or `{:error, %Ecto.Changeset{}}` instead of
raising.
"""
def update_user_as_admin(scope, %User{} = user, attrs) do
changeset = User.admin_changeset(user, attrs)
role_change = Ecto.Changeset.get_change(changeset, :role)
with :ok <- ensure_manage_users(scope),
:ok <- ensure_not_own_role_change(scope, user, role_change),
:ok <- ensure_can_manage_user(scope, user),
:ok <- ensure_can_assign_role(scope, role_change),
{:ok, updated} <- persist_user_changes(user, changeset) do
log_user_update(scope, user, changeset)
{:ok, updated}
end
end
@doc """
Creates an invitation and emails the recipient a link to choose a password.
The account is confirmed but has no password until the invitee follows the
link. `invite_url_fun` receives the encoded token and must return a URL.
"""
def invite_user_as_admin(scope, attrs, invite_url_fun)
when is_function(invite_url_fun, 1) do
role = normalize_role(role_param(attrs) || :member)
with :ok <- ensure_manage_users(scope),
:ok <- ensure_can_assign_role(scope, role) do
changeset =
%User{}
|> User.invite_changeset(attrs)
|> User.admin_changeset(attrs)
case Repo.insert(changeset) do
{:ok, user} ->
Logger.info("admin.user.invited",
actor_id: scope.user.id,
target_id: user.id,
fields: [:invite]
)
case deliver_invite_instructions(user, invite_url_fun) do
{:ok, _email} -> {:ok, user}
{:error, reason} -> {:error, reason}
end
{:error, changeset} ->
{:error, changeset}
end
end
end
@doc """
Sends a password-reset email on behalf of an administrator.
Uses the same policy as the editable user screen: an admin cannot trigger a
reset for another admin or a super admin.
"""
def send_user_reset_password_instructions_as_admin(scope, %User{} = user, reset_url_fun)
when is_function(reset_url_fun, 1) do
with :ok <- ensure_manage_users(scope),
:ok <- ensure_can_manage_user(scope, user) do
case deliver_user_reset_password_instructions(user, reset_url_fun) do
{:ok, email} ->
Logger.info("admin.user.password_reset_sent",
actor_id: scope.user.id,
target_id: user.id
)
{:ok, email}
error ->
error
end
end
end
@doc """
Resends the account-confirmation email on behalf of an administrator.
"""
def resend_user_confirmation_instructions_as_admin(scope, %User{} = user, confirmation_url_fun)
when is_function(confirmation_url_fun, 1) do
with :ok <- ensure_manage_users(scope),
:ok <- ensure_can_manage_user(scope, user) do
case deliver_user_confirmation_instructions(user, confirmation_url_fun) do
{:ok, email} ->
Logger.info("admin.user.confirmation_resent",
actor_id: scope.user.id,
target_id: user.id
)
{:ok, email}
error ->
error
end
end
end
defp admin_users_query(scope, opts) do
roles = Policy.visible_roles(scope)
search = opts |> Keyword.get(:search, "") |> to_string() |> String.trim()
query = from(u in User, where: u.role in ^roles)
if search == "" do
query
else
pattern = "%#{search}%"
where(
query,
[u],
ilike(u.email, ^pattern) or ilike(u.username, ^pattern)
)
end
end
defp persist_user_changes(user, changeset) do
Repo.transact(fn ->
with :ok <- ensure_not_last_super_admin(user, changeset),
{:ok, updated} <- Repo.update(changeset) do
{:ok, updated}
end
end)
end
defp ensure_not_last_super_admin(%User{role: :super_admin}, changeset) do
case Ecto.Changeset.get_change(changeset, :role) do
role when role in [nil, :super_admin] ->
:ok
_role ->
super_admins =
Repo.all(from(u in User, where: u.role == :super_admin, lock: "FOR UPDATE"))
if length(super_admins) <= 1 do
{:error, :last_super_admin}
else
:ok
end
end
end
defp ensure_not_last_super_admin(_user, _changeset), do: :ok
defp log_user_update(scope, user, changeset) do
fields = changeset.changes |> Map.keys() |> Enum.sort()
if fields != [] do
Logger.info("admin.user.updated",
actor_id: scope.user.id,
target_id: user.id,
fields: fields
)
end
end
defp deliver_invite_instructions(user, invite_url_fun) do
{encoded_token, user_token} = UserToken.build_email_token(user, "reset_password")
Repo.insert!(user_token)
UserNotifier.deliver_invite_instructions(user, invite_url_fun.(encoded_token))
end
defp ensure_manage_users(scope) do
if Policy.can?(scope, :manage_users), do: :ok, else: {:error, :unauthorized}
end
defp ensure_can_manage_user(scope, user) do
if Policy.can_manage_user?(scope, user), do: :ok, else: {:error, :unauthorized}
end
defp ensure_can_assign_role(_scope, nil), do: :ok
defp ensure_can_assign_role(scope, role) do
if Policy.can_assign_role?(scope, role), do: :ok, else: {:error, :unauthorized}
end
defp ensure_not_own_role_change(%Scope{user: %User{id: id}}, %User{id: id}, role)
when not is_nil(role),
do: {:error, :own_role}
defp ensure_not_own_role_change(_scope, _user, _role), do: :ok
defp fetch_user(id) do
Repo.get(User, id)
rescue
Ecto.Query.CastError -> nil
end
defp role_param(attrs), do: Map.get(attrs, "role") || Map.get(attrs, :role)
defp normalize_role(role) do
cond do
role in Role.values() -> role
is_binary(role) -> Enum.find(Role.values(), &(Atom.to_string(&1) == role))
true -> nil
end
end
defp normalize_page(page) when is_integer(page) and page > 0, do: page
defp normalize_page(page) when is_binary(page) do
case Integer.parse(page) do
{number, ""} when number > 0 -> number
_ -> 1
end
end
defp normalize_page(_page), do: 1
defp normalize_per_page(per_page) when is_integer(per_page) and per_page > 0 do
min(per_page, 100)
end
defp normalize_per_page(_per_page), do: @admin_users_per_page
## Settings
@doc """
@@ -168,6 +525,7 @@ defmodule Chesstrainer.Accounts do
with {:ok, query} <- UserToken.verify_change_email_token_query(token, context),
%UserToken{sent_to: email} <- Repo.one(query),
{:ok, user} <- Repo.update(User.email_changeset(user, %{email: email})),
{:ok, _subscription} <- MailingList.update_subscriber_email(user, email),
{_count, _result} <-
Repo.delete_all(from(UserToken, where: [user_id: ^user.id, context: ^context])) do
{:ok, user}
@@ -212,6 +570,66 @@ defmodule Chesstrainer.Accounts do
|> update_user_and_delete_all_tokens()
end
@doc ~S"""
Delivers the reset password email instructions to the given user.
## Examples
iex> deliver_user_reset_password_instructions(user, &url(~p"/users/reset-password/#{&1}"))
{:ok, %{to: ..., body: ...}}
"""
def deliver_user_reset_password_instructions(%User{} = user, reset_password_url_fun)
when is_function(reset_password_url_fun, 1) do
{encoded_token, user_token} = UserToken.build_email_token(user, "reset_password")
Repo.insert!(user_token)
UserNotifier.deliver_reset_password_instructions(user, reset_password_url_fun.(encoded_token))
end
@doc """
Gets the user with the given reset password token.
Returns `nil` if the token is invalid or has expired.
"""
def get_user_by_reset_password_token(token) do
with {:ok, query} <- UserToken.verify_reset_password_token_query(token),
%UserToken{sent_to: email} <- Repo.one(query),
%User{} = user <- Repo.get_by(User, email: email) do
user
else
_ -> nil
end
end
@doc """
Resets the user password.
Returns a tuple with the updated user, as well as a list of expired tokens.
"""
def reset_user_password(user, attrs) do
user
|> User.password_changeset(attrs)
|> update_user_and_delete_all_tokens()
end
## Deletion
@doc """
Permanently deletes a user and all of their data.
Attempts and session tokens are removed by database cascades. There is no
soft delete and no way to recover the account.
## Examples
iex> delete_user(user)
{:ok, %User{}}
"""
def delete_user(%User{} = user) do
Repo.delete(user)
end
## Session
@doc """
@@ -233,6 +651,22 @@ defmodule Chesstrainer.Accounts do
Repo.one(query)
end
@doc """
Returns the number of users with at least one valid session token.
Session tokens stay valid for `UserToken.session_validity_in_days/0` days, so
this counts users who logged in during that window, not necessarily users who
are connected right now. A user with multiple sessions counts once.
"""
def count_logged_in_users do
days = UserToken.session_validity_in_days()
UserToken
|> where([t], t.context == "session" and t.inserted_at > ago(^days, "day"))
|> select([t], count(t.user_id, :distinct))
|> Repo.one()
end
@doc ~S"""
Delivers the update email instructions to the given user.
+100
View File
@@ -0,0 +1,100 @@
defmodule Chesstrainer.Accounts.Policy do
@moduledoc """
The single source of truth for administrator capabilities.
Roles are ordered by `Chesstrainer.Accounts.Role`. An administrator may only
manage users below their own rank; a `super_admin` may also manage admins and
other super admins, but never changes their own role.
The router uses `can?/2` to gate the admin area, and every mutating admin
LiveView calls back into this module or into the scoped `Accounts` functions
so hidden buttons are never the only protection.
"""
alias Chesstrainer.Accounts.{Role, Scope, User}
@capabilities %{
manage_endgames: [:admin, :super_admin],
manage_themes: [:admin, :super_admin],
manage_users: [:admin, :super_admin]
}
@doc "All admin capabilities."
@spec capabilities() :: [atom()]
def capabilities, do: Map.keys(@capabilities)
@doc """
Returns true when the scope may perform the given admin capability.
A nil scope or a member/moderator never satisfies an admin capability.
"""
@spec can?(Scope.t() | nil, atom()) :: boolean()
def can?(%Scope{user: %User{role: role}}, capability) when is_atom(capability) do
role in Map.get(@capabilities, capability, [])
end
def can?(_scope, _capability), do: false
@doc """
Returns true when the scope may edit the target user's role and plan.
An actor may only modify a user whose role rank is strictly lower, except a
`super_admin`, who may also modify admins and other super admins. Nobody may
modify themselves through the admin area.
"""
@spec can_manage_user?(Scope.t() | nil, User.t()) :: boolean()
def can_manage_user?(%Scope{user: %User{} = actor} = scope, %User{} = target) do
cond do
not can?(scope, :manage_users) -> false
actor.id == target.id -> false
actor.role == :super_admin -> true
Role.rank(actor.role) > Role.rank(target.role) -> true
true -> false
end
end
def can_manage_user?(_scope, _target), do: false
@doc """
Returns true when the scope may view the target user in the admin area.
Admins can see themselves and lower-ranked users read-only; super admins can
see everyone. This is deliberately wider than `can_manage_user?/2`, which
controls the editable form.
"""
@spec can_view_user?(Scope.t() | nil, User.t()) :: boolean()
def can_view_user?(%Scope{user: %User{} = actor} = scope, %User{} = target) do
can?(scope, :manage_users) and
(actor.id == target.id or actor.role == :super_admin or
Role.rank(actor.role) > Role.rank(target.role))
end
def can_view_user?(_scope, _target), do: false
@doc """
Returns true when the scope may assign the given role.
Admins can only assign member or moderator. Super admins can assign any role.
"""
@spec can_assign_role?(Scope.t() | nil, Role.value()) :: boolean()
def can_assign_role?(%Scope{user: %User{role: :super_admin}}, role) do
role in Role.values()
end
def can_assign_role?(%Scope{user: %User{role: actor_role}}, role) do
role in Role.values() and Role.rank(actor_role) > Role.rank(role)
end
def can_assign_role?(_scope, _role), do: false
@doc """
Returns the roles whose users the scope may see in the admin user list.
Admins only see members and moderators; super admins see every role.
"""
@spec visible_roles(Scope.t() | nil) :: [Role.value()]
def visible_roles(%Scope{user: %User{role: :super_admin}}), do: Role.values()
def visible_roles(%Scope{user: %User{role: :admin}}), do: [:member, :moderator]
def visible_roles(_scope), do: []
end
+2
View File
@@ -6,6 +6,8 @@ defmodule Chesstrainer.Accounts.Role do
should ask for the minimum tier they need via `at_least?/2`.
"""
@type value :: :member | :moderator | :admin | :super_admin
@values [:member, :moderator, :admin, :super_admin]
@ranks %{
+11
View File
@@ -20,6 +20,8 @@ defmodule Chesstrainer.Accounts.Scope do
defstruct user: nil
@type t :: %__MODULE__{user: User.t() | nil}
@doc """
Creates a scope for the given user.
@@ -30,4 +32,13 @@ defmodule Chesstrainer.Accounts.Scope do
end
def for_user(nil), do: nil
@doc """
True when the scope belongs to a premium user.
`for_user/1` returns `nil` for anonymous visitors, so the catch-all covers
both nil scopes and free plans.
"""
def premium?(%__MODULE__{user: %User{plan: :premium}}), do: true
def premium?(_scope), do: false
end
+41 -1
View File
@@ -15,10 +15,13 @@ defmodule Chesstrainer.Accounts.User do
field :rating_deviation, :float, default: 350.0
field :confirmed_at, :utc_datetime
field :authenticated_at, :utc_datetime, virtual: true
field :mailing_list, :boolean, virtual: true, default: false
timestamps(type: :utc_datetime)
end
@type t :: %__MODULE__{}
@doc """
A user changeset for registration.
@@ -34,7 +37,7 @@ defmodule Chesstrainer.Accounts.User do
"""
def registration_changeset(user, attrs, opts \\ []) do
user
|> cast(attrs, [:email, :username, :password])
|> cast(attrs, [:email, :username, :password, :mailing_list])
|> validate_email(opts)
|> validate_username(opts)
|> validate_confirmation(:password, message: "does not match password")
@@ -52,6 +55,43 @@ defmodule Chesstrainer.Accounts.User do
|> validate_required([:role])
end
@doc """
A user changeset for changing the plan.
The plan is programmatic and must never be cast from user-supplied params.
"""
def plan_changeset(user, attrs) do
user
|> cast(attrs, [:plan])
|> validate_required([:plan])
end
@doc """
A user changeset for an admin-created invitation.
The account is created without a password and marked confirmed, so the
recipient can choose a password from the emailed invitation link and log in
immediately afterwards. Role and plan are applied separately by
`admin_changeset/2` after the caller has checked the policy.
"""
def invite_changeset(user, attrs) do
user
|> cast(attrs, [:email, :username])
|> validate_email([])
|> validate_username([])
|> put_change(:confirmed_at, DateTime.utc_now(:second))
end
@doc """
A user changeset for the fields an administrator may edit.
These values are programmatic, so this changeset is only used by the scoped
admin functions in `Chesstrainer.Accounts`.
"""
def admin_changeset(user, attrs) do
cast(user, attrs, [:role, :plan])
end
@doc """
A user changeset for registering or changing the email.
+67 -6
View File
@@ -1,20 +1,81 @@
defmodule Chesstrainer.Accounts.UserNotifier do
import Swoosh.Email
alias Chesstrainer.Mailer
alias Chesstrainer.Branding
alias Chesstrainer.Mail
# Delivers the email using the application mailer.
defp deliver(recipient, subject, body) do
email =
new()
|> to(recipient)
|> from({"Chesstrainer", "contact@example.com"})
|> subject(subject)
|> text_body(body)
with {:ok, _metadata} <- Mailer.deliver(email) do
{:ok, email}
|> Mail.deliver()
end
@doc """
Deliver instructions to confirm account.
"""
def deliver_confirmation_instructions(user, url) do
deliver(user.email, "Confirmation instructions", """
==============================
Hi #{user.email},
You can confirm your account by visiting the URL below:
#{url}
If you didn't create an account with us, please ignore this.
==============================
""")
end
@doc """
Deliver an invitation to choose a password.
Admins create the account without a password; the invitation link uses the
same reset-password token flow so the recipient can set one.
"""
def deliver_invite_instructions(user, url) do
deliver(user.email, "You're invited to #{Branding.name()}", """
==============================
Hi #{user.username},
An administrator has created an account for you on #{Branding.name()}.
Choose your password by visiting the URL below:
#{url}
If you weren't expecting this invitation, please ignore this email.
==============================
""")
end
@doc """
Deliver instructions to reset a user password.
"""
def deliver_reset_password_instructions(user, url) do
deliver(user.email, "Reset password instructions", """
==============================
Hi #{user.email},
You can reset your password by visiting the URL below:
#{url}
If you didn't request this change, please ignore this.
==============================
""")
end
@doc """
+55
View File
@@ -7,6 +7,8 @@ defmodule Chesstrainer.Accounts.UserToken do
@rand_size 32
@change_email_validity_in_days 7
@confirm_validity_in_days 1
@reset_password_validity_in_days 1
@session_validity_in_days 14
@primary_key {:id, :binary_id, autogenerate: true}
@@ -46,6 +48,9 @@ defmodule Chesstrainer.Accounts.UserToken do
{token, %UserToken{token: token, context: "session", user_id: user.id, authenticated_at: dt}}
end
@doc "How long a session token stays valid, in days."
def session_validity_in_days, do: @session_validity_in_days
@doc """
Checks if the token is valid and returns its underlying lookup query.
@@ -121,6 +126,56 @@ defmodule Chesstrainer.Accounts.UserToken do
end
end
@doc """
Checks if the token is valid and returns its underlying lookup query.
The query returns the user_token found by the token, if any.
This is used to validate requests to confirm the user account.
The given token is valid if it matches its hashed counterpart in the
database and if it has not expired (after @confirm_validity_in_days).
"""
def verify_confirmation_token_query(token) do
case Base.url_decode64(token, padding: false) do
{:ok, decoded_token} ->
hashed_token = :crypto.hash(@hash_algorithm, decoded_token)
query =
from token in by_token_and_context_query(hashed_token, "confirm"),
where: token.inserted_at > ago(@confirm_validity_in_days, "day")
{:ok, query}
:error ->
:error
end
end
@doc """
Checks if the token is valid and returns its underlying lookup query.
The query returns the user_token found by the token, if any.
This is used to validate requests to reset the user password.
The given token is valid if it matches its hashed counterpart in the
database and if it has not expired (after @reset_password_validity_in_days).
"""
def verify_reset_password_token_query(token) do
case Base.url_decode64(token, padding: false) do
{:ok, decoded_token} ->
hashed_token = :crypto.hash(@hash_algorithm, decoded_token)
query =
from token in by_token_and_context_query(hashed_token, "reset_password"),
where: token.inserted_at > ago(@reset_password_validity_in_days, "day")
{:ok, query}
:error ->
:error
end
end
defp by_token_and_context_query(token, context) do
from UserToken, where: [token: ^token, context: ^context]
end
+2
View File
@@ -16,6 +16,8 @@ defmodule Chesstrainer.Application do
{Phoenix.PubSub, name: Chesstrainer.PubSub},
# Start a worker by calling: Chesstrainer.Worker.start_link(arg)
# {Chesstrainer.Worker, arg},
Chesstrainer.GuestLimits,
ChesstrainerWeb.LoginThrottle,
# Start to serve requests, typically the last entry
ChesstrainerWeb.Endpoint,
{Registry, keys: :unique, name: Chesstrainer.CacheRegistry},
+63
View File
@@ -59,5 +59,68 @@ defmodule Chesstrainer.Attempts do
|> Repo.one()
end
@doc """
Returns the number of users who have recorded at least one attempt.
A retry does not count twice: the count is over distinct users.
"""
def count_users_with_attempts do
Attempt
|> select([a], count(a.user_id, :distinct))
|> Repo.one()
end
@doc """
Aggregated attempt totals for `user_id`.
Returns a map with `:attempts`, `:solved`, `:failed` and `:endgames` (the
number of distinct puzzles tried).
"""
def stats_for_user(user_id) do
Attempt
|> where([a], a.user_id == ^user_id)
|> select([a], %{
attempts: count(a.id),
solved: filter(count(a.id), a.outcome == :solved),
failed: filter(count(a.id), a.outcome == :failed),
endgames: count(a.endgame_id, :distinct)
})
|> Repo.one()
end
@doc """
The attempts of `user_id`, newest first, with each endgame preloaded.
Pass `limit: n` to cap the history (the profile page shows a recent window;
exports pass no limit).
"""
def list_attempts_for_user(user_id, opts \\ []) do
Attempt
|> where([a], a.user_id == ^user_id)
|> order_by([a], desc: a.inserted_at)
|> maybe_limit(Keyword.get(opts, :limit))
|> preload(:endgame)
|> Repo.all()
end
@doc """
The distinct endgame ids `user_id` has attempted in the last `days` days.
Used by puzzle selection to skip puzzles inside the repeat window; a retry
still counts as an attempt, even though the rating window leaves it unrated.
"""
def recent_endgame_ids(user_id, days \\ 30) do
cutoff = DateTime.add(DateTime.utc_now(), -days, :day)
Attempt
|> where([a], a.user_id == ^user_id and a.inserted_at >= ^cutoff)
|> distinct(true)
|> select([a], a.endgame_id)
|> Repo.all()
end
defp rated(query), do: where(query, [a], not is_nil(a.rated_at))
defp maybe_limit(query, nil), do: query
defp maybe_limit(query, limit) when is_integer(limit), do: limit(query, ^limit)
end
+63
View File
@@ -0,0 +1,63 @@
defmodule Chesstrainer.Background do
@moduledoc """
Runs background work and logs any failure.
Background failures otherwise disappear: a task exits, the supervisor keeps
the rest of the system running, and nobody sees why the work did not happen.
This wrapper turns crashes, throws, exits and `{:error, reason}` returns into
one structured error line with the reason and stacktrace.
The label is a short description of the work; metadata is added to the log
line unchanged (minus the formatter's own redaction).
"""
require Logger
@type result :: term()
@doc """
Runs `fun` and logs a failure. Returns the function's value, or `:error` when
it crashed or returned an error tuple.
"""
@spec run(String.t(), (-> result)) :: result() | :error
def run(label, fun), do: run(label, [], fun)
@doc """
Like `run/2`, with extra metadata for the error line.
"""
@spec run(String.t(), keyword(), (-> result)) :: result() | :error
def run(label, metadata, fun)
when is_binary(label) and is_list(metadata) and is_function(fun, 0) do
case fun.() do
{:error, reason} ->
Logger.error(
"#{label} failed: #{format_term(reason)}",
Keyword.merge(metadata, reason: reason)
)
:error
result ->
result
end
rescue
exception ->
Logger.error(
"#{label} crashed: #{Exception.message(exception)}",
Keyword.merge(metadata, exception: exception, stacktrace: __STACKTRACE__)
)
:error
catch
kind, reason ->
Logger.error(
"#{label} crashed: #{format_term(reason)}",
Keyword.merge(metadata, kind: kind, reason: reason, stacktrace: __STACKTRACE__)
)
:error
end
defp format_term(term) when is_binary(term), do: term
defp format_term(term), do: inspect(term, limit: 10, printable_limit: 500)
end
+64
View File
@@ -0,0 +1,64 @@
defmodule Chesstrainer.Branding do
@moduledoc """
Public-facing branding, read from `config :chesstrainer, :branding`.
Keeps display names out of templates and controllers so the site can be
renamed in one place. Values are read at runtime, so a deploy can override
them without recompiling.
"""
@defaults [
name: "Inner Square Chess",
wordmark: "INNERSQUARE",
tagline: "Endgame Trainer",
support_email: "support@innersquare.app",
mail_from: "no-reply@mail.innersquare.app",
discord_invite: "https://discord.gg/Z2NfkG7thV"
]
@doc "The display name, e.g. `\"Lucid Chess\"`."
def name, do: get(:name)
@doc "The short wordmark used in the navbar and footer."
def wordmark, do: get(:wordmark)
@doc "The tagline appended to the home title, e.g. `\"Endgame Trainer\"`."
def tagline, do: get(:tagline)
@doc "The support address shown in legal pages and used as the mailer reply-to."
def support_email, do: get(:support_email)
@doc "The From address used for outgoing mail."
def mail_from, do: get(:mail_from)
@doc """
The Discord invite URL, or `nil` when no invite is configured.
Accepts either a bare invite code (`"abc123"`) or a full URL; a bare code is
expanded to `https://discord.gg/<code>`.
"""
def discord_invite_url do
case get(:discord_invite) do
value when is_binary(value) ->
case String.trim(value) do
"" -> nil
"http" <> _ = url -> url
code -> "https://discord.gg/#{code}"
end
_ ->
nil
end
end
@doc "The home-page title, e.g. `\"Lucid Chess — Endgame Trainer\"`."
def home_title, do: "#{name()} — #{tagline()}"
@doc "Builds a page title, e.g. `title(\"Privacy Policy\")`."
def title(page), do: "#{page} — #{name()}"
defp get(key) do
config = Application.get_env(:chesstrainer, :branding) || []
Keyword.get(config, key, Keyword.fetch!(@defaults, key))
end
end
+16 -2
View File
@@ -11,7 +11,8 @@ defmodule Chesstrainer.Cache do
that were used heavily once but have not been used since eventually age out.
A daily backup runs off the cache process at a configurable UTC time, so reads
and writes stay responsive while the snapshot is written.
and writes stay responsive while the snapshot is written. Failures are logged
rather than lost.
## Examples
@@ -19,7 +20,9 @@ defmodule Chesstrainer.Cache do
"""
use GenServer
require Logger
alias Chesstrainer.Background
alias Chesstrainer.Cache.BackupSchedule
alias Chesstrainer.Cache.Persist
@@ -121,7 +124,18 @@ defmodule Chesstrainer.Cache do
table = state.table
backup_fun = state.backup_fun
Task.Supervisor.start_child(Chesstrainer.Cache.BackupSupervisor, fn -> backup_fun.(table) end)
task = fn ->
Background.run("cache backup", [table: table], fn -> backup_fun.(table) end)
end
case Task.Supervisor.start_child(Chesstrainer.Cache.BackupSupervisor, task) do
{:ok, _pid} ->
:ok
{:error, reason} ->
Logger.error("cache backup could not start", table: table, reason: reason)
:ok
end
end
defp schedule_backup(state) do
+7 -1
View File
@@ -5,8 +5,13 @@ defmodule Chesstrainer.Cache.Persist do
A backup is written to a temporary DETS file in the same directory and then
atomically renamed into place. A crash during the write therefore leaves the
previous backup untouched instead of a truncated file that fails to restore.
A backup that cannot be opened at boot is logged and skipped, so a damaged
file does not stop the application from starting with an empty cache.
"""
require Logger
@backup_path "priv/static/backups"
@format_version "v2"
@@ -54,7 +59,8 @@ defmodule Chesstrainer.Cache.Persist do
:dets.close(table)
{:error, _} ->
{:error, reason} ->
Logger.warning("cache backup restore failed", table: table, reason: reason)
:ok
end
end

Some files were not shown because too many files have changed in this diff Show More