minecraft/docs/worlds-and-network.md

Worlds, maps, and a server network

CraftDeck now has Worlds & Network, Live Maps, and a Capabilities guide. The original Overview, Players, Access, Performance, Schedules and other pages still manage the primary server. The network page manages additional independent servers; its Manage dialog scopes console, files, backups and restore to the selected server.

Quick workflow

1. Open Worlds & Network → Create server. Create a Paper lobby, choose an exact Minecraft version and matching Java runtime, and enter allowed account usernames.
2. Save, then Deploy. This downloads the runtime and waits for Minecraft health. Progress and failures appear in Operations even if you leave the page.
3. Add another Paper or Folia world with a different seed. Both servers can run at once.
4. Select the lobby under Network gateway, save, and Apply routing.
5. Join the gateway's port, then use /server <server-id> to switch servers. IDs appear on the cards. Optional hostname routes can enter a server directly through Velocity.

The gateway defaults to 25566, preserving the primary server's 25565 binding. To keep one public address at port 25565, your router can forward that external port into the gateway's host port 25566. Do not bind two services to the same host port. Changing the lobby and applying routing makes that world the network's entry point. It restarts the proxy and disconnects current connections; it is not a live migration.

A proxy profile's game and RCON ports are not published. Velocity authenticates Minecraft accounts and uses modern forwarding with a shared secret; Paper/Folia are configured to verify that forwarding. All new servers enforce a whitelist. These identities differ from the primary server's offline/EasyAuth accounts. The panel does not migrate inventories or authentication databases between them.

Runtime choices and isolated worlds

Runtime	Connection	Content
Paper	Velocity or direct	Paper-compatible plugins
Folia	Velocity or direct	Plugins explicitly compatible with Folia
Fabric / Forge / NeoForge / Quilt	Direct	Matching loader mods and clients
Vanilla	Direct	Vanilla clients and datapacks
Modrinth modpack	Direct	Exact pack/version, loader supplied by pack

Automatic modern forwarding configuration targets Paper/Folia 1.19+. Fabric and modded proxy integrations require additional compatible mods and version-specific setup; this panel deliberately does not auto-route those profiles. A proxy cannot swap the client's installed modpack. Switching to an incompatible modpack requires changing the client installation and reconnecting.

Each profile has a separate full data directory, including all dimensions, mods, plugin configs, inventories and logs. The Copy settings button creates a fresh world, not a clone of terrain. Change its seed or runtime before first deployment. After initialization, runtime, Minecraft version, Java, modpack version, route and seed are immutable in the profile editor. Create another profile to explore a new version or pack without converting existing terrain accidentally. There is no in-place downgrade or automatic world-conversion feature.

Java 8, 17, 21 and 25 images are available as choices; choose the release required by your exact Minecraft/loader combination. Choosing a runtime does not verify that all uploaded mods support it. Modrinth modpacks are checked against the selected Minecraft version before deployment. Profile runtime images currently use Java tags; for reproducible production deployments, review and pin the generated image digests.

Folia distributes independent regions across threads. It does not make every plugin thread-safe or guarantee a player count/TPS. Players clustered in one region, CPU contention and disk pressure can still cause lag. Allocate RAM for the sum of all running heaps, at least 1 GiB per server overhead, the proxy, maps and the host OS.

Maps

Choose BlueMap or Dynmap on a supported profile. Deployment resolves a stable release advertising the exact Minecraft version and loader; it refuses deployment if no such release is found. It does not fall back to an incompatible JAR. For a manually installed renderer, leave automatic installation off and use its own configuration and ingress.

• BlueMap: internal web port 8100, 3D terrain rendering.
• Dynmap: internal web port 8123, 2D/isometric map rendering.
• Each maps to its own host loopback port. Publish through an HTTPS reverse proxy or use an SSH tunnel. Ports are not exposed on every network interface by default.
• Save the resulting browser URL in the profile and open Live Maps.
• BlueMap requires its own asset-download consent in its generated config. Stop the server, edit it through Manage → Files, and restart after reviewing that setting.
• Initial rendering can be expensive. Configure renderer threads, map dimensions, player visibility, permissions, and privacy in the renderer's files.
• Claims need an addon compatible with the renderer and claim plugin. No claims data is fabricated by CraftDeck. The viewer displays the renderer's real output.

The embedded viewer requires a working reachable URL; it does not prove map health. HTTPS pages cannot embed insecure HTTP content. Renderer CSP/framing headers can require opening the full map in its own tab.

Resource packs and content

Set a direct ZIP URL, the file's SHA-1, an optional prompt and whether accepting the pack is required. Deploy applies these server properties. Use a publicly reachable static file compatible with the client version. The panel configures distribution; it does not host the ZIP or install client mods. Compute a checksum on macOS with shasum -a 1 pack.zip.

Use comma-separated Modrinth slugs (optionally slug:version-id) for managed mods or plugins. Manage → Files can upload JARs into mods/ or plugins/, and datapack ZIPs into world/datapacks/. Config editing and uploads require the server to be stopped. There is a 2 MB text editor limit and 100 MB upload limit. Uploads do not overwrite existing files. Use the profile's Console to manage whitelist entries, gamerules, weather, time, permissions and supported plugin commands. The saved profile whitelist is authoritative at deployment, so also update it when adding permanent players.

Backups, recovery and failures

Every server has a dedicated backup sidecar with an interval and retention policy. The backup data and output directories belong to that profile only. Manual snapshots briefly stop Minecraft and the sidecar, write to a partial archive, verify its contents, then publish it as a completed snapshot. Writers resume afterward. Applying changes to an existing world requires a verified snapshot first; backup failure cancels apply.

Restore verifies the archive before stopping writers, stages the data with the shared restore helper, and retains previous contents under recovery/. The server remains stopped after restore for inspection. Restart or deploy it once ready. Manual snapshots are recovery points; monitor their disk usage in addition to automatic retention.

Operations are serialized with existing primary-server power/backup operations. Their status is persisted. After a panel crash, unfinished jobs are marked failed and are not retried automatically. Inspect actual container status and logs before retrying. An unsuccessful deploy can leave the selected server stopped or unhealthy; it does not claim success or automatically replace data. Proxy config retains a .previous copy before applying changes.

Runtime storage (never commit):

data/dashboard/network.json              # profiles, gateway settings, jobs
data/network/<id>/compose.json           # generated Compose + RCON credential
data/network/<id>/data/                  # complete Minecraft server
data/network/<id>/backups/               # this server's archives
data/network/<id>/recovery/              # retained pre-restore data
data/network/proxy/config/velocity.toml  # routes
data/network/proxy/config/forwarding.secret
data/network/proxy/data/                 # proxy runtime and plugins

Back up the registry and proxy configuration along with server archives. Local backups are not off-host disaster recovery. On the production Docker host, deployment expects the standalone primary server's bind-mounted /data directory and one user-defined Docker network. Komodo managed installations stay read-only and should be extended through homelab-infra. For native Mac testing using Apple’s container CLI, see apple-container.md.

What else is possible?

The in-panel Capabilities guide distinguishes implemented features from addons: claims/towns, economies, cross-server inventories, permissions, rollback, anti-cheat, chunk pregeneration, voice chat, Discord bridges, Bedrock bridging, version translation, custom dimensions, minigames and off-host backups. Those integrations need their own compatible plugins, ports, databases and configuration; they are not preinstalled.

References: Velocity compatibility, modern forwarding, Folia, BlueMap installation, Docker server properties, Modrinth modpacks.