How to Create a Hytale Server with Docker (2026 Guide)

Docker provides a production-ready, containerized solution for hosting Hytale servers with simplified deployment, automatic updates, and easy scalability. This guide uses a pre-built Docker image that handles all server dependencies, making it perfect for VPS hosting and cloud deployments.

What you'll learn: Docker installation, using pre-built images from Docker Hub, Docker Compose configuration, persistent data management, VPS deployment, backups, and production best practices.

Docker Hub Image GitHub Repository

Why Use Docker for Hytale Servers?

🚀 Easy Deployment

One-command setup with pre-configured Java 25, server files, and dependencies. No manual installation needed.

🔄 Automatic Updates

Pull the latest image to update your server. No need to manually download and configure new versions.

💾 Persistent Storage

Docker volumes ensure your world data, configs, and mods survive container restarts and updates.

🔒 Isolated Environment

Containers provide isolation from your host system, improving security and preventing conflicts.

Requirements

▸Docker Engine: 20.10 or higher
▸Docker Compose: 2.0 or higher
▸RAM: 4GB minimum (6-8GB recommended)
▸Storage: 5GB+ for server files and world data
▸Hytale License: Valid Hytale game license for authentication

Step 1: Install Docker

Linux (Ubuntu/Debian)

# Download and run Docker installation script
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

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

# Add your user to docker group (optional, avoids sudo)
sudo usermod -aG docker $USER
newgrp docker

Windows / macOS

1.
Download Docker Desktop:
https://www.docker.com/products/docker-desktop
2.
Install Docker Desktop and restart your computer
3.
Launch Docker Desktop and wait for it to start

Verify Installation

docker --version
docker compose version

You should see version numbers for both commands.

Step 2: Quick Start with Pre-Built Image

Recommended: Using the pre-built image from Docker Hub is the fastest way to get started. No build process required!

Docker Hub: p0lgs/hytale-server-docker →

Create Project Directory

mkdir hytale-server && cd hytale-server

Create docker-compose.yml

Create a file named docker-compose.yml with this content:

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:

Step 3: Start Your Server

Launch the Container

# Pull image and start server
docker compose up -d

The -d flag runs the container in detached mode (background).

Check Status

# View logs
docker compose logs -f

# Check container status
docker ps

Press Ctrl+C to exit logs view.

Step 4: Authenticate Your Server

Important: Server authentication is required and separate from the build authentication. You must complete this step for players to connect.

Access Server Console

# Attach to the running container
docker attach hytale-server

In the server console, type:

/auth login device

You'll see output like:

===================================================================
DEVICE AUTHORIZATION
===================================================================
Visit: https://accounts.hytale.com/device
Enter code: ABCD-1234
===================================================================

1.
Visit the URL in your browser
2.
Enter the authorization code
3.
Complete authentication in your browser
4.
Return to console—you should see "Authentication successful!"

Detach from Console

To exit the console without stopping the server, press:

Ctrl+P, Ctrl+Q

This key combination detaches from the container while keeping it running.

Step 5: Configure Firewall & Network

Critical: Hytale uses QUIC over UDP. All firewall rules must specify UDP, not TCP!

Linux (UFW)

sudo ufw allow 5520/udp
sudo ufw enable
sudo ufw status

Linux (iptables)

sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPT
sudo iptables-save | sudo tee /etc/iptables/rules.v4

Cloud VPS (AWS, DigitalOcean, etc.)

Add an inbound rule in your provider's firewall/security group:

Protocol: UDP

Port: 5520

Source: 0.0.0.0/0 (allow all)

Configuration Options

Memory Allocation

Adjust JAVA_OPTS in docker-compose.yml:

environment:
- JAVA_OPTS=-Xms4G -Xmx6G -XX:AOTCache=Server/HytaleServer.aot

-Xms: Minimum heap (starting memory)
-Xmx: Maximum heap (memory limit)

Custom Port

Change the server port:

ports:
- "25565:25565/udp" # External:Internal

environment:
- HYTALE_PORT=25565

Auto-Restart Policy

Control container restart behavior:

restart: unless-stopped # Restart unless manually stopped
# restart: always # Always restart
# restart: no # Never restart
# restart: on-failure # Only restart on crash

Data Management

Persistent Storage

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

▸World saves (universe/)
▸Configuration files (config.json, permissions.json)
▸Mods (mods/)
▸Logs (logs/)

Access Server Files

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

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

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

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

Install Mods

# Copy mod to server
docker cp your-mod.jar hytale-server:/hytale/Server/mods/

# Restart to load mod
docker compose restart

Backups

Full Server Backup

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 .

Creates a compressed backup in your current directory.

Backup Just World Data

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

Common Docker Commands

# Start server
docker compose up -d

# Stop server
docker compose down

# Restart server
docker compose restart

# View logs (live)
docker compose logs -f

# Access console
docker attach hytale-server
# (Detach: Ctrl+P, Ctrl+Q)

# Check resource usage
docker stats hytale-server

# Update to latest version
docker compose pull
docker compose up -d

Complete VPS Deployment Guide

Full Setup Script

Here's a complete deployment script for a fresh VPS:

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

# Configure firewall
sudo ufw allow 5520/udp
sudo ufw enable

# Create server directory
mkdir -p ~/hytale-server && cd ~/hytale-server

# Download docker-compose.yml
wget https://raw.githubusercontent.com/PolGs/hytale-server-docker/main/docker-compose.yml

# Edit 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

Troubleshooting

Players Can't Connect

Check:

▸Port mapping uses /udp not /tcp
▸Firewall allows UDP port 5520: sudo ufw status
▸Server authentication completed
▸Container is running: docker ps

Container Crashes (Out of Memory)

Check logs with docker compose logs. If you see OOM errors, increase -Xmx in JAVA_OPTS. For 10+ players, use at least 8GB.

Permission Denied Errors

If you get permission errors, add your user to the docker group: sudo usermod -aG docker $USER, then log out and back in.

Data Lost After Update

Ensure you're using Docker volumes (not bind mounts) for persistent storage. Check your docker-compose.yml has volumes: section defined.

Advanced: Build from Source

Optional: Only build from source if you want to customize the Dockerfile or contribute to development.

# Clone repository
git clone https://github.com/PolGs/hytale-server-docker.git
cd hytale-server-docker

# Build image (requires authentication during build)
docker compose build

# Start server
docker compose up -d

# Authenticate server
docker attach hytale-server
# /auth login device

Note: Building requires authentication (~1.4GB download, 5-10 minutes).

Your Docker Server is Ready!

You now have a production-ready, containerized Hytale server running with Docker. Enjoy easy updates, persistent data storage, and simple management. Share your server IP to let players connect, and don't forget to list it on Hytale Servers Space to grow your community!

List Your Server View on GitHub →

Additional Resources

▸
Docker Hub Image: p0lgs/hytale-server-docker
▸
GitHub Repository: PolGs/hytale-server-docker
▸
Linux Server Setup Guide
▸
Windows Server Setup Guide