Hytale Server Docker Container

This repository contains a Docker container for running a Hytale dedicated server with automatic game file downloads.

Features

• Java 25 Alpine Base: Lightweight Alpine Linux with Temurin JDK 25
• Automatic Server Downloads: Uses the official Hytale Downloader CLI to fetch server files
• UDP/QUIC Support: Properly configured for Hytale's QUIC protocol over UDP
• Persistent Storage: Server data, assets, and configurations are preserved across container restarts
• Easy Configuration: Simple environment variables for customization

Prerequisites

• Docker and Docker Compose installed
• At least 4GB of RAM allocated to Docker
• UDP port forwarding configured on your router (default: 5520)
• A Hytale account for server authentication

Quick Start

1. Clone the Repository:

   git clone https://git.merith.xyz/oci/hytale
   cd hytale
   

2. Start the Container:

   docker-compose up -d
   

3. First-Time Setup:

   • The container will automatically download the Hytale Downloader
   • Server files and assets will be downloaded automatically
   • This may take several minutes depending on your connection

4. Authenticate Your Server:

   docker-compose logs -f
   

   Wait for the authentication prompt, then follow the instructions:

   • Visit the URL shown in the logs
   • Enter the device code
   • Authorize the server with your Hytale account

5. Connect to Your Server:

   • Use <your-server-ip>:5520 in the Hytale client
   • If hosting locally, use localhost:5520

Configuration

Environment Variables

Edit the docker-compose.yml file to customize these settings:

Variable	Default	Description
HYTALE_PORT	5520	UDP port the server listens on
ASSETS_PATH	/data/assets/Assets.zip	Path to game assets
SERVER_ARGS	""	Additional arguments for HytaleServer.jar
DOWNLOAD_SERVER	true	Automatically download server files
DOWNLOADER_URL	https://downloader.hytale.com/hytale-downloader.zip	URL for the downloader
STOP_LAUNCH	false	Prevents server start (for debugging)

Additional Server Arguments

You can pass additional arguments to the server via the SERVER_ARGS environment variable:

environment:
  SERVER_ARGS: "--backup --backup-frequency 30 --allow-op"

Common arguments:

• --backup: Enable automatic backups
• --backup-frequency <minutes>: Backup interval (default: 30)
• --allow-op: Allow operator commands
• --auth-mode offline: Run in offline mode (not recommended)

Network Configuration

Port Forwarding

Hytale uses UDP (not TCP) via the QUIC protocol. You must forward UDP port 5520:

Router: Forward UDP port 5520 to your server machine's local IP

Windows Firewall:

New-NetFirewallRule -DisplayName "Hytale Server" -Direction Inbound -Protocol UDP -LocalPort 5520 -Action Allow

Linux (ufw):

sudo ufw allow 5520/udp

Linux (iptables):

sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPT

Directory Structure

hytale/
├── data/
│   ├── hytale/           # Server files and world data
│   │   └── Server/       # HytaleServer.jar and runtime files
│   ├── assets/           # Assets.zip
│   └── downloader/       # Hytale Downloader CLI
├── scripts/              # Container startup scripts
├── docker-compose.yml    # Docker Compose configuration
├── Dockerfile           # Container definition
└── Readme.md            # This file

Building from Source

To build the Docker image locally:

docker build -t hytale-server .

Then update docker-compose.yml to use your local image:

services:
  hytale:
    build: .
    # image: git.merith.xyz/oci/hytale:latest

Troubleshooting

Server Won't Start

1. Check logs:

   docker-compose logs -f
   

2. Verify Java version:

   docker-compose exec hytale java --version
   

   Should show: openjdk 25.0.1

3. Check disk space: Server files require approximately 3-4GB

Can't Connect to Server

1. Verify UDP port forwarding (not TCP)
2. Check firewall rules on both router and server
3. Confirm server is running:

   docker-compose ps
   

4. Test local connection first using localhost:5520

Authentication Issues

• Device code expired: Restart the server and try again quickly
• Too many servers: You're limited to 100 servers per Hytale license
• Need automation: See the Server Provider Authentication Guide

Manual Server Files

If automatic download fails, you can manually copy files from your Hytale Launcher:

Windows:

%appdata%\Hytale\install\release\package\game\latest

Linux:

$XDG_DATA_HOME/Hytale/install/release/package/game/latest

macOS:

~/Library/Application Support/Hytale/install/release/package/game/latest

Copy the Server folder to ./data/hytale/ and Assets.zip to ./data/assets/

Updating the Server

The container will check for updates on restart when DOWNLOAD_SERVER=true:

docker-compose down
docker-compose up -d

System Requirements

• Minimum RAM: 4GB
• Recommended RAM: 8GB+ for multiple players
• CPU: Any modern multi-core processor
• Disk Space: 5GB+ (for server files, assets, and world data)
• Network: Stable internet connection with UDP support

Additional Resources

• Official Hytale Server Manual
• Server Provider Authentication Guide
• Hytale Support

Workflows

This repository includes GitHub Actions workflows for automated builds:

On Commit to Main

• Trigger: Commits to the main branch (excludes tags)
• Purpose: Builds and publishes a Docker image for each commit

On Tag Push

• Trigger: New tag push
• Purpose: Builds and publishes a Docker image tagged as latest

Required Secrets

• OCI_TOKEN: Your OCI registry token
• OCI_USER: Your OCI registry username

License

This project is licensed under the MIT License. See the LICENSE file for details.

Notes

• The Hytale server requires authentication to prevent abuse
• QUIC protocol provides better performance than TCP for game traffic
• Monitor resource usage during gameplay to optimize allocation
• Backup your world data regularly (server has built-in backup features)