Choose a host and matching release
Use a Windows x64 or Linux x86-64 host and a dedicated-server bundle from the same release and channel as your players. The current testing release is 1.10.0. Client/server mismatches are rejected before gameplay.
maxplayers in server.json defaults to 32. This build allows at most 128; a higher value logs a warning and runs with 128.
A public community server should start with HMP Foundation. The bare engine runs without a database, but Foundation needs MySQL 8.x or MariaDB 10.6+ for its persistent systems.
Install the server runtime
The archive separates client/, server/ for Windows, and server-linux/ for Linux. Copy the complete server directory for your platform into a permanent writable folder. Create resources/, logs/, and data/ beside the executable.
On Windows, run HogwartsMPServer.exe from that folder. On Linux, make HogwartsMPServer executable and run it as an unprivileged account. Keep the bundled libnode.so with its matching runtime; if necessary, set LD_LIBRARY_PATH to the server directory.
A service or process manager must use the server directory as its working directory. Relative configuration, resource, data, and log paths are resolved there.
HogwartsMPServer/
HogwartsMPServer.exe # Windows; HogwartsMPServer on Linux
server.json
resources/
data/
logs/
Configure server.json
The five framework keys below must be present with the correct JSON types. Leave map empty. An empty server-token keeps the server unlisted while still allowing direct connections. Start with no required CurseForge mods.
- host is the bind interface, not the address players should type.
- port is the UDP game port. Change the firewall and container mapping if you change it.
- server-token is a private MafiaHub listing key. Keep it out of source control and shared logs.
- mod.curseforge.mods accepts approved numeric project IDs as strings. Requirements apply to connecting clients, so test each addition deliberately.
- Restart the server after configuration or resource changes in distributed release builds.
{
"host": "0.0.0.0",
"port": 27015,
"map": "",
"maxplayers": 32,
"server-token": "",
"mod": {
"curseforge": {
"mods": []
}
}
}
Install Foundation for public gameplay
Foundation supplies persistent characters, inventory, banking, jobs, shops, administration, and other common server systems. Install one complete packaged Foundation release rather than mixing individual hmp-* resource versions.
The mod repository’s resources are internal, test, demonstration, and first-party game-mode material. They are not a supported public-server pack, even when an older resource guide calls individual folders “feature” resources.
- Create the database and a database-scoped account using Foundation’s installation instructions.
- Install all packaged hmp-* resources and their example data/hmp-*.json configurations; replace every CHANGE_ME value.
- Start the database before HogwartsMP. Foundation creates and migrates its own tables.
- Wait for the database connection and every required resource’s ready message. Do not open the server to players when a resource reports Startup failed.
Open the game port; keep services private
Test from outside your network. A successful local connection or TCP port test does not prove that public UDP traffic reaches the server.
| Port | Protocol | Purpose |
|---|
| 27015 | UDP | Game traffic. Forward through NAT for an internet server. |
| 27016 | TCP | Server-information HTTP API. Not needed for players to join; keep private unless deliberately protected. |
| 3306 | TCP | MySQL/MariaDB. Restrict to the host or private network. |
Appear on the masterlist
Sign in to MafiaHub, open the Servers dashboard, and add a server. Put its private server key in server-token, confirm outbound HTTPS and inbound UDP reachability, then restart. The runtime announces itself automatically; no separate heartbeat script is needed.
An empty token means an unlisted server, not a disabled game server. Players can still use Direct Connect. The website filters the public masterlist by the exact HogwartsMP game identifier.
Docker and game panels
Release builds publish ghcr.io/hogwarts-mp/hogwartsmp-server:<version> and a matching Pterodactyl/Pelican egg. Pin a published version such as 1.10.0; the release image has no moving latest tag.
The image contains the server runtime, not a gameplay resource pack or MySQL. Install Foundation separately and persist resources/, data/, configuration, and the database. Source-build Docker examples are for controlled development and must match the client’s Framework revision.
Update and recover safely
Database migrations may not be reversible. Rolling back the runtime can also require restoring its matching database backup. For startup failures, diagnose the first relevant error in logs/hogwarts-mp.log, not only the final shutdown message.
- Announce maintenance and stop the server. The player launcher does not update dedicated servers.
- Back up server.json, data/, custom resources, and the Foundation database.
- Replace the runtime with the matching release and update Foundation as one versioned pack.
- Review new configuration keys, start the database first, and confirm healthy resource startup.
- Join with a matching client and test the server’s core loop before reopening. Keep the previous runtime and matching database backup until the update is proven.