IceLegends SMP
A vanilla-first Romanian Minecraft SMP built for clean 3–4 month seasons.
The Problem
Running a community SMP means balancing plugin depth against vanilla feel, managing a world-reset cycle, and keeping operations simple enough for a solo admin. IceLegends SMP solves this with 11 carefully chosen plugins, strict feature gating per a "vanilla-first" principle, and fully automated backups and world resets.
My Role
Designed, configured, and deployed solo — server architecture, 11-plugin selection and configuration, LuckPerms permission model, economy and nation design, Docker infrastructure, and Cloudflare Tunnel ingress for Dynmap.
Highlights
- PaperMC 1.21 on Docker with a hard 11-plugin cap — every plugin is justified and none are redundant
- Towny nations with seasonal quests (Quests + Citizens NPCs) and a single manually-spawned MythicMobs boss per season
- AureliumSkills passive bonuses only — active abilities disabled to preserve vanilla combat (P-01)
- DiscordSRV bridge logs every death, join, and chat event to dedicated Discord channels in real time
- Daily automated backups with 7-day retention; resource world resets every Monday at 05:00 via cron
Stack
Constraints
- Solo admin — every operation must complete in under 10 minutes (P-02).
- Vanilla-first (P-01): if any plugin disappeared tomorrow, the game must continue unchanged.
- 11-plugin hard cap — every addition must displace something or prove unique, irreplaceable value.
System Architecture
Key Trade-offs
The decisions worth defending — what I chose, what I turned down, and why.
Plugin count cap
Chose
Hard cap at 11 plugins
Rejected
Unlimited plugin stack
Each plugin is a maintenance surface and a potential conflict point. The cap forces prioritisation and keeps the dependency graph legible for a solo admin.
Public ingress for Dynmap
Chose
Cloudflare Tunnel (no open ports)
Rejected
Expose :8123 directly via UFW
No origin IP exposure, free DDoS protection, and zero firewall rule maintenance — the same pattern used by the IceLegends portfolio site.
AureliumSkills scope
Chose
Passive bonuses only, active abilities disabled
Rejected
Full AureliumSkills feature set including active combat abilities
Active abilities alter vanilla combat — a direct violation of P-01. Passive bonuses reward playtime additively without changing the combat model.
Season lifecycle
Chose
Full world reset every 3–4 months
Rejected
Incremental map expansion with no reset
Resets keep the world fresh, prevent terrain exhaustion, and give every new player an equal start — critical for community health in a small SMP.
What I'd Do Differently
An honest retrospective — the stuff I'd change with more time, more users, or a second pass.
- 1Add a staging compose stack so plugin updates can be tested before touching the live season — one bad update cost several hours of rollback work.
- 2Move backup storage off-site from day one; local-only archives are a single hardware failure away from a full season loss.
- 3Wire Dynmap as a named Docker service rather than relying on the host port, so the Cloudflare Tunnel config survives container IP reassignment on restart.
Technical Deep-Dive
Architecture, specifications, and implementation details.
16 — Claude Code Implementation Contract
"Read ALL spec files before generating anything. Order matters.
#Pre-Generation Checklist
Before writing a single file:
- Read
00_project_overview.md— understand the philosophy - Read
01_system_architecture.md— understand the directory structure - Read
02_plugin_architecture.md— understand plugin dependencies - Read all remaining files 03–15
"⚠️ CRITICAL: Vault must be configured before ShopGUI+. LuckPerms must be configured before any permission-dependent plugin.
#Complete Deliverables — 23 Files
| # | File | Spec Source | Acceptance Criteria |
|---|---|---|---|
| 01 | docker-compose.yml | 01_system_architecture.md | Valid YAML, healthcheck present, ports 8123+25575 NOT exposed publicly |
| 02 | .env.example | 01_system_architecture.md | All variables present with Romanian comments |
| 03 | .gitignore | 12_security.md | .env and data/ in gitignore |
| 04 | server.properties | 01_system_architecture.md | view-distance=8, online-mode=true, spawn-protection=16 |
| 05 | config/paper-global.yml | 13_performance.md | Anti-xray engine-mode=2, Aikar flags referenced |
| 06 | config/paper-world-defaults.yml | 13_performance.md | Vanilla-compatible spawn limits |
| 07 | config/spigot.yml | 13_performance.md | mob-spawn-range aligned with paper settings |
| 08 | plugin-configs/luckperms/groups.yml | 11_permissions_staff.md | 4 groups: jucator/helper/moderator/admin with correct weights |
| 09 | plugin-configs/essentialsx/config.yml | 02_plugin_architecture.md | Economy disabled, /kit disabled, max-homes=3, locale=ro |
| 10 | plugin-configs/towny/townyconfig.yml | 04_towny_nations.md | war_enabled=false, taxes=0, Romanian titles |
| 11 | plugin-configs/aureliumskills/config.yml | 05_skills_progression.md | active-abilities=false, alchemy+enchanting disabled |
| 12 | plugin-configs/shopgui/shops.yml | 03_economy_design.md | 5 categories, sell prices ≤40% of buy prices |
| 13 | plugin-configs/quests/ | 06_quests_storyline.md | Q1+Q2+Q3 + 2 daily quests, rewards within spec |
| 14 | plugin-configs/mythicmobs/BossFinal.yml | 07_boss_events.md | 3000 HP, 3 phases, loot within economy spec |
| 15 | plugin-configs/discordsrv/config.yml | 10_discord_integration.md | Chat sync + deaths + join/leave. No console channel. |
| 16 | plugin-configs/dynmap/configuration.txt | 10_discord_integration.md | Port 8123, never opened in firewall |
| 17 | scripts/setup.sh | 01_system_architecture.md | Installs Docker + UFW, creates mcserver user, idempotent |
| 18 | scripts/backup.sh | 14_backup_recovery.md | save-off before backup, 7-day retention, excludes resurse world |
| 19 | scripts/reset-resurse.sh | 08_world_management.md | 10-min warning, Discord webhook, recreates world |
| 20 | scripts/update-paper.sh | 01_system_architecture.md | Compares current vs latest via api.papermc.io |
| 21 | scripts/setup-luckperms.sh | 11_permissions_staff.md | All 4 groups, weights, prefixes, permissions |
| 22 | plugins/DOWNLOAD_LIST.md | 02_plugin_architecture.md | All official URLs from plugin spec, with checksum instructions |
| 23 | CHECKLIST.md | 12_security.md + 15_season_lifecycle.md | Pre-launch security checklist + season start steps |
#Code Quality Rules
✅ Every YAML file: valid yaml-lint output
✅ Every bash script: starts with #!/bin/bash and set -euo pipefail
✅ Every config file: Romanian comment above each non-trivial setting
✅ No hardcoded passwords, tokens, IPs, or Discord IDs
✅ Placeholder format: PLACEHOLDER_DESCRIPTIVE_NAME (uppercase + underscore)
✅ docker-compose.yml: Ports 8123 and 25575 NOT in the ports section
✅ .env.example: every variable has an inline comment explaining it
✅ All shell scripts: executable permissions (chmod +x)
#Generation Order
Step 1: docker-compose.yml + .env.example + .gitignore
Step 2: server.properties + config/*.yml
Step 3: plugin-configs/ — in dependency order:
luckperms → essentialsx → towny → aureliumskills
→ shopgui → quests → mythicmobs → discordsrv → dynmap
Step 4: scripts/ — setup.sh first, then others
Step 5: plugins/DOWNLOAD_LIST.md
Step 6: CHECKLIST.md
Step 7: Validate with commands below
#Validation Commands (run after generation)
# 1. Docker Compose syntax
docker compose config
# 2. Dry run
docker compose up --dry-run
# 3. File count
ls -R plugin-configs/ | wc -l # must be ≥ 23
# 4. Security check — must return nothing
grep -r 'RCON_PASSWORD\|TOKEN\|SECRET' docker-compose.yml
# 5. Gitignore check
grep '.env' .gitignore
# 6. Scripts executable
ls -la scripts/*.sh # must show -rwxr-xr-x
#Key References
| Topic | File |
|---|---|
| Architecture diagram | 01_system_architecture.md |
| Plugin dependencies | 02_plugin_architecture.md |
| Economy prices | 03_economy_design.md |
| Towny config values | 04_towny_nations.md |
| Skills to enable/disable | 05_skills_progression.md |
| Quest YAML structure | 06_quests_storyline.md |
| Boss HP and phases | 07_boss_events.md |
| World reset script | 08_world_management.md |
| NPC commands | 09_spawn_design.md |
| Discord channel IDs | 10_discord_integration.md |
| LuckPerms commands | 11_permissions_staff.md |
| Security checklist | 12_security.md |
| JVM flags | 13_performance.md |
| Backup script | 14_backup_recovery.md |
| Season procedures | 15_season_lifecycle.md |
SMP-ARCH-001 v1.0.0 — Implementation Contract