app-catalog-felhom.eu/REPORT.md

REPORT — crafty-controller: image bump 4.4.8→4.10.7 + Java game-port range + connection guidance

Date: 2026-06-26 · Repo: app-catalog-felhom.eu (catalog-only) · Commit: 2d5b835 (template) Guest: 9201 (demo-felhom) on felhom-pve · Controller: unchanged

Changes (3, catalog-only)

• A — image bump: crafty-4:4.4.8 → 4.10.7 (confirmed latest stable in the GitLab registry; 4.10.8/4.11.0 do not exist). Security CVEs + Java.
• B — publish game ports: added ports: ["25565-25575:25565-25575"] (TCP, 11 Java servers). No network_mode: host; Traefik labels + python3 healthcheck unchanged.
• C — app-page guidance (.felhom.yml): port-range usage + LAN connection (manual IP:port) + internet/port-forward note, in first_steps/prerequisites (the only rendered AppInfo fields).

Verification (live, guest 9201)

Check	Result
Image + health	crafty-4:4.10.7, Up (healthy) (python3 TLS healthcheck passes)
Public URL	minecraft.demo-felhom.eu → 302 (prior 502 fix holds)
Java 25 present?	YES — /usr/lib/jvm/java-25-openjdk-amd64, default java -version = openjdk 25.0.3 (also 8/11/17/21). Latest-MC (26.x) blocker resolved.
Migration	clean from 4.4.8 — "Crafty has fully started"; no traceback (but see TOTP caveat)
Ports published	0.0.0.0:25565-25575->25565-25575/tcp (only host-bound range; others are image EXPOSEs)
Guest network mode	bridged (net0 → vmbr0), own LAN IP 192.168.0.121 (DHCP) — direct LAN reach, no host NAT forward
LAN reachability	from build server 192.168.0.180: 192.168.0.121:25565 OPEN, :25575 OPEN; :25600 (outside range) closed (negative control)
Fresh deploy login	admin / seeded pw → 200 + token
App-page card + guidance	shows the seeded admin password; "25565" guidance rendered

Reachability used synthetic listeners on the range ends (the prior fresh-redeploy removed the old test server). A real Minecraft-client join is the optional gold standard (not performed; Crafty's first server binds 0.0.0.0:25565 by default).

⚠ Key finding — in-place upgrade locks out the admin (TOTP)

An in-place 4.4.8→4.10.7 upgrade of the existing seeded install locked out admin login (401 INCORRECT_CREDENTIALS) despite the correct password (the stored argon2 hash verifies True). Root cause: 4.10.7's login treats len(user.totp_user) > 0 as "2FA enabled", and the old install carried an unconfigured totp_data row (a TOTP secret the customer never set up) — so password-only login is rejected. A fresh 4.10.7 deploy has 0 TOTP rows and logs in fine (verified). The demo (the only existing install) was fresh-redeployed, so no live customer is affected; the catalog bump is safe for new deploys.

Observations (documented, NOT acted on)

1. In-place upgrade remediation: upgrading any pre-4.10 Crafty needs its unconfigured totp_data (+totp_recovery) rows cleared, or the user logs in with a recovery code, else lockout. A safe migration helper (clear TOTP rows that were never user-activated) would be a Crafty-side or entrypoint concern — own task; currently moot (no other installs).
2. Java 25 present → no custom image needed to run latest MC; the earlier "may need a custom temurin-25 image" worry is resolved by 4.10.7 itself.
3. Dynamic connection panel: render the live LAN IP + published range + per-server port on the app page (vs static guidance) — a controller feature, own task.
4. Bedrock (UDP 19132) — out of scope; own task if Bedrock enters product scope.
5. Internet exposure (operator port-forward vs Felhom-operated relay vs Tailscale) — open design call.