p0lgs/hytale-server-docker

By p0lgs

•Updated 9 months ago

Hytale dedicated server with Java 25, automatic downloads, and persistent storage

Image

Networking

461

Overview Tags

p0lgs/hytale-server-docker repository overview

⁠Hytale Server Docker

Production-ready Docker image for running Hytale dedicated servers. Built with Java 25 and optimized for Linux VPS deployment.

Docker Hub: p0lgs/hytale-server-docker

⁠Features

Java 25 (Eclipse Temurin/Adoptium)
Automatic server file downloads via official Hytale downloader
Persistent data storage with Docker volumes
UDP/QUIC protocol support
Simple configuration

⁠Requirements

Docker Engine 20.10+
Docker Compose 2.0+
4GB RAM minimum (6-8GB recommended)
Hytale game license

⁠Quick Start

⁠Option A: Use Pre-Built Image (Recommended)

Create docker-compose.yml:

services:
  hytale-server:
    image: p0lgs/hytale-server-docker:latest
    container_name: hytale-server
    restart: unless-stopped

    ports:
      - "5520:5520/udp"

    environment:
      - JAVA_OPTS=-Xms2G -Xmx4G -XX:AOTCache=Server/HytaleServer.aot
      - HYTALE_PORT=5520
      - HYTALE_BIND=0.0.0.0

    volumes:
      - hytale-data:/hytale/Server

    stdin_open: true
    tty: true

volumes:
  hytale-data:

Then start:

docker compose up -d

Skip to Step 3: Authenticate Server below.

⁠Option B: Build from Source

⁠1. Clone and Build

git clone https://github.com/PolGs/hytale-server-docker.git
cd hytale-server-docker
docker compose build

During build, you'll be prompted to authenticate:

=> => # https://oauth.accounts.hytale.com/oauth2/device/verify?user_code=gxETqUPb
=> => # Or visit the following URL and enter the code:
=> => # https://oauth.accounts.hytale.com/oauth2/device/verify
=> => # Authorization code: gxETqUPb
=> => # downloading latest ("release" patchline) to "/hytale/game.zip"
=> => # [=====                                             ] 10.0% (142.5 MB / 1.4 GB)

Action: Visit the URL and enter the code to authenticate. Build continues after authentication (~1.4 GB download, 5-10 minutes).

⁠2. Start Server

docker compose up -d

⁠3. Authenticate Server

Important: This is a second authentication for the running server (different from build auth).

docker attach hytale-server

In the console, run:

/auth login device

Follow the instructions, visit the URL, enter the code, then detach with Ctrl+P, Ctrl+Q.

⁠4. Verify Running

docker compose logs -f

You should see:

[2026/01/13 20:25:00   INFO]   [HytaleServer] Universe ready!
[2026/01/13 20:25:00   INFO]   [HytaleServer] ===============================================================================================
[2026/01/13 20:25:00   INFO]   [HytaleServer]          Hytale Server Booted! [Multiplayer, Fresh Universe] took 22sec 201ms 220us 266ns
[2026/01/13 20:25:00   INFO]   [HytaleServer] ===============================================================================================

⁠Configuration

⁠Environment Variables

Edit docker-compose.yml:

environment:
  - JAVA_OPTS=-Xms4G -Xmx6G  # Adjust memory for your VPS
  - HYTALE_PORT=5520          # Server port
  - HYTALE_BIND=0.0.0.0       # Bind address

⁠Port Configuration

ports:
  - "5520:5520/udp"  # Hytale uses UDP, not TCP!

⁠Data Persistence

All server data is stored in the hytale-data Docker volume:

World saves (universe/)
Server configs (config.json, permissions.json, etc.)
Mods (mods/)
Logs (logs/)

⁠Managing Files

# List files
docker exec hytale-server ls -la /hytale/Server

# View config
docker exec hytale-server cat /hytale/Server/config.json

# Copy file out
docker cp hytale-server:/hytale/Server/config.json ./config.json

# Copy file in
docker cp ./config.json hytale-server:/hytale/Server/config.json
docker compose restart

⁠Installing Mods

docker cp your-mod.jar hytale-server:/hytale/Server/mods/
docker compose restart

⁠Backup

# Backup entire server
docker run --rm --volumes-from hytale-server -v $(pwd):/backup ubuntu \
  tar czf /backup/hytale-backup-$(date +%Y%m%d).tar.gz -C /hytale/Server .

# Backup just worlds
docker exec hytale-server tar czf /tmp/universe.tar.gz -C /hytale/Server/universe .
docker cp hytale-server:/tmp/universe.tar.gz ./universe-backup-$(date +%Y%m%d).tar.gz

⁠VPS Deployment

⁠Initial Setup

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose
sudo apt-get update
sudo apt-get install docker-compose-plugin

# Configure firewall (UDP, not TCP!)
sudo ufw allow 5520/udp
sudo ufw enable

# Create directory and docker-compose.yml
mkdir hytale-server && cd hytale-server
wget https://raw.githubusercontent.com/PolGs/hytale-server-docker/main/docker-compose.yml

# Edit docker-compose.yml to use published image
nano docker-compose.yml
# Change 'build: .' to 'image: p0lgs/hytale-server-docker:latest'

# Start server
docker compose up -d

# Authenticate
docker attach hytale-server
# Run: /auth login device
# Detach: Ctrl+P, Ctrl+Q

⁠Updates

docker compose pull
docker compose up -d

⁠Docker Hub

Published at: p0lgs/hytale-server-docker

⁠Using Pre-Built Image

The image is available on Docker Hub. Simply use:

services:
  hytale-server:
    image: p0lgs/hytale-server-docker:latest
    # ... rest of config

Or pull directly:

docker pull p0lgs/hytale-server-docker:latest

⁠Building and Publishing (For Maintainers)

# Build
docker compose build

# Tag
docker tag hytale-server:latest p0lgs/hytale-server-docker:latest
docker tag hytale-server:latest p0lgs/hytale-server-docker:1.0.0

# Login and push
docker login
docker push p0lgs/hytale-server-docker:latest
docker push p0lgs/hytale-server-docker:1.0.0

⁠Common Commands

# Start
docker compose up -d

# Stop
docker compose down

# Restart
docker compose restart

# Logs
docker compose logs -f

# Console access
docker attach hytale-server

# Detach (without stopping)
Ctrl+P, Ctrl+Q

# Resource usage
docker stats hytale-server

⁠Troubleshooting

⁠Players Can't Connect

Check firewall allows UDP port 5520:

sudo ufw status
sudo ufw allow 5520/udp

Verify port mapping uses /udp not /tcp in docker-compose.yml
Ensure server authentication completed: /auth login device

⁠High Memory Usage

Hytale's default view distance (384 blocks) uses significant RAM. To reduce:

docker cp hytale-server:/hytale/Server/config.json ./config.json
# Edit view distance
docker cp ./config.json hytale-server:/hytale/Server/config.json
docker compose restart

Consider the Nitrado:PerformanceSaver plugin for dynamic view distance adjustment.

⁠Server Won't Start

Check logs:

docker compose logs -f

Common issues:

Insufficient memory (reduce -Xmx in JAVA_OPTS)
Authentication not completed
Port already in use

⁠Important Notes

QUIC Protocol: Hytale uses QUIC over UDP. All firewall rules and port forwarding must be UDP, not TCP.
Authentication: Two separate authentications required - one during build, one for running server.
Server Limit: 100 servers per Hytale license. For more, purchase additional licenses or apply for Server Provider status.
Protocol Version: Client and server must match versions exactly. Update Docker image when Hytale updates.

⁠Resources

⁠License

Hytale and all related assets are property of Hypixel Studios. This Docker image is provided as-is for running Hytale servers.

⁠Support

GitHub Issues: Report problems⁠
Hytale Support: https://support.hytale.com⁠

Tag summary

Recent tags

Content type

Image

Digest

sha256:543da5826…

Size

1.5 GB

Last updated

9 months ago

docker pull p0lgs/hytale-server-docker:2026.01.17-4b0f30090