From 57ee531c639e1e899d63a786fd878ad9cb1c76e4 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sat, 17 Oct 2026 08:45:48 +0200 Subject: [PATCH 1/5] Host a server: a guide in docs/hosting.md, and the site's /server page built from it What works on main today (install, game files, first run, server.toml, the commands, the web panel, backups, services, Docker built by hand) and, plainly, what doesn't yet: offline mode only, no published image, no secure chat or locator bar, the open PRs that are coming. The site renders the guide into /server at build time, so it has one source. The CSP hashes now cover every page's inline script, so the privacy page's theme script is allowed too. Co-Authored-By: Claude Opus 5.5 --- docs/README.md | 3 +- docs/hosting.md | 306 +++++++++++++++++++++++++++++++++++++ website/Caddyfile | 3 +- website/README.md | 3 +- website/build.mjs | 16 +- website/public/sitemap.xml | 1 + website/src/index.html | 2 +- website/src/server.html | 31 ++++ 8 files changed, 356 insertions(+), 9 deletions(-) create mode 100644 docs/hosting.md create mode 100644 website/src/server.html diff --git a/docs/README.md b/docs/README.md index 7cf322042..9a5ea0483 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,7 +6,8 @@ To play, use [the launcher](../launcher/README.md); the project site is [playhor - [Build from source](../README.md#build-from-source): your own copy of the game, resource preparation, `cargo run`. - [Native client](native-client.md): options, controls, the dedicated server, `horizon-ctl` scripting, packaging, architecture. -- [Hosting a server](server.md): `horizon-server`, the design and the plan: install, `server.toml`, the CLI, the web panel, backups, services, Docker, and the bot benchmark against vanilla. +- [Host a server](hosting.md): install `horizon-server`, prepare the game files, first run, `server.toml`, the commands, the web panel, backups, services and Docker; what works today and what doesn't yet. +- [Hosting a server: design](server.md): `horizon-server`, the design and the plan: install, `server.toml`, the CLI, the web panel, backups, services, Docker, and the bot benchmark against vanilla. - [Agent control](agent-control.md): what AI agents can drive in the launcher and the game, and the design of the control socket, `horizon-ctl` and MCP. - [Graphics](graphics.md): the Simple and Advanced graphics settings, the graphics benchmark and what it measured. - [Benchmark](benchmark.md): Horizon against vanilla 26.3 and vanilla with performance mods, on the same machine, world, path and settings: what is measured, how it is kept fair, how to reproduce it. diff --git a/docs/hosting.md b/docs/hosting.md new file mode 100644 index 000000000..483d1cfcb --- /dev/null +++ b/docs/hosting.md @@ -0,0 +1,306 @@ +# Host a server + +`horizon-server` hosts a Minecraft Java Edition 26.3 server with Horizon's own game as the engine: one native +program, no Java, one settings file, a command line, and a web panel. Vanilla 26.3 clients and Horizon clients +can join it. This page covers what works on `main` today and says plainly what doesn't yet. The design and the +plan are in [docs/server.md](docs/server.md). + +## Before you start + +- **It runs in offline mode only.** Today the server never checks Minecraft accounts: even with + `online_mode = true` it runs offline and says so when it starts. Anyone who can reach it can join under any + name, including a name on your whitelist. Run it on your LAN, on a tailnet (Tailscale, ZeroTier), or for + friends you trust. Don't open it to the internet. +- **Online mode is coming in two parts.** Checking accounts with Mojang's session servers is in review ([#587](https://github.com/ludovic111/horizon/pull/587), + and [#589](https://github.com/ludovic111/horizon/pull/589) for adding players to the whitelist and ops by account). With it, players who sign in with the + official Minecraft launcher can join with their own accounts. Horizon's own client can't sign in to a + Microsoft account yet: that needs an Azure app registration and Mojang's approval, which the project doesn't + have yet ([docs/microsoft-account.md](docs/microsoft-account.md)). Until then Horizon players can join + offline servers only. +- **No secure chat.** Chat isn't signed. Vanilla clients show chat from the server as not secure. +- **No locator bar** for vanilla clients yet (coming). +- **Remote players stay in the Overworld.** Nether and End portals don't move remote players yet (in review: + [#668](https://github.com/ludovic111/horizon/pull/668), for a server with one player). +- **Vanilla's movement checks and chunk pacing** ("moved too quickly", sending chunks as fast as a client + acknowledges them) are in review ([#586](https://github.com/ludovic111/horizon/pull/586)). +- **No Docker image is published.** You build it yourself from the repository (below). Publishing an image + needs the project owner. +- Nothing of Mojang's is downloaded or shipped. The server reads the game files you prepare from your own copy + of Minecraft 26.3. + +## 1. Install + +Linux (x86-64) and macOS (Apple Silicon): + +```sh +curl -fsSL https://raw.githubusercontent.com/ludovic111/horizon/main/packaging/server/install.sh | sh +``` + +Windows (x64), in PowerShell: + +```powershell +irm https://raw.githubusercontent.com/ludovic111/horizon/main/packaging/server/install.ps1 | iex +``` + +The script downloads the latest Horizon release for your computer from GitHub, checks it against the SHA-256 +GitHub publishes, and never asks for sudo or administrator rights. It installs: + +- the release in `~/.local/share/horizon/releases/` (Windows: `%LOCALAPPDATA%\Horizon`), with + `current` pointing at the one in use; +- `horizon-server` and `horizon-prepare` in `~/.local/bin` (Windows: added to your PATH); +- a `game-files` folder for the files you prepare, kept across updates. + +Options: `--version vX.Y.Z`, `--dir FOLDER`, `--bin FOLDER` (Windows: `-Version`, `-Dir`). Other systems, +such as Linux on ARM, build from source: `cargo build --release -p horizon-client --bin horizon-client -p +horizon-server` and keep both programs in one folder. + +The Horizon launcher also installs releases. Every release folder holds `horizon-server`, so you can run it +from there too. + +## 2. Prepare the game files + +Horizon reads Minecraft's data from your own copy of the game. You need Minecraft Java Edition 26.3, played +once from the official launcher on this computer, Java 25 (a JDK), and the 26.3 `server.jar`: it's the +`downloads.server.url` in your launcher's `versions/26.3/26.3.json`. Then: + +```sh +horizon-prepare --prepare --server-jar /path/to/server.jar +``` + +Add `--minecraft-dir PATH` if your launcher keeps the game elsewhere. The prepared files go to +`game-files`, which updates keep. + +**On a headless machine** (a VPS, a home server), prepare on your own computer instead, with the launcher or +`horizon-prepare`, and copy the prepared `26.3` folder to the server: into +`~/.local/share/horizon/game-files/horizon-client/26.3`, or into `resources/` in the server folder, or anywhere +`[engine] resources` in `server.toml` names. A folder copied this way needs a release newer than +v2026.10.17.05: older ones don't keep `registries.json` and `commands.json` with the prepared files, and the +server then stops with "registries.json not found next to the resources". Prepare again with a newer release. + +## 3. First run + +```sh +mkdir my-server && cd my-server +horizon-server init +``` + +`init` asks five things and writes `server.toml`: + +1. whether you agree to the [Minecraft EULA](https://aka.ms/MinecraftEULA): only a yes writes `eula=true`; +2. the world's name and an optional seed (an existing world or vanilla server folder is kept and its + `server.properties` imported); +3. the port, 25565 by default; +4. whether to use a whitelist (yes by default, as in vanilla) and who to add; +5. whether to make the first player an operator. + +It then tells you where it found the game and its files. Every question has a flag, so it also runs from a +script: + +```sh +horizon-server init --eula --world survival --seed 12345 --port 25565 --whitelist --player Alex --op Alex --yes +``` + +`--no-whitelist` turns the whitelist off. Since the server runs offline, the players you add get offline UUIDs, +as a vanilla server in offline mode gives them. + +Start the server in the foreground, with the console on your terminal (Ctrl-C stops it cleanly): + +```sh +horizon-server run +``` + +or in the background: + +```sh +horizon-server start +horizon-server status +``` + +```text +Running, up 29 s +TPS 20.0, MSPT 1.0 ms average, 3.1 ms P95 +0 of 20 players, 377 chunks loaded +RAM 1.42 GB, CPU 2 % of a core +``` + +Players join at your computer's address and the port (`192.168.1.20:25565`, or a tailnet name). Every +command takes `--dir FOLDER` to work on a server folder from elsewhere. + +## 4. Settings: `server.toml` + +You edit one file. The server writes vanilla's `server.properties` from it before every start, so the game +reads exactly what a vanilla server reads, and a vanilla server folder works as it is. + +```toml +[server] +motd = "A Minecraft Server" +port = 25565 +bind = "" # listen on every address, or only on this one (server-ip) +max_players = 20 +online_mode = true # not supported yet: the server runs offline and says so +whitelist = true +enforce_whitelist = false +view_distance = 10 +simulation_distance = 10 + +[world] +name = "world" +seed = "" # empty: a random seed on the first start +game_mode = "survival" +difficulty = "easy" +hardcore = false + +# Any other server.properties key, spelled as vanilla spells it: +[properties] +# spawn-protection = 16 + +[engine] +path = "" # the game program; empty: the one beside horizon-server +resources = "" # the prepared game files; empty: resources/ here, else the usual places +restart_on_crash = true + +[backups] +every = "6h" # 30m, 6h, 1d...; "0" turns automatic backups off +keep = 12 # automatic backups kept; backups made by hand are never deleted + +[panel] +bind = "127.0.0.1:8130" # this computer only, or a tailnet address (100.x); "" turns it off +allow_public = false +``` + +The defaults are vanilla 26.3's. Unknown keys and values vanilla would refuse are errors, so a typo stops the +start instead of being ignored. When the game changes a setting itself (`/whitelist on`), the change is copied +back into `server.toml` when it stops, and your comments are kept. Changes to the file apply at the next +restart: there is no live reload yet. + +Already have a vanilla server? Run `horizon-server init` in its folder, or `horizon-server import +server.properties` to write `server.toml` from it. The world, `ops.json`, `whitelist.json` and the ban lists +keep vanilla's names and formats, so going back to vanilla works too. + +## 5. Commands + +```text +horizon-server init first run +horizon-server run in the foreground, with the console; Ctrl-C stops it +horizon-server start | stop | restart in the background (its output goes to logs/supervisor.log) +horizon-server status [--json] up or not, TPS, MSPT, players, chunks, RAM, CPU +horizon-server cmd COMMAND... one console command, and what it answers +horizon-server logs [-f] [-n N] the log; -f follows it +horizon-server op|deop NAME +horizon-server whitelist on|off|list +horizon-server whitelist add|remove NAME +horizon-server backup [NAME] back up now +horizon-server backups list the backups +horizon-server restore BACKUP [--yes] +horizon-server service install|uninstall|print [--system] +horizon-server panel a one-time login link for the web panel +horizon-server import FILE server.toml from a vanilla server.properties +``` + +While the server runs, `op`, `whitelist` and `cmd` go to the game's console, so they act exactly as vanilla's +console commands do. While it's stopped, they edit vanilla's files directly. Any console command works through +`cmd`: `horizon-server cmd ban Griefer`, `horizon-server cmd say Restarting in 5 minutes`. + +The server restarts the game by itself if it crashes: after 5 s, then waiting longer each time, up to 5 +minutes. It keeps the crash report and gives up after 5 crashes in 10 minutes, and `status` says why. + +Coming: `update` and `rollback`, `console` (attach to a server running in the background), `ban` and +`pardon` as their own commands, and `mcp` (an MCP server so an AI assistant can run the server). + +## 6. Web panel + +The panel runs inside `horizon-server` while the server runs. It shows live TPS, MSPT, RAM and CPU graphs for +the last 10 minutes, the players with their ping (and a kick button), the console with a command line, and the +backups (back up now, restore with a confirmation), with Restart and Stop. + +```sh +horizon-server panel +``` + +prints a login link that works once, for 10 minutes. The panel listens on `127.0.0.1:8130`, this computer +only. To reach it from your other devices: + +- put your tailnet address in `[panel] bind` (for example `bind = "100.101.102.103:8130"`), or +- forward the port over SSH: `ssh -L 8130:127.0.0.1:8130 your-server`, then open the link on your computer. + +Any other address, such as `0.0.0.0` or a public IP, is refused unless you set `allow_public = true`, and +even then the panel warns at every start. It has no passwords to leak: whoever can read the server folder can +make a login link, and no one else can. Never put it on the open internet. + +## 7. Backups + +```sh +horizon-server backup before-the-update +horizon-server backups +horizon-server restore before-the-update +``` + +A backup zips the world, vanilla's files and `server.toml` into `backups/`. A running server saves first and +stays up: players don't notice. Automatic backups run on the `[backups] every` schedule while the server runs, +and the oldest automatic ones beyond `keep` are deleted. Backups you make by hand are never deleted. + +`restore` takes a backup's file name, a unique start of it, or the name you gave it. It moves the current +world aside to `backups/replaced-