Spaces:
Paused
Paused
| title: Minecraft Server | |
| emoji: 🧱 | |
| colorFrom: green | |
| colorTo: blue | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| # Minecraft Server (Java Edition 1.21.11) | |
| [Paper](https://papermc.io) server (1.21.11, build 132) bundled with the | |
| [playit.gg](https://playit.gg) agent so it can be reached from a normal | |
| Minecraft client, plus a small web control panel that runs in the same | |
| container. | |
| ## How the networking works | |
| A Minecraft Java client speaks raw TCP and the Space only routes HTTPS to | |
| `app_port` (7860), so the two cannot meet directly. The playit agent fixes this | |
| without any inbound connectivity: it dials **out** to playit's relays and they | |
| proxy the public address back down that same connection. The Space only ever | |
| makes outbound requests. | |
| ``` | |
| Minecraft client ──TCP──> playit relay <──outbound──> playitd ──> java server :25565 | |
| ``` | |
| Port 7860 hosts the **control panel** (live console, commands, stop/restart), | |
| which also keeps the Space reporting as running. | |
| ## Control panel | |
| Open the Space URL in a browser (keep it private if you want - accessing the | |
| panel is separate from joining the game): | |
| - Live server console with auto-scroll | |
| - Send commands (`say hi`, `list`, `whitelist ...`, `/stop`) via the input or | |
| quick buttons | |
| - **Stop** (graceful, saves the world) and **Restart** | |
| - Status badges: server state, RAM/uptime, playit tunnel state | |
| - Reading logs/status is open; commands and stop/restart require a password | |
| when one is configured | |
| ## Panel / API over HTTP | |
| From a browser the panel page (`/`) already uses the API below. The public | |
| `.hf.space` gateway only reliably forwards **GET** requests (POST bodies get | |
| rejected or stripped of their JSON quotes), so the panel talks to the API with | |
| GET + query parameters: | |
| ```sh | |
| # status / logs | |
| curl https://USER-SPACE.hf.space/api/status | |
| curl "https://USER-SPACE.hf.space/api/log?after=-10" | |
| # run a server command | |
| curl --get --data-urlencode "cmd=list" https://USER-SPACE.hf.space/api/command | |
| curl --get --data-urlencode "cmd=say hello" https://USER-SPACE.hf.space/api/command | |
| # stop (graceful) / restart | |
| curl --get --data-urlencode "action=stop" https://USER-SPACE.hf.space/api/action | |
| curl --get --data-urlencode "action=restart" https://USER-SPACE.hf.space/api/action | |
| ``` | |
| If a `CONTROL_PASSWORD` is set, add the header `X-Token: <token>` where the | |
| token is `sha256("panel-control:" + CONTROL_PASSWORD)`, and log in first via | |
| `POST /api/login` for a panel session. JSON/form POST endpoints also exist | |
| (`/api/command`, `/api/action`, `/api/login`) for callers that can reach the | |
| container directly (e.g. from inside the Space). | |
| ## Setup | |
| 1. Create a Space with the **Docker** SDK and push this repo. | |
| 2. Generate a playit **secret key** (link in the playit dashboard, "new agent"). | |
| 3. Add it in the Space settings under **Variables and secrets** as a **Secret** | |
| named `PLAYIT_SECRET`. Do not commit it. | |
| 4. (Recommended) Add a second Secret named `CONTROL_PASSWORD` to lock the | |
| panel's command/stop/restart actions. Leave it unset only while testing. | |
| 5. In the playit dashboard, create a tunnel of type **Minecraft Java** targeting | |
| `localhost:25565`, then claim it with this Space's agent. | |
| 6. Copy the assigned address and port into the Minecraft client's | |
| *Direct Connect* / *Add Server*. | |
| ## Configuration | |
| | Variable | Default | Notes | | |
| | ----------------- | ------- | -------------------------------------------- | | |
| | `PLAYIT_SECRET` | unset | Required for the tunnel; server still boots without it | | |
| | `CONTROL_PASSWORD`| unset | Gives the panel Open Console / Stop / Restart a password. Leave unset = unlocked (testing only) | | |
| | `MC_MEM` | `4G` | Both `-Xmx` and `-Xms` | | |
| | `STATUS_PORT` | `7860` | Control panel; must match `app_port` | | |
| Server tuning lives in `server.properties` aboard the container. | |
| ## Caveats worth knowing | |
| - **World persistence depends on your storage.** Fresh Spaces use ephemeral | |
| storage and are reset on restart; this space mounts a Storage Bucket at `/data` | |
| so the world/`server.properties` survive rebuilds and playit/client count resets | |
| only with a rebuild. | |
| - **Offline mode is on** (`online-mode=false`), so any username can join and | |
| nothing is verified with Mojang. Turn it on if you want real authentication. | |
| - **Server jar is Paper 1.21.11 (build 132, Java 21 bytecode).** The Paper | |
| bundler re-downloads the Mojang 1.21.11 server jar into `versions/` on first | |
| boot. It runs on the pinned `eclipse-temurin:25-jre-jammy` (Java 25) base image | |
| since newer JVMs run older class files. Swap `server.jar` and reuse `MC_JAR` if | |
| you change versions. | |
| - The server auto-restarts on crash (3s backoff) and restarts if the container | |
| is recreated, so a failed boot loops in the logs - read the newest trace. |