diff --git a/Makefile b/Makefile index 0750fb2..ce29c93 100644 --- a/Makefile +++ b/Makefile @@ -2,16 +2,12 @@ SHELL := /usr/bin/env bash MAKEFLAGS += --no-builtin-rules --warn-undefined-variables -VERBOSE ?= 0 -NO_COLOR ?= 0 - COMPOSE := docker compose -f docker-compose.yml SERVICE ?= hytale-server -CMD ?= list WAIT_TIMEOUT ?= 300 # ---- Targets --------------------------------------------------------------- -.PHONY: build up down restart status logs in update update-hytale-downloader auth attach help +.PHONY: build up down restart status logs in update update-hytale-downloader attach help ##@ Container build: ## Build server docker image diff --git a/README.md b/README.md index c770f07..9b53927 100644 --- a/README.md +++ b/README.md @@ -1,147 +1,99 @@ -Docker setup for running the Hytale dedicated server. +Hytale dedicated server in Docker. The container supports automatic updates on the server startup via the official Hytale Downloader CLI and runs `HytaleServer.jar` with custom launch options based on environment -This container downloads/updates the server on startup using the official Hytale Downloader CLI, then starts `HytaleServer.jar` with the options configured via environment variables. +## Quick start -To use the `docker-compose.yml` file you'll need to first copy the ยด.env.example` to `.env` and work with `docker-compose up -d` after that. +Copy `.env.example` to `.env` and edit as needed. +On linux can be done via: +```bash +cp .env.example .env +``` -Once the server runs you have to authorize with Hytale so client connects work. -Therefore you have to attach to the container `docker attach CONTAINER_NAME` if you use the default docker-compose.yml it's `hytale` and run `auth login device` you will the an authentication link navigating you to the hytale login page, once authenticated clients can connect. To save the authorization so you dont have to do it every restart you can run `auth persistence Encrypted` so it gets saved to an encrypted file. +Start the server with `docker compose up -d` or `make up` -The command `auth persistence Encrypted` needs the hardware id to be present, see the docker-compose.yml and uncomment the mapping of the hardware id (if your host system supports it, not every linux distro has the machine-id at the same location) +Follow logs with `docker compose logs -f` or `make logs` -Thanks to @aASDa213ASD this image brings an optional makefile script giving you easy access to commands like build, up, down, restart, status, logs, in, attach, update, update-hytale-downloader through docker-compose commands for easy access. +## Authentication -## Ports +Attach to the running container and authenticate using the server console: -- UDP `5520` (default) +```bash +docker attach hytale +auth login device +``` -## Environment variables +To persist authentication across restarts, enable machine ID access in `docker-compose.yml` and run: -These are set in `docker-compose.yml`. You can change them there or move them into a `.env` and reference them from Compose. +```bash +auth persistence Encrypted +``` -### Server / networking +## Compose setup -- `HYTALE_PORT` (default: `5520`) - - Server port. -- `BIND_ADDR` (default: `0.0.0.0`) - - Bind address. +`docker-compose.yml` uses: -### Assets / auth +- Container name `hytale` +- UDP port `5520` +- Named volume `hytale-data` mounted at `/hytale` +- `.env` file for configuration -- `ASSETS_PATH` (default: `/hytale/Assets.zip`) - - Path to the server assets zip inside the container. -- `AUTH_MODE` (default: `authenticated`) - - Authentication mode passed to the server. +## Makefile helpers -#### Server Provider Authentication +The Makefile wraps common `docker compose` commands: -You can pass auth tokens to the server. These are **not set by default** and the startup script only adds the flags when the variables are present: +`build`, `up`, `down`, `restart`, `status`, `logs`, `in`, `attach`, `update`, `update-hytale-downloader` -- `SESSION_TOKEN` (optional) - - Adds `--session-token ""` -- `IDENTITY_TOKEN` (optional) - - Adds `--identity-token ""` -- `OWNER_UUID` (optional) - - Adds `--owner-uuid ""` +Run `make` for descriptions -### Updates +## Environment variables -- `ENABLE_AUTO_UPDATE` (default: `true`) - - If `true`, runs `./hytale-downloader` on every container start. -- `SKIP_DELETE_ON_FORBIDDEN` (default: `false`) - - If `true`, the startup script will **not** delete `~/.hytale-downloader-credentials.json` when it detects a `403 Forbidden`. +Defaults are defined in [Dockerfile](Dockerfile) and [.env.example](.env.example) and can be overridden in your `.env` file -### AOT cache +### Server and networking -- `USE_AOT_CACHE` (default: `true`) - - If `true` and `/hytale/Server/HytaleServer.aot` exists, adds `-XX:AOTCache=HytaleServer.aot`. +- `HYTALE_PORT` (default `5520`): UDP port to listen on +- `BIND_ADDR` (default `0.0.0.0`): bind address -### Flags +### Assets and auth mode -- `ACCEPT_EARLY_PLUGINS` (default: `false`) - - Adds `--accept-early-plugins`. -- `ALLOW_OP` (default: `false`) - - Adds `--allow-op`. -- `DISABLE_SENTRY` (default: `false`) - - Adds `--disable-sentry`. +- `ASSETS_PATH` (default `/hytale/Assets.zip`): assets zip path in the container +- `AUTH_MODE` (default `authenticated`): `authenticated`, `offline`, or `insecure` -### Backups +Optional server provider tokens (only passed when set in `.env.` file): + +- `SESSION_TOKEN`: adds `--session-token` +- `IDENTITY_TOKEN`: adds `--identity-token` +- `OWNER_UUID`: adds `--owner-uuid` + +### Updates + +- `ENABLE_AUTO_UPDATE` (default `true`): download and update the server on container start +- `SKIP_DELETE_ON_FORBIDDEN` (default `false`): keep downloader credentials on `403 Forbidden` + +The downloader binary also checks for its own updates on every start. -- `BACKUP_ENABLED` (default: `false`) - - If `true`, adds backup arguments. -- `BACKUP_DIR` (default: `/hytale/backups`) - - Backup output directory inside the container. -- `BACKUP_FREQUENCY` (default: `30`) - - Backup frequency. - -### Java memory - -- `JAVA_XMS` (default: `4G`) - - Adds `-Xms`. -- `JAVA_XMX` (default: `4G`) - - Adds `-Xmx`. -- `JAVA_CMD_ADDITIONAL_OPTS` (optional) - - Appends additional JVM args to the `java` command. - - -### Additional server options - -- `HYTALE_ADDITIONAL_OPTS` (default: empty) - - Appends additional **HytaleServer.jar** options after all other generated args. - - Usable for server options which are not currently available as env variables. - -Using `HYTALE_ADDITIONAL_OPTS` you can use any of the below commands to add it to the server startup command. It's recommended not to duplicate commands either by adding them multiple times or using the above env variables because of possible unknown issues. - -Commands available as seen with `java -jar HytaleServer.jar --help`: - -| Option | Description | -|---|---| -| `--accept-early-plugins` | You acknowledge that loading early plugins is unsupported and may cause stability issues. | -| `--allow-op` | | -| `--assets ` | Asset directory (default: ../HytaleAssets) | -| `--auth-mode ` | Authentication mode (default: AUTHENTICATED) | -| `-b, --bind ` | Port to listen on (default: 0.0.0.0/0.0.0.0:5520) | -| `--backup` | | -| `--backup-dir ` | | -| `--backup-frequency ` | (default: 30) | -| `--backup-max-count ` | (default: 5) | -| `--bare` | Runs the server bare, e.g. without loading worlds, binding to ports or creating directories. (Note: Plugins will still be loaded and may not respect this flag.) | -| `--boot-command ` | Runs command on boot. If multiple commands are provided they are executed synchronously in order. | -| `--client-pid ` | | -| `--disable-asset-compare` | | -| `--disable-cpb-build` | Disables building of compact prefab buffers | -| `--disable-file-watcher` | | -| `--disable-sentry` | | -| `--early-plugins ` | Additional early plugin directories to load from | -| `--event-debug` | | -| `--force-network-flush ` | (default: true) | -| `--generate-schema` | Causes the server generate schema, save it into the assets directory and then exit | -| `--help` | Print's this message. | -| `--identity-token ` | Identity token (JWT) | -| `--log ` | Sets the logger level. | -| `--migrate-worlds ` | Worlds to migrate | -| `--migrations ` | The migrations to run | -| `--mods ` | Additional mods directories | -| `--owner-name ` | | -| `--owner-uuid ` | | -| `--prefab-cache ` | Prefab cache directory for immutable assets | -| `--session-token ` | Session token for Session Service API | -| `--shutdown-after-validate` | Automatically shutdown the server after asset and/or prefab validation. | -| `--singleplayer` | | -| `-t, --transport ` | Transport type (default: QUIC) | -| `--universe ` | | -| `--validate-assets` | Causes the server to exit with an error code if any assets are invalid. | -| `--validate-prefabs [ValidationOption]` | Causes the server to exit with an error code if any prefabs are invalid. | -| `--validate-world-gen` | Causes the server to exit with an error code if default world gen is invalid. | -| `--version` | Prints version information. | -| `--world-gen ` | World gen directory | +### JVM and server flags + +- `JAVA_XMS` (default `4G`): initial heap size +- `JAVA_XMX` (default `4G`): max heap size +- `JAVA_CMD_ADDITIONAL_OPTS`: extra JVM options appended to `java` +- `USE_AOT_CACHE` (default `true`): add `-XX:AOTCache=HytaleServer.aot` if present +- `ACCEPT_EARLY_PLUGINS` (default `false`): add `--accept-early-plugins` +- `ALLOW_OP` (default `false`): add `--allow-op` +- `DISABLE_SENTRY` (default `false`): add `--disable-sentry` +- `HYTALE_ADDITIONAL_OPTS`: additional server options appended at the end + +### Backups +- `BACKUP_ENABLED` (default `false`): enable backups +- `BACKUP_DIR` (default `/hytale/backups`): backup output directory +- `BACKUP_FREQUENCY` (default `30`): minutes between backups ## Notes -- If the downloader fails with a `403 Forbidden`, the startup script clears `~/.hytale-downloader-credentials.json` and retries on next start. +- If the downloader fails with `403 Forbidden`, the startup script may remove `~/.hytale-downloader-credentials.json` unless `SKIP_DELETE_ON_FORBIDDEN=true`. +- The server data lives in the `hytale-data` volume at `/hytale`. -## Docs +## Links - Server Provider Authentication Guide: https://support.hytale.com/hc/en-us/articles/45328341414043-Server-Provider-Authentication-Guide - Hytale Server Manual: https://support.hytale.com/hc/en-us/articles/45326769420827-Hytale-Server-Manual