# 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.