hytale-server-setup/README.md

Hytale Server Setup

Automated setup script for Hytale dedicated servers on Debian/Ubuntu Linux systems.

After finishing this setup, it's recommended to setup Docker. See DOCKER.md for instructions.

Features

• Installs Adoptium JDK (recommended by Hytale)
• Downloads and configures the Hytale server
• Creates a systemd service for automatic startup
• Configures UFW firewall rules
• Colored terminal output for better visibility
• Automatic cleanup on installation failure
• Built-in update mechanism with automatic backups

Requirements

• OS: Debian or Ubuntu (x86_64 only)
• Permissions: Root access required
• Network: Internet connection for downloading packages
• Account: Valid Hytale account for authentication

Quick Start

# Download and run the script
wget https://raw.githubusercontent.com/Edu4rdSHL/hytale-server-setup/main/hytale-setup.sh
chmod +x hytale-setup.sh
sudo ./hytale-setup.sh

CRITICAL: Authentication Setup

After the server starts for the first time and you see the "Hytale Server Booted!" message, you MUST run the following commands in the server console:

/auth persistence Encrypted
/auth login device

WARNING: If you skip these commands or enter them incorrectly, the server will not function properly.

After completing authentication, stop the server with Ctrl+C and start it normally using:

# If systemd is available (recommended)
sudo systemctl start hytale-server.service

# Or manually
cd /opt/Hytale/Server && java -jar HytaleServer.jar --assets Assets.zip

Configuration

The script supports environment variables for customization:

Variable	Default	Description
DISTRO_VERSION	trixie	Debian/Ubuntu codename for Adoptium repository
ADOPTIUM_JDK_VERSION	25	JDK version to install
INSTALL_PATH	/opt/Hytale	Server installation directory
HYTALE_SERVER_VERSION	release	Version to download (release, pre-release, or specific version)
FIREWALL_PORT	5520/udp	Port to open in UFW
LOCAL_HYTALE_SERVER_ZIP	(empty)	Path to local server zip (skips downloads)

Example with custom configuration

sudo INSTALL_PATH=/home/hytale/server HYTALE_SERVER_VERSION=pre-release ./hytale-setup.sh

Memory Configuration (Important!)

For optimal server performance, you should configure the Java memory settings (-Xms and -Xmx) based on your server's available RAM:

• -Xms: Initial heap size (minimum memory allocated at startup)
• -Xmx: Maximum heap size (maximum memory the JVM can use)

Recommended Settings

Server RAM	-Xms	-Xmx	Example
4 GB	1024m	2560m	-Xms1024m -Xmx2560m
8 GB	2048m	6144m	-Xms2048m -Xmx6144m
16 GB	4096m	12288m	-Xms4096m -Xmx12288m
32 GB	8192m	24576m	-Xms8192m -Xmx24576m

Tip: Always leave some RAM for the operating system and other processes. A good rule of thumb is to allocate 75-80% of your total RAM to -Xmx.

Applying Memory Settings

If using the systemd service, edit /etc/systemd/system/hytale-server.service:

sudo systemctl edit hytale-server.service

And add/modify the ExecStart line to include memory flags:

[Service]
ExecStart=
ExecStart=/usr/bin/java -Xms2048m -Xmx6144m -jar /opt/Hytale/Server/HytaleServer.jar --assets /opt/Hytale/Server/Assets.zip

Then reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart hytale-server.service

If running manually:

cd /opt/Hytale/Server && java -Xms2048m -Xmx6144m -jar HytaleServer.jar --assets Assets.zip

Systemd Service

If systemd is available, the script creates a service at /etc/systemd/system/hytale-server.service:

# Start the server
sudo systemctl start hytale-server.service

# Stop the server
sudo systemctl stop hytale-server.service

# Check status
sudo systemctl status hytale-server.service

# View logs
sudo journalctl -u hytale-server.service -f

Updating the Server

The script includes a built-in update mechanism that:

• Checks your current server version
• Compares it with the latest available version
• Creates a backup of your current files before updating
• Updates only the necessary server files (preserves your configuration)

Check for and apply updates

sudo ./hytale-setup.sh --update
# or
sudo ./hytale-setup.sh -u

What gets updated

The update process replaces only the required server files that need updating:

• Server/HytaleServer.jar
• Server/HytaleServer.aot
• Server/Assets.zip

Your server configuration, world data, and other custom files are preserved.

Backups

Before each update, a backup is automatically created at:

/opt/Hytale/backups/YYYYMMDD_HHMMSS/

To restore a backup, simply copy the files back:

sudo systemctl stop hytale-server.service # adjust the stop command if you're using docker/podman
sudo cp /opt/Hytale/backups/YYYYMMDD_HHMMSS/* /opt/Hytale/Server/
sudo systemctl start hytale-server.service # adjust the start command if you're using docker/podman

Connecting to Your Server

After setup, players can connect using:

• Remote/Public IP: your_server_ip:5520
• Local: localhost:5520

Make sure port 5520/udp is open on your firewall and any cloud provider security groups.

Troubleshooting

Server fails to start after reboot

Make sure you ran the /auth commands during initial setup. If not, you may need to re-authenticate.

JDK installation fails

Try setting a different DISTRO_VERSION that matches your system:

sudo DISTRO_VERSION=bookworm ./hytale-setup.sh  # Debian 12
sudo DISTRO_VERSION=jammy ./hytale-setup.sh     # Ubuntu 22.04

Port already in use

Check if another process is using port 5520:

sudo lsof -i :5520

License

This project is open source, licensed under the MIT License. Feel free to contribute or submit issues!