Sign inSign up

everhytale/hytale-server

By everhytale

•Updated 9 months ago

Optimized Hytale dedicated server with Java 25 and multi-arch support

Image
0

4.3K

everhytale/hytale-server repository overview

ā šŸŽ® Hytale Dedicated Server - Docker Image

Build Docker Pulls License: MIT

An optimized, production-ready Docker image for running Hytale dedicated servers.

ā āš ļø Disclaimer

This is an unofficial community project. Hytale is a trademark of Hypixel Studios.

ā šŸ“¦ Image Tags

All images use SemVer with Hytale version as build metadata:

TagDescriptionExample
latestLatest stable releaseeverhytale/hytale-server:latest
X.Y.Z+HYTALE_VERSIONFull version (image + Hytale)1.0.0+2026.01.15-c04fdfe10
HYTALE_VERSIONLatest image for this Hytale version2026.01.15-c04fdfe10
X.YMinor version (latest patch)1.0
XMajor version (latest minor)1
rcLatest release candidaterc
devLatest development builddev
edgeLatest build from main branchedge
⁠Automated Builds

The CI/CD pipeline automatically checks for new Hytale versions every 12 hours. When a new version is detected, a new Docker image is built and pushed with the appropriate tags.

⁠✨ Features

  • šŸ—ļø Multi-architecture support: linux/amd64 and linux/arm64
  • ā˜• Java 25 (Eclipse Temurin)
  • šŸ” Token-based authentication via OAuth2 Device Flow
  • šŸ“¦ Automated builds via GitHub Actions (checks every 12h for new Hytale versions)
  • šŸ”„ Automatic token refresh scripts included
  • šŸ›”ļø Security-first: runs as non-root user
  • šŸ“Š Health checks built-in

ā šŸ“‹ Requirements

  • Docker 20.10+ and Docker Compose v2
  • Minimum 4GB RAM (8GB recommended)
  • Hytale account with server access
  • UDP port 5520 available (Hytale uses QUIC protocol)

ā šŸš€ Quick Start

⁠Option 1: Use Pre-built Image
# Latest stable release
docker pull everhytale/hytale-server:latest

# Specific Hytale version (latest image for that version)
docker pull everhytale/hytale-server:2026.01.15-c04fdfe10

# Specific image + Hytale version
docker pull everhytale/hytale-server:1.0.0+2026.01.15-c04fdfe10

# Create data directory
mkdir -p ./data

# Run the server
docker run -d \
  --name hytale-server \
  -p 5520:5520/udp \
  -v ./data:/server \
  -v /etc/machine-id:/etc/machine-id:ro \
  -e MIN_MEMORY=4G \
  -e MAX_MEMORY=8G \
  everhytale/hytale-server:latest
⁠Option 2: Using Docker Compose
  1. Clone the repository

    git clone https://github.com/everhytale/dockers.git
    cd dockers/dockers/hytale-server
    
  2. Authenticate with Hytale

    chmod +x scripts/hytale-auth.sh
    ./scripts/hytale-auth.sh
    

    Follow the instructions to complete OAuth2 authentication.

  3. Start the server

    docker-compose up -d
    
  4. View logs

    docker-compose logs -f
    

ā šŸ”§ Configuration

⁠Environment Variables
VariableDefaultDescription
MIN_MEMORY4GMinimum JVM heap size
MAX_MEMORY8GMaximum JVM heap size
SERVER_PORT5520Server port (UDP)
SERVER_BIND0.0.0.0Bind address
AUTH_MODEauthenticatedAuthentication mode (authenticated or offline)
DISABLE_SENTRYfalseDisable crash reporting (for development)
USE_AOT_CACHEtrueUse AOT cache for faster startup
BACKUP_ENABLEDfalseEnable automatic backups (--backup)
BACKUP_DIR/server/backupsBackup directory path (--backup-dir)
BACKUP_FREQUENCY30Backup interval in minutes (--backup-frequency)
BACKUP_MAX_COUNT5Maximum number of backups to keep (--backup-max-count)
⁠Token Authentication
VariableDescription
OWNER_NAMEServer owner username
OWNER_UUIDServer owner UUID
SESSION_TOKENSession token from OAuth2
IDENTITY_TOKENIdentity token (JWT)

ā šŸ“ Directory Structure

The image separates game files (read-only) from server data (persistent):

/opt/hytale-server/          # Game files (read-only, in image)
ā”œā”€ā”€ HytaleServer.jar         # Server executable
ā”œā”€ā”€ HytaleServer.aot         # AOT cache (faster startup)
└── Assets.zip               # Game assets

/server/                     # Server data (persistent, mounted volume)
ā”œā”€ā”€ universe/                # Worlds and player data
ā”œā”€ā”€ mods/                    # Installed mods
ā”œā”€ā”€ logs/                    # Server logs
ā”œā”€ā”€ .cache/                  # Optimized cache
ā”œā”€ā”€ auth.enc                 # Encrypted authentication credentials
ā”œā”€ā”€ config.json              # Server configuration
ā”œā”€ā”€ permissions.json         # Permissions
ā”œā”€ā”€ whitelist.json           # Whitelisted players
└── bans.json                # Banned players

Key benefits:

  • Game files are immutable and versioned with the image
  • All server data is in a single /server volume
  • Easy to backup: just backup the /server directory
  • Easy to migrate: copy the data folder to a new server

ā šŸ”’ Authentication

Hytale servers require authentication to communicate with Hytale's service APIs. There are two methods:

  1. Start the server and attach to console:

    docker-compose up -d
    docker attach hytale-server
    
  2. Authenticate via device code:

    /auth login device
    

    You'll see output like:

    ===================================================================
    DEVICE AUTHORIZATION
    ===================================================================
    Visit: https://accounts.hytale.com/device
    Enter code: ABCD-1234
    ===================================================================
    
  3. Complete authorization in your browser, then wait for confirmation:

    Authentication successful! Use '/auth status' to view details.
    WARNING: Credentials stored in memory only - they will be lost on restart!
    
  4. Persist credentials to survive container restarts:

    /auth persistence Encrypted
    

    Output:

    Swapped credential store to: EncryptedAuthCredentialStoreProvider
    
  5. Detach from container (without stopping it): Press Ctrl+P then Ctrl+Q

⁠The auth.enc File

When you use /auth persistence Encrypted, Hytale creates an encrypted file auth.enc that stores your authentication credentials. This file:

  • Is encrypted using your machine's hardware ID
  • Persists across server restarts
  • Must be mounted as a volume to survive container recreation

Important: To use encrypted persistence in Docker, you must:

  1. Mount the machine-id from the host
  2. Mount the auth.enc file

Quick setup with local files (recommended):

# Create data directory and empty auth.enc
mkdir -p ./data
touch ./data/auth.enc

# Use the local configuration
docker-compose -f docker-compose.local.yml up -d

Or add to your docker-compose.yml:

volumes:
  - /etc/machine-id:/etc/machine-id:ro
  - /var/lib/dbus/machine-id:/var/lib/dbus/machine-id:ro
  - ./data/auth.enc:/server/auth.enc  # Persist auth credentials
⁠Persistence Types
TypeCommandDescription
Memory/auth persistence MemoryCredentials lost on restart (default)
Encrypted/auth persistence EncryptedCredentials saved to auth.enc, encrypted with machine-id
⁠Method 2: Token Authentication via Environment Variables

Use the included scripts to obtain tokens programmatically:

# Initial authentication
./scripts/hytale-auth.sh

# Refresh expired tokens
./scripts/hytale-refresh.sh
docker-compose restart

This method sets environment variables (SESSION_TOKEN, IDENTITY_TOKEN) that are passed to the server at startup.

ā šŸ—ļø Building from Source

⁠Prerequisites

You'll need Hytale credentials stored as a credentials file.

⁠Local Build (New Method)

Game files are now downloaded separately before building:

cd dockers/hytale-server

# 1. Create credentials file (or use scripts/hytale-auth.sh)
echo '{"access_token":"...", "refresh_token":"..."}' > .hytale-downloader-credentials.json

# 2. Download game files
./scripts/download-game.sh

# 3. Build the image with HYTALE_VERSION
HYTALE_VERSION=$(cat game-files/.version) docker compose -f docker-compose.build.yml build

# 4. Run the server
docker compose -f docker-compose.build.yml up -d

The download-game.sh script will:

  • Download the Hytale downloader
  • Download game files using your credentials
  • Extract them to ./game-files/
  • Save the version to ./game-files/.version
⁠Multi-architecture Build
# Build for multiple platforms
HYTALE_VERSION=$(cat game-files/.version) docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --build-context game=./game-files \
  --build-arg HYTALE_VERSION=$HYTALE_VERSION \
  -t everhytale/hytale-server:local \
  --push .

Security Note: Credentials are never included in the Docker image. Game files are downloaded separately before the build.

ā šŸ”„ GitHub Actions CI/CD

The repository includes a GitHub Actions workflow that:

  1. Checks for new Hytale versions every 12 hours
  2. Builds multi-architecture images (amd64, arm64)
  3. Pushes to Docker Hub and GitHub Container Registry
  4. Uses SemVer tags with Hytale version as build metadata
  5. Runs security scans with Trivy
⁠Tag Examples

For a release v1.0.0 with Hytale version 2026.01.15-c04fdfe10:

  • 1.0.0+2026.01.15-c04fdfe10 (full version)
  • 2026.01.15-c04fdfe10 (Hytale version, latest image)
  • 1.0.0, 1.0, 1 (SemVer)
  • latest
⁠Required Secrets
SecretDescription
HYTALE_CREDENTIALSRequired. JSON credentials for the Hytale downloader
DOCKERHUB_USERNAMEOptional. Docker Hub username
DOCKERHUB_TOKENOptional. Docker Hub access token
⁠Setting up Secrets
  1. Go to your repository settings
  2. Navigate to Secrets and variables → Actions
  3. Add the required secrets

⁠🌐 Network Configuration

Hytale uses the QUIC protocol over UDP (not TCP).

⁠Firewall Rules
# Linux (ufw)
sudo ufw allow 5520/udp

# Linux (iptables)
sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPT

# Windows PowerShell
New-NetFirewallRule -DisplayName "Hytale Server" -Direction Inbound -Protocol UDP -LocalPort 5520 -Action Allow
⁠Port Forwarding

If behind a router, forward UDP port 5520 to your server. TCP is not required.

ā šŸ”§ Troubleshooting

⁠Machine-ID Error

If you see "Failed to get Hardware UUID":

# docker-compose.yml
volumes:
  - /etc/machine-id:/etc/machine-id:ro

Or use memory-based persistence:

/auth persistence Memory
⁠Token Expired

Refresh tokens using the included script:

./scripts/hytale-refresh.sh
docker-compose restart
⁠Server Won't Start
  1. Check logs: docker-compose logs -f
  2. Verify Assets.zip exists
  3. Ensure minimum 4GB RAM available

ā šŸ“ License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

ā šŸ¤ Contributing

Contributions are welcome! Please read our Contributing Guidelines⁠ before submitting a PR.

ā šŸ“š Resources

Tag summary

Content type

Image

Digest

sha256:f7f8eb4a0…

Size

1.5 GB

Last updated

9 months ago

docker pull everhytale/hytale-server