How to Set Up a Hytale Server with Docker

Running your own Hytale server is a great way to play with friends or build a community. This guide will walk you through setting up a Hytale dedicated server using Docker, which makes the process simple and reproducible.

Prerequisites

Before you begin, make sure you have:

• A Hytale account with game access
• Docker and Docker Compose installed on your server
• A CurseForge API key (optional, for mod support) - Get one at console.curseforge.com
• Basic terminal/command line knowledge

Step 1: Create the Docker Compose File

Create a new directory for your server and add a docker-compose.yml file with the following content:

services:
  hytale:
    image: hybrowse/hytale-server:latest
    environment:
      HYTALE_AUTH_MODE: "authenticated"
      HYTALE_AUTO_DOWNLOAD: "true"
      HYTALE_ENABLE_BACKUP: "true"
      HYTALE_BACKUP_DIR: "/backups"
      HYTALE_BACKUP_FREQUENCY_MINUTES: "60"
      # Enable CurseForge mod management
      HYTALE_CURSEFORGE_MODS: |
        1409700
        1423661
        1428236
        1423805
        1418291
        1429189
        1406395
        1419622
        1423494
        1405415
        1428816
        1429827
      # Read the API key from a mounted secret file
      HYTALE_CURSEFORGE_API_KEY_SRC: "/run/secrets/curseforge_api_key"

    secrets:
      - curseforge_api_key

    ports:
      - "5520:5520/udp"    # Game port
      - "8080:8080"        # Web interface (if applicable)
      - "5523:5523"        # Additional port
    volumes:
      - ./data:/data
      - ./backups:/backups
    tty: true
    stdin_open: true
    restart: unless-stopped

secrets:
  curseforge_api_key:
    file: ./secrets/curseforge_api_key.txt

Step 2: Set Up Directory Structure

Create the necessary directories and set permissions:

# Create directories
mkdir -p ./secrets
mkdir -p ./data
mkdir -p ./backups

# Set permissions (Docker runs as user 1000)
chown -R 1000:1000 ./data
chown -R 1000:1000 ./backups

Step 3: Configure CurseForge API Key (Optional)

If you want to use mods from CurseForge, you'll need an API key:

1. Go to console.curseforge.com
2. Create or copy your API key
3. Save it to the secrets file:

nano ./secrets/curseforge_api_key.txt
# Paste your API key and save

Step 4: First Run - Download and Authentication

Start the server for the first time:

docker compose up

On first run, you'll need to authenticate to download the server files. Watch the logs for a message like:

Please visit the following URL to authenticate:
https://oauth.accounts.hytale.com/oauth2/device/verify?user_code=KpDgbqsN
Or visit the following URL and enter the code:
https://oauth.accounts.hytale.com/oauth2/device/verify
Authorization code: KpDgbqsN

Open the URL in your browser, log in with your Hytale account, and enter the code to authorize the download.

Step 5: Server Authentication

After the server files download, you'll need to authenticate the server itself. Attach to the container console:

docker compose attach hytale

Then run these commands in the server console:

# Enable persistent authentication (saves tokens)
/auth persistence Encrypted

# Start device login flow
/auth login device

You'll see another authentication prompt:

[AbstractCommand] DEVICE AUTHORIZATION
===================================================================
Visit: https://oauth.accounts.hytale.com/oauth2/device/verify
Enter code: Vc7TjdCt
===================================================================
Waiting for authorization (expires in 600 seconds)...

Complete the authentication in your browser. Once successful, you'll see:

Authentication successful! Mode: OAUTH_DEVICE

To detach from the console without stopping the server, press Ctrl-p then Ctrl-q.

Step 6: Adding Mods

The HYTALE_CURSEFORGE_MODS environment variable accepts a list of CurseForge project IDs. To find the ID of a mod:

1. Go to legacy.curseforge.com/hytale/mods
2. Open the mod page you want
3. Look for "Project ID" on the right sidebar

For example, the EyeSpy mod at legacy.curseforge.com/hytale/mods/eyespy has Project ID 1423494.

Add the project ID to your compose file and restart the container to install new mods.

Configuration Options

Here are the key environment variables you can configure:

Ports

• 5520/UDP - Main game port (required for players to connect)
• 8080 - Web interface (optional)
• 5523 - Additional services port

Make sure port 5520/UDP is open in your firewall and forwarded if behind a NAT.

Useful Commands

# Start the server in background
docker compose up -d

# View logs
docker compose logs -f hytale

# Attach to server console
docker compose attach hytale

# Restart the server
docker compose restart

# Stop the server
docker compose down

Adding Your Server to Santale

Once your server is running and authenticated, you can add it to Santale to gain visibility and allow players to find you:

1. Create an account on Santale
2. Go to Add Your Server
3. Enter your server's hostname and port (default: 5520)
4. Fill in your server details and submit

For server status to work properly, you may need to install a query protocol mod. See our FAQ for more information on supported query protocols.

Troubleshooting

Authentication Expired

If your server shows authentication errors after a restart, you may need to re-authenticate using /auth login device in the server console.

Mods Not Loading

Check that your CurseForge API key is valid and the mod IDs are correct. View logs with docker compose logs to see any mod loading errors.

Players Can't Connect

Verify that port 5520/UDP is open in your firewall and properly forwarded if your server is behind a router.

Have questions? Check out our FAQ or join the community to get help from other server owners.