theo546/docker-hytale-server repository overview

A Docker setup for running a Hytale server. Dead simple. Downloads, updates, auto-installs & updates mods, authentication, configuration, it just handles all of it. You point it at a directory, run it, and it works.

⁠Quick Start

Ideally, use the compose.yml below to get started immediately.

⁠GitHub Container Registry (Recommended)

services:
  hytale-server:
    image: ghcr.io/theo546/docker-hytale-server:latest
    restart: always
    read_only: true
    volumes:
      - ./data:/server
    tmpfs:
      - /tmp:size=100M,uid=1000,gid=1000,mode=1777,exec
      - /var/lib/dbus:size=5M,uid=1000,gid=1000,mode=0755
    ports:
      - "5520:5520/udp"
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges
    environment:
      # Server configuration
      - HYTALE_BIND=0.0.0.0:5520
      - HYTALE_AUTH_MODE=AUTHENTICATED
      - HYTALE_ALLOW_OP=false
      - HYTALE_CURSEFORGE_MODS=

      # Backup
      - HYTALE_BACKUP_ENABLED=true
      - HYTALE_BACKUP_DIR=/server/backups
      - HYTALE_BACKUP_FREQ=30

      # Experimental
      - HYTALE_ACCEPT_EARLY_PLUGINS=false

      # Downloader
      # Patchline to use (e.g. "pre-release")
      - HYTALE_PATCHLINE_PRE_RELEASE=

      # Game Config
      - HYTALE_SERVER_NAME=Hytale Server
      - HYTALE_SERVER_MOTD=
      - HYTALE_SERVER_PASSWORD=
      - HYTALE_SERVER_MAX_PLAYERS=100
      - HYTALE_SERVER_MAX_VIEW_RADIUS=32
      - HYTALE_SERVER_OWNER_NAME=

View package on GitHub Container Registry⁠

⁠Docker Hub

services:
  hytale-server:
    image: theo546/docker-hytale-server:latest 
    # ... rest of the configuration is identical

View image on Docker Hub⁠

⁠How to Run

1. Copy the compose.yml exemple from above in a dedicated directory.

2. Create the data directory with the correct permissions:

   mkdir data
   sudo chown 1000:1000 data
   

   Copy

3. Run the server:

   docker compose up -d
   

   Copy

4. Check the logs to authenticate:

   docker compose logs -f
   

   Copy

   You will need to authenticate twice:

   1. First, when the system downloads the game assets.
   2. Second, when the game server starts up and connects to the session service.

   Look for a log line containing a URL like this: https://oauth.accounts.hytale.com/oauth2/device/verify?user_code=AAAAAAAA

   Copy and paste that URL into your browser to authorize the server. Once the logs say "Authentication successful", you are good to go.

⁠Configuration

Configure the server by editing the compose.yml file.

⁠Data Storage

All server data (save files, logs, config, and your persistent machine ID) is stored in the ./data directory.

⁠Authentication and Machine ID

Hytale servers use a unique "machine ID" to encrypt your login credentials. In a standard Docker environment, this ID changes every time you recreate the container, which would normally force you to re-login after every update.

This setup solves that problem. On the first run, it generates a unique machine ID and saves it to your data folder. On every subsequent boot, it injects this saved ID back into the system. This tricks the server into believing it is always running on the same machine, keeping your encrypted credentials valid indefinitely.

⁠Source Code

This project is open source!
View on GitHub⁠