Skip to content

Sync paying families' kids onto the whitelist from fullhearts.app - #77

Merged
OpenSource-For-Freedom merged 1 commit into
mainfrom
feat/fullhearts-whitelist-sync
Oct 17, 2026
Merged

OpenSource-For-Freedom merged 1 commit into
mainfrom
feat/fullhearts-whitelist-sync

Conversation

@YatoVoid

@YatoVoid YatoVoid commented Oct 16, 2026 •

Copy link
Copy Markdown
Collaborator

What

gitops/fullhearts_sync.py keeps the whitelist in step with paid EduCraft access on fullhearts.app. A systemd timer runs it every 2 minutes. It pulls one realm's list of players who should be on, adds the missing ones and removes the ones it added that should be off, then posts a report back to the FullHearts admin page.

file
gitops/fullhearts_sync.py the sync, standard library only
gitops/fullhearts-sync.service / .timer every 2 min, hardened unit
gitops/install_fullhearts_sync.sh asks for the token, writes /etc/educraft-sync.env (600), enables the timer
tests/test_fullhearts_sync.py safety checks, added to CI
.github/workflows/ci.yml runs the tests, fails if compose sets OVERRIDE_WHITELIST
gitops/install_gitops.sh comment only: the whitelist is no longer synced from compose

What it will never do

  • Remove a player it didn't add. It keeps its own ledger (/var/lib/educraft-sync/ledger.json) and only removes entries in it. SihabMaybe, anything in compose WHITELIST, and anyone added with /whitelist add are left alone.
  • Re-add someone you removed by hand while the site still lists them.
  • Act on a bad reply. Site down, slow, wrong token, paused, wrong realm, or anything that doesn't validate: no changes. An empty list is never read as "remove everyone".
  • Mass-remove. At most 2 removals per run, the rest wait for the next run. More than 5 wanted at once removes nobody and sends a Discord alert.
  • Open anything. It pulls over HTTPS and runs rcon-cli inside the container. No ports, no inbound access. The token can only read one realm's list and post a report.

If the ledger is ever lost, everything it added is treated as hand-added and kept, so it fails toward keeping people on.

One trade-off: a player who was whitelisted by hand before paying on the site counts as hand-added, so cancelling won't remove them. You'd remove them yourself.

Install

On the droplet, as root, after merging:

cd /root/minecraft && git pull
bash gitops/install_fullhearts_sync.sh

It asks for the sync token. Get it from fullhearts.app/admin, "Set up sync" on the realm.

It starts in dry-run: it only reports what it would do. Watch the reports on the admin page for 3 days. If they look right, set SYNC_MODE=apply in /etc/educraft-sync.env. The timer picks it up on its next run.

Keep OVERRIDE_WHITELIST off in compose. CI blocks it, because it would rewrite the whitelist on every deploy and wipe the synced kids.

Tested

  • python3 tests/test_fullhearts_sync.py covers hand-added players, the removal limits, bad replies, hand removals, a name that points to a different account, and the dry-run default.
  • End to end on a laptop against a local FullHearts and a fake docker: added on payment, removed on cancel, hand-added players untouched, paused / site down / bad token changed nothing.
  • Not yet run against this server. That's what the dry-run days are for.

A timer pulls one realm's wanted list every 2 minutes and adds or removes
only players it added itself, tracked in its own ledger. Hand-added players
(compose WHITELIST, /whitelist, rcon-cli) are never touched. A bad or paused
reply, or a stopped container, changes nothing. Removals go at most 2 per
run; more than 5 wanted at once removes nobody and alerts. Installs in
dry-run mode; switch SYNC_MODE to apply after checking the reports on the
FullHearts admin page.

CI now fails if compose ever sets OVERRIDE_WHITELIST, which would rewrite
the live whitelist from compose on each deploy and wipe synced players.
@OpenSource-For-Freedom
OpenSource-For-Freedom merged commit 3f356e4 into main Oct 17, 2026
9 checks passed
@OpenSource-For-Freedom
OpenSource-For-Freedom deleted the feat/fullhearts-whitelist-sync branch October 17, 2026 03:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants