Configuration#

How settings are layered#

Three layers, lowest precedence first:

1. Built-in defaults — DEFAULTS in app/config.py. The app runs with no config file at all.
2. app/config/config.yml — your settings. If it does not exist, config.example.yml is used instead, so a fresh checkout boots.
3. Environment variables (RT_*) — these win, and they cover the things that differ per deployment: ports, secrets, the database URL.

YAML layers are deep-merged, so you only need to write the keys you want to change. Setting targets.default_goal does not wipe targets.splits.

The merged result is available to the app as app.config["RT"] and to templates as settings.

cp app/config/config.example.yml app/config/config.yml
$EDITOR app/config/config.yml
docker compose restart web

Environment variables#

Set these in .env, which Compose passes into the container.

Note the four slashes in the SQLite URL: sqlite:////data/... is an absolute path, sqlite:///data/... is relative to the working directory. Getting this wrong is the most common cause of "my data disappeared" — see Troubleshooting.

config.yml#

app#

scrambler#

Controls full scramble generation. See Scrambling.

Turning either rule off produces scrambles that are shorter than they look. Do not, unless you are testing the parser.

drills#

See Drills.

Raising weakest_case_count above about 6 defeats the point of the feature — the value of a small set is that you meet the same case again while the last rep is still fresh.

targets#

The heart of the scoring model. See Expected times for where these numbers come from and how much to trust them.

Each entry under targets.splits is keyed by the goal name used on profiles (Profile.goal_key) and holds a label plus one float per phase:

targets:
  splits:
    sub_20:
      label: "Sub-20"
      cross: 2.5
      f2l: 9.5
      oll: 4.0
      pll: 4.0

You can add your own goal — a sub_8 row, or a casual row with generous targets — and it appears in the profile goal picker automatically. Every phase key in PHASES (cross, f2l, oll, pll) should be present; a missing phase falls back to the default goal's value.

Lowering min_attempts_for_measured to 1 makes scores react immediately and also makes them jumpy, since a single lucky rep then defines a case. Three is the smallest number that lets the trimmed mean do anything useful.

assessment#

assessment:
  scale:
    0: "Never seen it"
    1: "Recognise it, cannot solve it"
    2: "Solve it slowly, need to think"
    3: "Solve it, some hesitation"
    4: "Solid, smooth"
    5: "Instant, no thought"

You can reword the labels — for a younger student, or in another language — but do not change the range. 0..5 is baked into the score formula (self_score / 5 × 100, capped at 80) and into the Assessment.score column. Keys arriving from YAML as strings are normalised to integers on load.

viewer#

See The 3D viewer.

viewer:
  colors:
    U: "#f7f7f7"   # white
    D: "#ffd500"   # yellow
    F: "#009b48"   # green
    B: "#0045ad"   # blue
    R: "#b71234"   # red
    L: "#ff5800"   # orange
    core: "#1b1d21"

This is the standard western (BOY) scheme. Changing it affects the 3D viewer, the flat net and every case thumbnail, because all three read the same map. A common change is swapping F/B and R/L for the Japanese scheme.

The keys are face letters, not colour names, because the internal cube state is colour-agnostic — a facelet stores which face it belongs to, and colour is applied at render time.

docs#

Point this somewhere else and /docs serves that tree instead. Only *.md files are served, and only from inside the root — anything resolving outside it (including through a symlink) returns 404.

analytics#

Traffic analysis with Matomo, done from the server: the app sends page views and events to Matomo's HTTP Tracking API itself. There is no Matomo JavaScript in the pages, so nothing to add to a Content-Security-Policy and nothing for an ad blocker to drop.

Nothing is sent unless enabled is on and a URL and site id are set.

What is tracked

• A page view for every successful HTML page, named after its route — library.index, library.case / OLL 27 — Sune, docs.page / user/library. Never a database id or a query string. The live filter's partial refreshes and JSON calls are not page views.
• Events: auth (sign-in, first-sign-in); practice (rate with the score, drill-start, drill-finish with the reps done, solve with the time in ms); library (case-open, display-switch).
• Site search from the library's search box, once typing has settled, with the result count and the phase as category.

The last two — the display switch and the search — happen only in the browser. A small first-party script reports them to the app's own /analytics/event, which checks them against an allow-list and forwards them. The script is only on pages that are tracked.

What is not

• Anything for a browser sending DNT: 1 or Sec-GPC: 1, for a crawler, or for an ignored path. Those visitors don't even get the script.
• A whole IP address. Without RT_MATOMO_TOKEN no address is sent at all, and Matomo records the server's own address for every hit — visitor and location reports are then meaningless. With the token, the address goes out truncated (IPv4 /24, IPv6 /48).
• Who someone is. A signed-in user is sent as uid, an HMAC of their account id keyed with RT_SECRET_KEY — stable across visits, not reversible to the account. Rotating the secret starts everyone over as new users.
• Cookies: the app sets no tracking cookie. Signed-out visitors are grouped by Matomo's own heuristics (truncated address and browser).

Sending happens on a background thread per worker, from a queue of at most 1000 hits. If Matomo is slow or down, hits are dropped — never waited for — and a warning is logged at most once a minute.

On the Matomo side

1. Create a site for the trainer and note its id.
2. For RT_MATOMO_TOKEN, create a token for a user with write access to that site (Personal → Security → Auth tokens). Matomo needs it to accept cip.
3. Under Privacy → Anonymize data, turn on IP anonymisation (2 bytes) as well, for anything that reaches Matomo by another route, such as an imported nginx log.
4. Under Privacy → Anonymize data → Regularly delete old raw data, delete raw visit logs older than 180 days — the period the privacy notice promises. Aggregated reports can stay.
5. Optionally create a visit-scope custom dimension, "Request id", and set its number as RT_MATOMO_REQUEST_ID_DIMENSION.

A minimal config.yml#

You do not need the whole example file. This is a complete, valid config:

app:
  name: "Cube Club"

targets:
  default_goal: sub_15

drills:
  weakest_case_count: 5
  inspection_seconds: 15

Everything else falls through to the defaults.

Checking what is loaded#

docker compose run --rm web python -c \
  "from app.config import load_settings; import json; print(json.dumps(load_settings(), indent=2))"

That prints the fully merged settings, which is the fastest way to find out whether your file is being read at all. If it looks like the defaults, check RT_CONFIG_FILE and that the file is actually mounted into the container.