{"id":41944181,"url":"https://github.com/zonfacter/hytale-docker","last_synced_at":"2026-02-08T13:04:23.031Z","repository":{"id":334538825,"uuid":"1141760072","full_name":"zonfacter/hytale-docker","owner":"zonfacter","description":"Docker image for Hytale Dedicated Server with Web Dashboard - Easy deployment with setup wizard","archived":false,"fork":false,"pushed_at":"2026-01-25T22:12:04.000Z","size":210,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-26T02:48:20.061Z","etag":null,"topics":["curseforge","dashboard","dedicated-server","docker","docker-compose","docker-hub","docker-image","game-server","hytale","hytale-server","modding"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zonfacter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-25T11:38:10.000Z","updated_at":"2026-01-25T22:11:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zonfacter/hytale-docker","commit_stats":null,"previous_names":["zonfacter/hytale-docker"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/zonfacter/hytale-docker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zonfacter%2Fhytale-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zonfacter%2Fhytale-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zonfacter%2Fhytale-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zonfacter%2Fhytale-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zonfacter","download_url":"https://codeload.github.com/zonfacter/hytale-docker/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zonfacter%2Fhytale-docker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29230787,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-08T12:28:20.184Z","status":"ssl_error","status_checked_at":"2026-02-08T12:28:19.510Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["curseforge","dashboard","dedicated-server","docker","docker-compose","docker-hub","docker-image","game-server","hytale","hytale-server","modding"],"created_at":"2026-01-25T19:16:41.305Z","updated_at":"2026-02-08T13:04:23.025Z","avatar_url":"https://github.com/zonfacter.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hytale Docker\n\n[![Docker Hub](https://img.shields.io/docker/v/zonfacter/hytale-docker?label=Docker%20Hub\u0026logo=docker)](https://hub.docker.com/r/zonfacter/hytale-docker)\n[![Docker Pulls](https://img.shields.io/docker/pulls/zonfacter/hytale-docker?logo=docker)](https://hub.docker.com/r/zonfacter/hytale-docker)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Hytale](https://img.shields.io/badge/Hytale-Server-orange)](https://hytale.com/)\n\nDocker image for **Hytale Dedicated Server** with integrated **Web Dashboard**.\n\n🇩🇪 [Deutsche Anleitung](docs/setup-guide-de.md) | 🇬🇧 [English Guide](docs/setup-guide-en.md)\n\n![Dashboard Screenshot](https://raw.githubusercontent.com/zonfacter/hytale-dashboard/master/docs/dashboard.png)\n\n---\n\n## Features\n\n- 🎮 **Hytale Dedicated Server** - Ready to run with Java 24\n- 🖥️ **Web Dashboard** - Manage your server via browser\n- 🔧 **Setup Wizard** - Guided installation with OAuth support\n- 💬 **Server Console** - Send commands directly from the dashboard\n- 🔐 **Server Authentication** - Easy Browser/Device login buttons\n- 🔗 **Tailscale VPN** - Secure remote access without port-forwarding\n- 🌐 **Port Mapping Display** - See external ports in bridge mode\n- 📊 **Version Detection** - Automatic update checking via downloader\n- ⬇️ **Automatic Downloader** - Server files downloaded automatically\n- 📦 **CurseForge Integration** - Install mods with one click\n- 💾 **Automatic Backups** - Built-in backup system\n- ⚙️ **Runtime Settings** - Configure API keys without container restart\n- 🚀 **AOTCache Support** - Faster server startup with Java 24\n- 🔑 **Persistent Auth** - Credentials survive container restarts\n\n![Setup Wizard](docs/screenshots/setup-wizard.png)\n\n---\n\n## Quick Start\n\n### Option 1: Using Docker Hub (Recommended)\n\n```bash\n# Pull image\ndocker pull zonfacter/hytale-docker:latest\n\n# Run container with named volumes (recommended)\n# Note: Universe path is Server/universe/ since Hytale Server 2026.01\ndocker run -d \\\n  --name hytale-server \\\n  -p 8088:8088 \\\n  -p 5520:5520/udp \\\n  -v hytale-universe:/opt/hytale-server/Server/universe \\\n  -v hytale-mods:/opt/hytale-server/mods \\\n  -v hytale-backups:/opt/hytale-server/backups \\\n  -v hytale-downloader:/opt/hytale-server/.downloader \\\n  -e DASH_PASS=changeme \\\n  zonfacter/hytale-docker:latest\n\n# Open dashboard\n# http://localhost:8088/setup\n```\n\n**Alternative:** If you prefer bind mounts for direct file access:\n\n```bash\n# Create data directory\nmkdir -p hytale-data/{universe,mods,backups,downloader}\n\n# Run container with bind mounts\n# Note: Universe path is Server/universe/ since Hytale Server 2026.01\ndocker run -d \\\n  --name hytale-server \\\n  -p 8088:8088 \\\n  -p 5520:5520/udp \\\n  -v $(pwd)/hytale-data/universe:/opt/hytale-server/Server/universe \\\n  -v $(pwd)/hytale-data/mods:/opt/hytale-server/mods \\\n  -v $(pwd)/hytale-data/backups:/opt/hytale-server/backups \\\n  -v $(pwd)/hytale-data/downloader:/opt/hytale-server/.downloader \\\n  -e DASH_PASS=changeme \\\n  zonfacter/hytale-docker:latest\n```\n\n### Option 2: Using Docker Compose\n\n```bash\n# Clone repository\ngit clone https://github.com/zonfacter/hytale-docker.git\ncd hytale-docker\n\n# Start containers\ndocker-compose up -d\n\n# Open dashboard\n# http://localhost:8088/setup\n```\n\n**Default Credentials:**\n- Username: `admin`\n- Password: `changeme`\n\n⚠️ **Change the password in `docker-compose.yml` before production use!**\n\n---\n\n## Initial Setup\n\n### 1. Hytale Downloader (Automatic)\n\nThe container automatically downloads the Hytale Downloader on first start from:\n```\nhttps://downloader.hytale.com/hytale-downloader.zip\n```\n\n**No manual action required!** The ZIP file is automatically extracted and the Linux binary is installed.\n\n\u003e 💡 **Custom URL:** If needed, you can override the URL via environment variable:\n\u003e ```yaml\n\u003e environment:\n\u003e   - HYTALE_DOWNLOADER_URL=https://custom-url/downloader.zip\n\u003e ```\n\n### 2. Start and Configure\n\n```bash\ndocker-compose up -d\n```\n\n### 3. Complete Setup via Dashboard\n\nOpen `http://localhost:8088/setup` and follow the wizard:\n\n1. ✅ Downloader automatically fetched from hytale.com\n2. 🔐 Click \"Start Download\" → OAuth link appears in log\n3. 🌐 Open OAuth link in browser → Login with Hytale account\n4. ⬇️ Server downloads automatically\n5. 🎉 Done! Server starts automatically\n\n![Setup Process](docs/screenshots/setup-oauth.png)\n\n---\n\n## Tailscale VPN (Optional)\n\nEnable secure remote access without port-forwarding using Tailscale:\n\n```yaml\nservices:\n  hytale:\n    cap_add:\n      - NET_ADMIN\n      - SYS_MODULE\n    devices:\n      - /dev/net/tun:/dev/net/tun\n    environment:\n      - TAILSCALE_ENABLED=true\n      - TAILSCALE_AUTHKEY=tskey-auth-xxxxx  # Get from tailscale.com/admin\n      - TAILSCALE_HOSTNAME=hytale-server\n    volumes:\n      - hytale-tailscale:/var/lib/tailscale\n```\n\n**Benefits:**\n- 🔒 No port forwarding needed\n- 🌍 Access from anywhere securely\n- 🔐 End-to-end encrypted connections\n- 👥 Easy multiplayer with friends\n\n**Setup:**\n1. Create a [Tailscale account](https://login.tailscale.com/start) (free)\n2. Generate an [auth key](https://login.tailscale.com/admin/settings/keys)\n3. Add the configuration above to docker-compose.yml\n4. Access your server via Tailscale IP: `http://100.x.x.x:8088`\n\n📖 **Full Documentation:** [docs/tailscale-integration.md](docs/tailscale-integration.md)\n\n---\n\n## Configuration\n\nEdit `docker-compose.yml`:\n\n```yaml\nenvironment:\n  # Server Settings\n  - HYTALE_MEMORY_MIN=2G\n  - HYTALE_MEMORY_MAX=4G\n\n  # Downloader (automatic, uses official URL by default)\n  # - HYTALE_DOWNLOADER_URL=https://downloader.hytale.com/hytale-downloader.zip\n\n  # Dashboard Settings\n  - DASH_USER=admin\n  - DASH_PASS=your-secure-password  # CHANGE THIS!\n\n  # Optional: CurseForge API Key\n  - CF_API_KEY=your-api-key\n```\n\nThen restart:\n\n```bash\ndocker-compose up -d\n```\n\n---\n\n## Build Arguments \u0026 Platform Support\n\n### Supported Platforms\n\nThis image supports multiple architectures:\n- **linux/amd64** (Intel/AMD 64-bit)\n- **linux/arm64** (ARM 64-bit, e.g., Apple Silicon, Raspberry Pi 4/5)\n\nDocker will automatically pull the correct image for your platform.\n\n### Custom Build Arguments\n\nYou can customize the base image and Java version when building from source:\n\n```bash\n# Clone repository with submodules\ngit clone --recurse-submodules https://github.com/zonfacter/hytale-docker.git\ncd hytale-docker\n\n# Build with default settings (Trixie + Java 24)\ndocker build -t hytale-custom .\n\n# Or with custom Debian/Java version\ndocker build \\\n  --build-arg DEBIAN_BASE_IMAGE=debian:bookworm-slim \\\n  --build-arg DEBIAN_CODENAME=bookworm \\\n  --build-arg JAVA_VERSION=21 \\\n  -t hytale-custom .\n```\n\nAvailable build arguments:\n- **DEBIAN_BASE_IMAGE**: Base Debian image (default: `debian:trixie-slim`)\n- **DEBIAN_CODENAME**: Debian codename for Java repository (default: `trixie`)\n- **JAVA_VERSION**: Eclipse Temurin Java version (default: `24`)\n\n\u003e ⚠️ **Note:** Java 24 is required for the Hytale Server's AOTCache feature (faster startup).\n\nOr configure in `docker-compose.yml`:\n\n```yaml\nbuild:\n  context: .\n  dockerfile: Dockerfile\n  args:\n    DEBIAN_BASE_IMAGE: debian:trixie-slim\n    DEBIAN_CODENAME: trixie\n    JAVA_VERSION: 24\n```\n\n### Building from Source\n\nWhen building from source, the dashboard is included as a Git submodule. To clone the repository with all dependencies:\n\n```bash\n# Clone with submodules\ngit clone --recurse-submodules https://github.com/zonfacter/hytale-docker.git\n\n# Or if already cloned, initialize submodules\ngit submodule update --init --recursive\n```\n\nTo update the dashboard to the latest version:\n\n```bash\ncd dashboard-source\ngit pull origin master\ncd ..\ngit add dashboard-source\ngit commit -m \"Update dashboard to latest version\"\n```\n\n---\n\n## Ports\n\n| Port | Protocol | Description |\n|------|----------|-------------|\n| 5520 | UDP | Hytale Game Server |\n| 5523 | TCP | Nitrado WebServer API |\n| 8088 | TCP | Web Dashboard |\n\n---\n\n## Volumes\n\nData is stored in Docker-managed named volumes by default (recommended for production):\n\n| Volume Name | Container Path | Description |\n|-------------|----------------|-------------|\n| `hytale-universe` | `/opt/hytale-server/Server/universe` | World data (players, builds) |\n| `hytale-mods` | `/opt/hytale-server/mods` | Installed mods |\n| `hytale-backups` | `/opt/hytale-server/backups` | Backup files |\n| `hytale-downloader` | `/opt/hytale-server/.downloader` | Downloader \u0026 OAuth credentials |\n| `hytale-logs` | `/opt/hytale-server/logs` | Server logs |\n\n\u003e **Note:** Since Hytale Server 2026.01, world data is stored in `Server/universe/` instead of `universe/`. If upgrading from an older version, see [Migration Guide](#migration-from-v17-or-earlier).\n\n### Volume Configuration Options\n\nThe default configuration uses **named volumes**, which are recommended because:\n- ✅ Independent of working directory\n- ✅ Better managed by Docker\n- ✅ Consistent across different operating systems\n- ✅ Easier to backup and migrate\n\n#### Alternative 1: Bind Mounts with Relative Paths\n\nIf you need direct file system access (e.g., for manual backups), you can use bind mounts with relative paths. Edit `docker-compose.yml` and uncomment the relative path section (around line 106).\n\n⚠️ **Important:** You must always run `docker-compose` from the repository root directory, or the data will be stored in unexpected locations.\n\n#### Alternative 2: Bind Mounts with Absolute Paths\n\nFor production environments with specific storage requirements, use absolute paths. Edit `docker-compose.yml` and uncomment the absolute path section (around line 116), replacing `/path/to/hytale-data` with your actual data directory.\n\nThis is the most reliable option for production as it explicitly defines where data is stored.\n\n### Managing Named Volumes\n\n```bash\n# List volumes\ndocker volume ls\n\n# Inspect a volume to see where data is stored\ndocker volume inspect hytale-universe\n\n# Backup a volume (example for universe)\ndocker run --rm -v hytale-universe:/data -v $(pwd):/backup ubuntu tar czf /backup/universe-backup.tar.gz -C /data .\n\n# Restore a volume\ndocker run --rm -v hytale-universe:/data -v $(pwd):/backup ubuntu tar xzf /backup/universe-backup.tar.gz -C /data\n\n# Remove all volumes (WARNING: deletes all data!)\ndocker-compose down -v\n```\n\n---\n\n## Commands\n\n```bash\n# Start\ndocker-compose up -d\n\n# Stop\ndocker-compose down\n\n# View logs\ndocker-compose logs -f\n\n# Restart\ndocker-compose restart\n\n# Update\ndocker-compose pull \u0026\u0026 docker-compose up -d\n\n# Enter container shell\ndocker-compose exec hytale bash\n```\n\n---\n\n## Runtime Settings\n\nYou can configure settings **after** container creation without recreating the container:\n\n1. Open the Dashboard → Setup page\n2. Scroll down to \"Settings (Optional)\"\n3. Enter your CurseForge API Key or custom Downloader URL\n4. Click \"Save\"\n\nSettings are stored in `/opt/hytale-server/.dashboard_config.json` (persisted in volume).\n\nThis is especially useful for NAS systems (like UGREEN) where you can't easily pass environment variables during container creation.\n\n---\n\n## CurseForge Integration\n\nInstall mods directly from CurseForge:\n\n**Option 1: Via Environment Variable**\n```yaml\nenvironment:\n  - CF_API_KEY=your-api-key\n```\n\n**Option 2: Via Dashboard (Runtime)**\n1. Get a free API key: [console.curseforge.com](https://console.curseforge.com/)\n2. Open Dashboard → Setup → Settings\n3. Enter your API key and click \"Save\"\n4. Browse \u0026 install mods via Dashboard → Manage → CurseForge\n\n---\n\n## Release v1.9.0\n\n- Dashboard submodule updated to `hytale-dashboard v1.5.0` (`426d13e`).\n- Backup management enhancements are now available in Docker builds (create/restore actions and seed handling from upstream dashboard).\n- Docker build remains reproducible via pinned submodule commit.\n\n## Draft Release Download (v1.9.1)\n\nEin Draft-Release mit Paketdateien wird unter GitHub Releases bereitgestellt.\nEnthaelt:\n- `hytale-docker-v1.9.1-full.tar.gz`\n- `hytale-docker-v1.9.1-full.zip`\n\nHinweis: Draft-Releases sind nur fuer Repo-Collaborators sichtbar, bis sie veroeffentlicht werden.\n\n## Documentation\n\n- 🇩🇪 [Einrichtungsanleitung (Deutsch)](docs/setup-guide-de.md)\n- 🇬🇧 [Setup Guide (English)](docs/setup-guide-en.md)\n- ⚙️ [Configuration \u0026 Read-Only Containers](docs/configuration.md)\n- 🔧 [IPC Mechanisms \u0026 FIFO Documentation](docs/ipc-mechanisms.md)\n- 📊 [Dashboard Repository](https://github.com/zonfacter/hytale-dashboard)\n\n---\n\n## Migration from v1.7 or Earlier\n\n### Universe Path Change (v1.8.0+)\n\n**Problem:** Since Hytale Server 2026.01, world data is stored in `Server/universe/` instead of `universe/`. If you upgrade from v1.7 or earlier, your world data may appear to be lost.\n\n**Ursache / Cause:**\n- 🇩🇪 Die neue Hytale Server Version speichert Weltdaten in `Server/universe/` statt `universe/`\n- 🇬🇧 The new Hytale Server version stores world data in `Server/universe/` instead of `universe/`\n\n**Solution:**\n\n```bash\n# 1. Stop the container\ndocker-compose down\n\n# 2. Copy data from old location to new location\ndocker run --rm \\\n  -v hytale-universe:/old \\\n  -v hytale-universe-new:/new \\\n  ubuntu cp -r /old/. /new/\n\n# 3. Update docker-compose.yml volume path:\n#    Change: hytale-universe:/opt/hytale-server/universe\n#    To:     hytale-universe-new:/opt/hytale-server/Server/universe\n\n# 4. Start the container\ndocker-compose up -d\n```\n\n**Alternative (Bind Mounts):**\n```bash\n# If using bind mounts, simply update the path in docker-compose.yml:\n# Old: ./data/universe:/opt/hytale-server/universe\n# New: ./data/universe:/opt/hytale-server/Server/universe\n```\n\n---\n\n## Troubleshooting\n\n### Downloader not found\nThe downloader is fetched automatically from `https://downloader.hytale.com/hytale-downloader.zip` on first start.\n\n**If automatic download fails:**\n- Check container logs: `docker-compose logs hytale`\n- Verify network connectivity\n- Try manual download:\n  ```bash\n  # Download and extract manually\n  wget https://downloader.hytale.com/hytale-downloader.zip\n  unzip hytale-downloader.zip\n  # Copy to volume\n  docker run --rm -v hytale-downloader:/downloader -v $(pwd):/host ubuntu \\\n    cp /host/hytale-downloader-linux-amd64 /downloader/\n  ```\n\n### OAuth link doesn't appear\n- Click \"Refresh Log\" in the setup wizard\n- Check if downloader file exists (see \"Downloader not found\" above)\n\n### Server won't start\n- Check logs: `docker-compose logs hytale`\n- Ensure enough memory is available\n- Verify server files were extracted correctly\n\n### Mods not loading\n- **With named volumes**: Mods can be added via the Dashboard's CurseForge integration or copied to volume using: `docker run --rm -v hytale-mods:/mods -v $(pwd):/host ubuntu cp /host/your-mod.jar /mods/`\n- **With bind mounts**: JAR files must be directly in `./data/mods/` (not in subfolders)\n- Restart server after installing mods\n\n### Console commands not working / FIFO issues\n- **Symptom**: Commands sent via dashboard don't reach the server\n- **Cause**: Named Pipe (FIFO) compatibility issues with storage drivers or orchestration\n- **Quick fix**: Check if pipe exists: `docker exec hytale-server ls -l /opt/hytale-server/.console_pipe`\n- **Detailed documentation**: See [IPC Mechanisms Guide](docs/ipc-mechanisms.md) for:\n  - Storage driver compatibility\n  - Kubernetes-specific issues\n  - Alternative IPC methods (Unix sockets, TCP)\n  - Windows Docker Desktop considerations\n\n---\n\n## Credits\n\n- **Dashboard \u0026 Docker Setup:** [Claude Opus 4.5](https://anthropic.com) (AI)\n- **Project Concept:** [zonfacter](https://github.com/zonfacter)\n- **Hytale:** [Hypixel Studios](https://hytale.com/)\n\n---\n\n## License\n\nMIT License - See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzonfacter%2Fhytale-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzonfacter%2Fhytale-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzonfacter%2Fhytale-docker/lists"}