lang:ende

throwfather

A self-hostable darts rating system. Score 301/501 matches dart by dart in the app, and every finished match feeds a Glicko-2 leaderboard plus proper darts stats — served by a Nuxt web interface and API. You run the server, the database and the identity provider; nothing phones home.

mode self-hosted
stack Nuxt 4 · Expo 57
db SQLite / PostgreSQL
auth Keycloak (OIDC)

What Throwfather is

The office dartboard, now with a leaderboard nobody asked for. Two components: throwfather-server (Nuxt web interface + API, one Docker image) and the Throwfather app (native, Expo) that scores matches and talks to the same API. The darts sibling of Rodfather.

[01/06]

X01 scorer

$ x01 --start 501 --double-out

301 or 501, double-out or straight-out, first to N legs — scored dart by dart in the app, with checkout hints. A match is stored as the flat list of darts thrown; the server replays it and rejects darts that don't finish the match.

[02/06]

Glicko-2 by leg margin

$ rating --glicko2 --by-leg-margin

Ratings are replayed from the match log, never stored. A 3–0 counts as a full win, a 3–2 as 0.67 — so a close loss costs less than a whitewash.

[03/06]

1v1, doubles, free-for-all

$ match --players 2..8

Singles, 2v2 doubles (each pair rated as one side) or 3–8 players free-for-all, rated by finishing order. Practice matches are stored but never rated.

[04/06]

Darts stats

$ stats --avg --checkout

3-dart average, first-9, 100+/140+/180, checkout %, highest checkout and best leg — all derived from the same replay. They never move the rating.

[05/06]

Match voiding

$ match void <id>

A mis-scored match is voided rather than deleted: it stays on record with a reason, and every rating after it is recomputed without it.

[06/06]

Self-hosted by design

$ docker run -v throwfather-data:/data

One org-agnostic Docker image, all configuration at run time. No tenant, no account, no license server, no layer418 backend involved.

Deploy the server

Nothing about your realm, your org name or your URLs is baked into the image at build time — one published image serves every deployment, and everything is supplied at docker run time.

01

Keycloak client

Create a confidential client in your realm for the web interface, with the callback URL https://your-host/auth/keycloak/callback as a valid redirect URI.

02

Generate 3 secrets

Session secret (≥48 chars), a base64 32-byte token key, and an auth-session secret. In production the server refuses to invent them for you.

03

Run the container

Start ghcr.io/layer418/throwfather-server with those secrets, the realm base URL and the client credentials. The schema is created on boot — no migration step.

04

Optional: enable the app

Set NUXT_APP_CLIENT_ID to a second, public Keycloak client. Left unset, GET /api/config returns 501 and the app simply reports that this instance doesn't support it.

# one image, zero build-time config — everything is passed at run time
docker run -d \
  -p 3000:3000 \
  -v throwfather-data:/data \
  -e NUXT_OIDC_SESSION_SECRET="$(openssl rand -base64 48)" \
  -e NUXT_OIDC_TOKEN_KEY="$(openssl rand -base64 32)" \
  -e NUXT_OIDC_AUTH_SESSION_SECRET="$(openssl rand -base64 48)" \
  -e NUXT_OIDC_PROVIDERS_KEYCLOAK_BASE_URL="https://sso.example.com/realms/acme" \
  -e NUXT_OIDC_PROVIDERS_KEYCLOAK_CLIENT_ID="throwfather-web" \
  -e NUXT_OIDC_PROVIDERS_KEYCLOAK_CLIENT_SECRET="…" \
  -e NUXT_OIDC_PROVIDERS_KEYCLOAK_REDIRECT_URI="https://darts.example.com/auth/keycloak/callback" \
  -e NUXT_PUBLIC_ORG_NAME="Acme GmbH" \
  -e NUXT_APP_CLIENT_ID="throwfather-app" # optional: enables the app
  ghcr.io/layer418/throwfather-server:latest

# generate the three secrets once and keep them stable —
# regenerating them invalidates every existing session.

SQLite or PostgreSQL

One environment variable decides. Leave DATABASE_URL unset and the server uses a SQLite file at DB_PATH (/data/throwfather.db in the image) — the right choice for a single container with a mounted volume.

Set DATABASE_URL to a postgres:// connection string when pods must be independent: more than one replica, rolling updates, or no volume to attach. Web login sessions live in the database too, so any pod can serve them.

Moving a league between backends is a JSON dump of four tables, ids preserved — from the admin page (set THROWFATHER_ADMINS) or the db-transfer CLI. Import is all-or-nothing and refuses a target that already has matches. The dump doubles as a backup.

# SQLite (default) — single container + volume
# DATABASE_URL unset → /data/throwfather.db

# PostgreSQL — multiple replicas, rolling updates,
# or no volume to attach
DATABASE_URL="postgres://throwfather:…@db:5432/throwfather"

# move a league between backends (or back it up):
node server/db-transfer.ts export /data/dump.json
node server/db-transfer.ts import /w/dump.json
# tables: players, matches, match_players, match_voids

Use the app

No server URL is baked into the app. It is built once and works against any self-hosted instance: the user types their server's address on first launch and the app fetches that instance's auth parameters from it.

01

Enter the server

On the setup screen the user types their instance's address. The app normalizes it, reads GET /api/config and shows the org name it found for confirmation — a typo'd address that returns HTTP 200 is rejected by shape validation, not accepted silently.

02

Sign in

Native OIDC Authorization Code + PKCE straight to your Keycloak, using the issuer and public client id from /api/config. No password ever touches the app's own UI.

03

Identify

Tokens are stored in the OS keystore and /api/** is called with a bearer token. GET /api/me maps the token's subject to a player row, so there is no "pick your player" step.

04

Throw

Score a match dart by dart, then browse ranks, matches and player stats. No signal at the board? Finished matches queue on the device and upload once you're back online — retries are safe.

The app needs its own Keycloak client

The web interface uses a confidential client with a secret. A mobile app cannot keep a secret, so it needs a second, public client in the same realm — with client authentication off, PKCE S256, and the redirect URI throwfather://auth.

Pointing NUXT_APP_CLIENT_ID at the confidential web client makes Keycloak reject the app's token exchange with unauthorized_client. Same symptom if the client exists but client authentication is left on.

No audience mapper is needed: the server verifies on every app request that the token was issued to this client, accepting Keycloak's azp claim or a matching aud. That check is not skippable — without it, a token minted for any other client in the realm could act as the app.

# Keycloak → Clients → Create client
client_id            = "throwfather-app"
client_auth          = off        # public client
standard_flow        = on
direct_access_grants = off
redirect_uri         = "throwfather://auth"
pkce                 = "S256"
audience_mapper      = not needed

# then on the server container:
NUXT_APP_CLIENT_ID   = "throwfather-app"

Privacy

Short version: the app collects nothing, and layer418 stores nothing. The only place your league's data exists is the Throwfather server, its database and the Keycloak realm that you host yourself.

The app collects no data

$ telemetry --status → none

No analytics, no telemetry, no crash or performance reporting, no advertising, no tracking identifiers, no third-party SDKs collecting anything on the side. There is no usage data to opt out of, because none is gathered.

no analyticsno telemetryno crash reportingno adsno tracking IDs

There is no layer418 backend

$ grep -r "layer418.de" app/ → 0

The app ships without a server URL and has no default instance to fall back on. It talks to exactly one host: the address the user entered. layer418 operates no service in that path and receives no requests from the app.

All data lives on your systems

$ df -h /your/infrastructure

Players, matches, darts and ratings are stored by the Throwfather server you deployed, in the SQLite file or PostgreSQL database you attached. Accounts, names, emails and logins live in your own Keycloak realm. All of these are backends you host, on infrastructure you choose.

throwfather-serverSQLite / PostgreSQLKeycloak

What stays on the device

$ keychain list throwfather

The server address in app settings, the OIDC tokens in the platform keystore (iOS Keychain / Android Keystore), and finished matches waiting for upload while offline. Signing out deletes the tokens; "change server" deletes the address too. Nothing is ever transmitted anywhere except to your own server and realm.

What your server stores

$ sqlite3 throwfather.db ".tables"

Four tables: players, matches (with the darts thrown and the submitting player's IP address), match_players and match_voids — plus web login sessions. League results, not personal profiles. Identity data (name, email, credentials) stays in Keycloak and is only referenced by the token's subject.

You are the controller

$ whoami → you

Whoever operates the instance is the data controller for it, and decides retention, backups, access and deletion. layer418 is not a processor for your deployment and has no access to it. If we host an instance for you as a paid service, that is a separate contract with a DPA.

# where data flows — and where it does not

  [ throwfather app ]
         │
         │  HTTPS, bearer token
         ├──────────────▶ [ your throwfather-server ] ──▶ [ your database ]
         │
         └──────────────▶ [ your Keycloak realm ]    # login, identities

         ✕──────────────▶ [ layer418 ]              # no connection, ever
         ✕──────────────▶ [ third parties ]         # no SDKs, no analytics
Does the app send anything to layer418?

No. The app has no layer418 endpoint compiled into it and no analytics or crash-reporting SDK. Every network request goes to the server address the user configured and to that instance's Keycloak realm.

Who can see my league's matches?

Only whoever you grant access to in your Keycloak realm. The data never leaves your server and database, so access control is entirely yours — including deleting all of it by dropping the volume or database.

Do I need Keycloak, or can I use another identity provider?

Keycloak is what Throwfather is built and tested against — the server uses its azp claim for the app-client check and the Keycloak OIDC preset for the web interface. Any other OIDC provider is untested.

Can layer418 host it for us?

Yes — we run it on EU-resident infrastructure as a managed deployment, including the Keycloak realm and backups. That is ordinary hosting under contract; the self-hosted route stays available and costs nothing.

Want a hand with the deployment?

Self-hosting is the point, and the docs above should be enough. If you'd rather we ran it — or need it wired into an existing Keycloak realm — mailhello@layer418.deand we'll sort it out.