minecraft-server/docs/MIGRATION-PLAN-EXCELLENTSHOP.md

Migration Plan — EZShop + Kiranhart AH → ExcellentShop unified

Date: 2026-05-08 Author: s8n Supersedes: AUDIT-2026-05-07 F-11; SHOP-SYSTEM-DECISION sec. 6 (now operational) Staging: staging/excellentshop/ Status: Ready for operator-scheduled maintenance window.

---

1. Summary

Replace two plugins (EZShop 1.0-SNAPSHOT bespoke + Kiranhart AuctionHouse 1.4.6 ARR-no-LICENSE) with one GPL-3 stack: ExcellentShop 5.0.1 + CoinsEngine 2.7.0, both built by NightExpress against nightcore 2.15.3. All three jars are sourced from the upstream Reposilite (repo.nightexpressdev.com) — source-of-truth identical to a local mvn package from github.com/nulli0n/ExcellentShop-spigot, just reproducible without the brittle alex9849 integration that fails on TLS handshake.

Both modules share one theme, one perm tree, one update cadence. Chest Shop module is disabled — not a future-of-server commit (QuickShop-Hikari path already documented in SHOP-SYSTEM-DECISION).

2. Pre-flight (not in swap.sh, do these first)

1. Heads-up window: post in-game notice via /pm news minus 7d, 1d, 1h. "Auction listings will be drained on YYYY-MM-DD HH:MM."
2. Drain Kiranhart AH: instruct players to claim/cancel listings. Bid-in-progress items revert at the close of the bid window (max 2h, per bid-auction-duration: 7200). Manual refund the residue to the listing owner via /eco give after the window — record the audit trail in live-server/migration-2026-05-08-residue.log.
3. Snapshot live data: invoke scripts/restic-backup-playerdata.sh (already wired for nullstone). Verify the snapshot via restic snapshots --tag pre-shop-migration.
4. Verify staged bundle:

   cd staging/excellentshop/build
   sha256sum *.jar          # match the values committed alongside this doc
   

5. Confirm operator window: compose stop → up takes ~3 minutes; ExcellentShop generates ~11 default shops + 400 items on first start (~30s extra). Total expected downtime: 4-6 minutes best case, 12 minutes worst case (if itzg downloads stall).

3. Swap procedure

scripts/swap.sh runs as user@nullstone and performs:

Step	Action
1	docker compose stop mc
2	tar legacy EZShop + AuctionHouse plugin trees + jars to /opt/docker/minecraft/plugins.tar.bak-<ts>
3	privileged rm -rf of legacy trees and jars (uses docker run --privileged --userns=host per feedback_docker_sudo_bypass)
4	populate /opt/docker/minecraft-custom-plugins/ with the three staged jars, chown 1000:1000
5	replace docker-compose.yml with docker-compose.patch.yml (adds COPY_PLUGINS_SRC=/plugins-custom, the bind mount, and the new REMOVE_OLD_MODS_EXCLUDE glob list) — keeps a .bak-<ts>
6	docker compose up -d mc (first-start config generation runs here)
7	poll mc-health for up to 4 minutes
8	docker cp the staged config overrides into the now-populated plugin tree, run excellentshop reload + coinsengine reload, then run lp-shop-migration.sh over RCON to grant default-tier perms

The compose patch is identical to the existing live compose except for the three lines: PLUGINS (drops EZShop+AH URLs), REMOVE_OLD_MODS_EXCLUDE (adds three new globs), and COPY_PLUGINS_SRC + matching volume mount.

4. Smoke test (post-swap, manual)

Run as a non-staff player and as a staff player:

• /shop → main category menu, 11 shops, GUI renders within 1s.
• /sellall → sells inventory, +N coins chat feedback, /balance updates.
• /sellhand → sells hand stack, hand cleared.
• /ah → AH GUI opens, list a test item via /ah list 100, see it in browse.
• /ah admin: /ah admin remove <listing> works, /ah admin expire works.
• /balance, /pay, /eco resolve through CoinsEngine via Vault bridge.
• Tail logs docker logs -f minecraft-mc | grep -E 'nightcore|ExcellentShop|CoinsEngine|ERROR|WARN' for 5 minutes after first player joins.

If any of the above fail, run scripts/rollback.sh.

5. Rollback

scripts/rollback.sh reverses everything: stops the container, removes ExcellentShop+CoinsEngine+nightcore plugin trees and jars, clears the custom-plugins bind dir, restores legacy EZShop+AuctionHouse from the tar snapshot, restores the previous docker-compose.yml, restarts, and runs lp-shop-rollback.sh over RCON to restore the legacy perm nodes.

Rollback total time: ~5 minutes.

6. Risk register

#	Risk	Likelihood	Impact	Mitigation
R1	nightcore 2.15.3 incompatible with Purpur 1.21.11 (api-version 1.21 should match)	Low	High	Smoke-test on a throwaway container first; rollback path < 5 min if breakage
R2	CoinsEngine 2.7.0 fails Vault bridge (EssentialsX expects Vault)	Medium	High	Vault_Compatibility.Default: true set in staged currency YAML; verify /balance in smoke step 4
R3	NightExpress reposilite goes dark before next maintenance	Low	Low	Jars are committed to the repo at staging/excellentshop/build/ with sha256 receipts — never re-fetched at swap time
R4	Players keep typing /auctionhouse (legacy alias)	Certain	Low	commands.yml aliases [ah, auctionhouse, market] keep muscle memory
R5	EZShop balance migration loss (if EZShop tracked any)	Very Low	Low	EZShop was sell-only with Vault → balances live in EssentialsX, untouched by this swap
R6	Live AH listings lost (residual stuck items)	Medium	Medium	Pre-flight step 2 drains, residue refund is documented
R7	First-start delay > 4 min healthcheck window (large default catalog generation)	Low	Medium	start_period: 240s already set; if exceeded, manual docker exec mc mc-health poll
R8	Compose typo locks server out of plugins	Low	High	swap.sh keeps docker-compose.yml.bak-<ts> for trivial revert; rollback restores it
R9	excellentshop.shop.use not granted to default group → no players can /shop	Medium	High	lp-shop-migration.sh step 8 grants the full perm tree; verify with /lp user <name> permission check excellentshop.shop.use
R10	Compose cap_drop: ALL strips a cap CoinsEngine needs	Low	Low	If /data/plugins/CoinsEngine/ write fails, cap_add: DAC_OVERRIDE rescue documented in swap.sh comments

7. Top 3 swap-window risks (operator brief)

1. R9 (perm regression) — if the LP migration RCON call drops mid-script, players see /shop work but /sellall fail. Mitigation: re-run lp-shop-migration.sh idempotently — every line is permission set <node> true.
2. R7 (slow first-start) — first start of a fresh ExcellentShop with the bundled catalog generation takes ~30s extra and might trip the 240s healthcheck on a cold pool. Mitigation: swap.sh step 7 polls manually before declaring success.
3. R2 (Vault bridge) — if /balance returns 0 instead of the player's actual balance, the Vault bridge from CoinsEngine is mis-wired. Mitigation: Vault_Compatibility.Default: true is in the staged YAML; if still broken, /eco give <player> <prev-balance> from the EssentialsX-side dump that restic-backup-playerdata.sh already takes.

8. Estimated downtime

• Best case: 4 minutes (compose stop → up + health check, no log churn).
• Typical: 6 minutes (one extra stall on jar copy or LP RCON timeout).
• Worst case: 12 minutes (first-start catalog generation slow + manual smoke).

If the worst case is exceeded, abort and run rollback.sh — the data snapshot from pre-flight step 3 is the source of truth.

9. Post-migration

• Update AUDIT-2026-05-07.md F-11: status → Resolved (date 2026-05-08).
• Update docs/COMMANDS.md: /shop, /ah, /sellall, /sellhand, /balance all now route through ExcellentShop+CoinsEngine.
• Update SYSTEM.md plugin table: drop EZShop, drop AuctionHouse 1.4.6, add ExcellentShop 5.0.1, CoinsEngine 2.7.0, nightcore 2.15.3.
• Schedule a follow-up audit in 7d to confirm no log spam, no economy drift, no listing exploits.