ocelus/hytale-docker-server repository overview

⁠Hytale Docker Server

A high-performance, automated Docker image for running Hytale servers with Java 25. This project features automated updates, secure OAuth2 Device Flow authentication, and optimized memory management for low-latency gaming.

⁠Features

• Java 25 Runtime: Leverages the latest JVM for high performance, with support for modern garbage collectors like Generational ZGC.
• Headless OAuth2 Authentication: Utilizes the RFC 8628 Device Flow for a secure, browser-based authentication process without exposing account credentials to the container.
• Automated Server Updates: Automatically checks for and downloads the latest Hytale server version on startup. It also monitors for updates during runtime and notifies players before restarting to apply the update.
• Persistent Sessions: Securely stores and refreshes authentication tokens in a volume, maintaining your server's identity across restarts.
• Alpine Linux Optimized: A lightweight base image with gcompat and automated machine-id generation to ensure full compatibility with native libraries (e.g., Netty/QUIC).
• Security-Focused: Runs as a non-root user within the container for improved security.
• Highly Configurable: Easily manage JVM, server, and game settings using environment variables.

⁠Quick Start

⁠Prerequisites

• Docker⁠
• Docker Compose⁠

⁠Basic Setup

1. Create a docker-compose.yml file in your server directory:

   services:
     hytale:
       image: ocelus/hytale-docker-server:latest
       container_name: hytale
       ports:
         - "5520:5520/udp"
       volumes:
         - ./hytale-data:/game
       restart: unless-stopped
   

   Copy

2. Launch the server:

   docker-compose up
   

   Copy

Deployment Examples

You can find various configuration templates in the samples⁠ directory of this repository. These examples demonstrate different use cases, including High Performance setups using Generational ZGC, Standard community configurations, and Debug modes for development. Each sample is designed to help you quickly deploy a Hytale server tailored to your specific needs.

⁠First-Time Authentication

On the first launch, you need to authorize the server with your Hytale account:

1. Watch the container logs for an authorization message.
2. You will see a URL and a user code, similar to this:

   [HytaleDockerServer] [    2024/01/01 12:00:00        WARN]      [AUTH] ACTION REQUIRED: Please authorize this Hytale server
   [HytaleDockerServer] [    2024/01/01 12:00:00        WARN]      [AUTH] URL  : https://accounts.hytale.com/device
   

   Copy
3. Open the provided URL in a browser and enter the code to grant access.
4. The server will automatically detect the completed authorization, generate session tokens, and finish starting. Authentication tokens will be stored in your volume, so you only need to do this once.

⁠Configuration

⁠Environment Variables

You can customize your server using the following environment variables.

⁠Persistent Volumes

• /game: (can be changed with SERVER_PATH env var) This is the main directory for server files, world data, and authentication tokens. This must be persistent to avoid re-authenticating and save loss on every restart.

⁠Configuration Files

On the first run, the server will generate default configuration files in your volume at <SERVER_PATH>/Server/:

• config.json: Main server settings like name, MOTD, and player limit.
• permissions.json: Manages user and group permissions, including OPs.
• whitelist.json: Manages the server's player whitelist.

These files are automatically managed on startup by the environment variables listed above (SERVER_NAME, OPS_LIST, etc.). You can also edit them directly while the server is offline.

⁠Auto-Update

In addition to automatically using the latest available version when the container starts, the server will check for updates throughout its lifecycle.

When an update is detected, the server will notify players a few minutes before restarting to install the latest version.

⁠Pterodactyl Panel

To use this image with Pterodactyl Panel, you can import the hytale-server-egg.json⁠ file.

1. Navigate to your Pterodactyl Admin area.
2. Go to the "Nests" section.
3. Select the Nest where you want to add the Hytale server.
4. Click "Import Egg" and upload the hytale-server-egg.json file.
5. You can now create a new server using the "HytaleDockerServer" Egg.

⁠Star History