nix-config-v2/modules/games/homestead/README.md

# 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 the Minecraft port in `modules/machine/krile/configuration.nix`:

```nix
services.homestead.port = 25566;
```

The default is TCP 25565. When `services.homestead.openFirewall = true`, the
opened TCP port follows this setting. Update your router's port forwarding and
connect with `krile:25566` (or your server's address). Voice chat remains on
UDP 24454, matching the pack's `config/voicechat/voicechat-server.properties`.
Rebuild krile to apply the change.

Change memory in the host configuration:

```nix
services.homestead.jvmOpts = "-Xms6G -Xmx12G -XX:+UseG1GC";
```

Declare operators in the host configuration:

```nix
services.homestead.operators = {
  "YourMinecraftName" = {
    uuid = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
    level = 4;
    bypassesPlayerLimit = false;
  };
};
```

Replace the example name and UUID with the player's actual Minecraft account
details. A UUID string also works as a shorthand:
`services.homestead.operators."YourMinecraftName" = "your-player-uuid";`.
It defaults to permission level 4 and does not bypass the player limit.

After rebuilding krile, nix-minecraft generates
`/srv/minecraft/homestead/ops.json` when the server starts. A nonempty operator
list replaces the file on each start, so changes made with `/op` or `/deop` do
not persist across restarts. The default `{ }` leaves `ops.json` unmanaged.

Other server settings use the underlying nix-minecraft options:

```nix
services.minecraft-servers.servers.homestead = {
  serverProperties = {
    max-players = 10;
    white-list = true;
  };
  # Add real player UUIDs here, or manage the whitelist through the console.
  whitelist = { };
};
```

The underlying `serverProperties.server-port` setting can still override
`services.homestead.port`; the opened TCP port follows the effective value.

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.