add: krile configuration

modules/games/homestead/README.md

@@ -0,0 +1,105 @@
+# Homestead 2.0 on krile
+
+This module uses the Minecraft NixOS module and Fabric overlay re-exported by
+the existing `nur` flake input. It pins Minecraft 1.20.1, Fabric 0.19.5, Java 17,
+and the [official Homestead 2.0 server pack](https://cozystudios.org/homestead/server-pack/).
+The archive and all eight additional mods listed in its `startserver.sh` are
+downloaded with fixed SHA-256 hashes during the Nix build. The upstream startup
+script is not run.
+
+`modules/machine/krile/configuration.nix` enables the server, accepts the Minecraft
+EULA, and opens TCP 25565 and UDP 24454 (Simple Voice Chat). Forward those ports
+to krile on your router if players connect from outside your network. Players
+need the Homestead 2.0 client pack.
+
+The default heap is 6 GiB initially and 10 GiB maximum. Give the VM additional
+RAM for the OS, native libraries, and filesystem cache; 16 GiB total is a
+reasonable starting point.
+
+## Deploy
+
+On krile, from the repository root:
+
+```bash
+nix eval --raw path:.#nixosConfigurations.krile.config.system.build.toplevel.drvPath
+sudo nixos-rebuild switch --flake path:.#krile
+```
+
+The `path:.` form includes new files before they have been added to Git. Once the
+new module and krile files are tracked, `--flake .#krile` works as usual.
+
+The service starts on boot and restarts after an unexpected exit. Check it with:
+
+```bash
+systemctl status minecraft-server-homestead
+journalctl -u minecraft-server-homestead -f
+```
+
+The console uses nix-minecraft's systemd FIFO. For example, run a command with:
+
+```bash
+sudo sh -c 'echo list > /run/minecraft/homestead.stdin'
+```
+
+Stop the service with `sudo systemctl stop minecraft-server-homestead` so it can
+save the world cleanly.
+
+## Configuration and state
+
+Worlds, player progress, and other runtime state live in
+`/srv/minecraft/homestead`. Back up that directory, particularly `world/`, before
+changing pack versions. The module does not provide automatic backups.
+
+The `mods` directory and server icon are store symlinks. `config`, `defaultconfigs`,
+`kubejs`, `scripts`, and `patchouli_books` are writable copies of the pinned pack,
+recreated on each start and removed on stop by nix-minecraft. Edits to those
+copies do not persist across restarts. World data is not part of those managed
+directories.
+
+Change memory in the host configuration:
+
+```nix
+services.homestead.jvmOpts = "-Xms6G -Xmx12G -XX:+UseG1GC";
+```
+
+Other server settings use the underlying nix-minecraft options:
+
+```nix
+services.minecraft-servers.servers.homestead = {
+  serverProperties = {
+    server-port = 25566;
+    max-players = 10;
+    white-list = true;
+  };
+  # Add real player UUIDs here, or manage the whitelist through the console.
+  whitelist = { };
+};
+```
+
+Changing `server-port` also changes the opened TCP port. Voice chat remains on
+UDP 24454, matching the pack's `config/voicechat/voicechat-server.properties`.
+
+To use this module on another NixOS host, pass `nur` in `specialArgs`, import
+`modules/games/homestead`, set `services.homestead.enable = true`, and set
+`services.minecraft-servers.eula = true` after accepting the EULA. The host must
+allow unfree packages, as the common modules already do for krile.
+
+## Pack updates
+
+For a new release, inspect the official archive and startup script, update the
+archive URL/hash in `package.nix`, update `required-mods.json` with any separate
+downloads and their hashes, and match the Minecraft/Fabric versions in
+`default.nix`. Evaluate and build before switching, then check the startup log.
+The pack is kept fixed at 2.0 until these declarations change.
+
+## Validation
+
+The krile system derivation evaluates, and the pack, Fabric launcher, and
+nix-minecraft setup/cleanup scripts build successfully. A temporary local server
+reached `Done`, started Simple Voice Chat, and exited with status 0 after `stop`,
+saving every dimension. Setup/cleanup was also checked to preserve world data
+and reset managed configs. Multiplayer gameplay was not tested.
+
+The upstream 2.0 pack emits some nonfatal mixin/recipe warnings and an optional
+Falling Trees/Jade integration error during startup; these did not prevent the
+startup and shutdown check from passing.