From 06a00b2ac6226cc6e1f02126b2e845ce219fcf50 Mon Sep 17 00:00:00 2001 From: Alex Kretzschmar Date: Fri, 16 Jan 2026 13:58:07 -0500 Subject: [PATCH 1/3] Add Hytale service with Tailscale sidecar --- services/hytale/.env | 20 +++++++++++++ services/hytale/README.md | 26 +++++++++++++++++ services/hytale/compose.yaml | 55 ++++++++++++++++++++++++++++++++++++ 3 files changed, 101 insertions(+) create mode 100644 services/hytale/.env create mode 100644 services/hytale/README.md create mode 100644 services/hytale/compose.yaml diff --git a/services/hytale/.env b/services/hytale/.env new file mode 100644 index 0000000..bfeaf59 --- /dev/null +++ b/services/hytale/.env @@ -0,0 +1,20 @@ +#version=1.1 +#URL=https://github.com/tailscale-dev/ScaleTail +#COMPOSE_PROJECT_NAME= # Optional: only use when running multiple deployments on the same infrastructure. + +# Service Configuration +IMAGE_URL=deinfreu/hytale-server:experimental + +# Network Configuration +SERVICEPORT=5520 +DNS_SERVER=1.1.1.1 + +# Tailscale Configuration +TS_AUTHKEY= + +# Hytale Configuration +SERVER_IP=0.0.0.0 +SERVER_PORT=5520 +PROD=FALSE +DEBUG=FALSE +TZ=US/Eastern diff --git a/services/hytale/README.md b/services/hytale/README.md new file mode 100644 index 0000000..3b9124c --- /dev/null +++ b/services/hytale/README.md @@ -0,0 +1,26 @@ +# Hytale Server with Tailscale Sidecar Configuration + +This Docker Compose configuration sets up a Hytale game server with Tailscale as a sidecar container to place the server directly on your Tailnet. The Hytale container uses the Tailscale network stack via `network_mode: service:tailscale`, so players connect over Tailscale without exposing the UDP port publicly. + +## Hytale Server + +The Hytale server runs from `deinfreu/hytale-server:experimental` and is configured for UDP port `5520`. The game server data is stored in a named volume (`hytale-data`) to persist across restarts. + +Upstream container details and install notes: +https://deinfreu.github.io/hytale-server-container/installation/container_installation/ + +## Key Notes + +* First-time authentication should be done attached (do not use `-d` initially). +* Game files, world data, and configuration are stored in the data volume and persist across restarts. + +## Configuration Overview + +In this setup, the `tailscale` service runs the Tailscale client to join your private mesh network. The `hytale` service is configured with `network_mode: service:tailscale`, so all network traffic for the game server is routed through the Tailscale container. The sidecar binds UDP `5520` for Tailnet access only. + +## Files to check + +Please verify the following files and variables before deploying: + +* `.env` — define `SERVICE`, `IMAGE_URL`, `SERVICEPORT`, `TS_AUTHKEY`, and the Hytale variables (`SERVER_IP`, `SERVER_PORT`, `PROD`, `DEBUG`, `TZ`). +* `compose.yaml` — confirm environment variables and volume mappings for your server. diff --git a/services/hytale/compose.yaml b/services/hytale/compose.yaml new file mode 100644 index 0000000..89c4f6f --- /dev/null +++ b/services/hytale/compose.yaml @@ -0,0 +1,55 @@ +services: +# Make sure you have updated/checked the .env file with the correct variables. +# All the ${ xx } need to be defined there. + # Tailscale Sidecar Configuration + hytale-ts: + image: tailscale/tailscale:latest # Image to be used + container_name: hytale-ts # Name for local container management + hostname: ${SERVICE} # Name used within your Tailscale environment + environment: + - TS_AUTHKEY=${TS_AUTHKEY} + - TS_STATE_DIR=/var/lib/tailscale + - TS_USERSPACE=false + - TS_ENABLE_HEALTH_CHECK=true # Enable healthcheck endpoint: "/healthz" + - TS_LOCAL_ADDR_PORT=127.0.0.1:41234 # The : for the healthz endpoint + #- TS_ACCEPT_DNS=true # Uncomment when using MagicDNS + volumes: + - ./config:/config # Config folder used to store Tailscale files - you may need to change the path + - ./ts/state:/var/lib/tailscale # Tailscale requirement - you may need to change the path + devices: + - /dev/net/tun:/dev/net/tun # Network configuration for Tailscale to work + cap_add: + - net_admin # Tailscale requirement + ports: + - "${SERVICEPORT}:${SERVICEPORT}/udp" + # If any DNS issues arise, use your preferred DNS provider by uncommenting the config below + #dns: + # - ${DNS_SERVER} + healthcheck: + test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:41234/healthz"] # Check Tailscale has a Tailnet IP and is operational + interval: 1m # How often to perform the check + timeout: 10s # Time to wait for the check to succeed + retries: 3 # Number of retries before marking as unhealthy + start_period: 10s # Time to wait before starting health checks + restart: always + + # ${SERVICE} + hytale-server: + image: ${IMAGE_URL} # Image to be used + network_mode: service:tailscale # Sidecar configuration to route ${SERVICE} through Tailscale + container_name: hytale-server # Name for local container management + environment: + - SERVER_IP=${SERVER_IP} + - SERVER_PORT=${SERVER_PORT} + - PROD=${PROD} + - DEBUG=${DEBUG} + - TZ=${TZ} + volumes: + - ./${SERVICE}-data:/home/container + - /etc/machine-id:/etc/machine-id:ro + tty: true + stdin_open: true + depends_on: + tailscale: + condition: service_healthy + restart: unless-stopped From be93c47b997e651a64ef2c77cb0e913d48741fb8 Mon Sep 17 00:00:00 2001 From: Alex Kretzschmar Date: Fri, 16 Jan 2026 14:01:17 -0500 Subject: [PATCH 2/3] Fix markdown link in Hytale README --- services/hytale/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/services/hytale/README.md b/services/hytale/README.md index 3b9124c..d22456a 100644 --- a/services/hytale/README.md +++ b/services/hytale/README.md @@ -7,7 +7,7 @@ This Docker Compose configuration sets up a Hytale game server with Tailscale as The Hytale server runs from `deinfreu/hytale-server:experimental` and is configured for UDP port `5520`. The game server data is stored in a named volume (`hytale-data`) to persist across restarts. Upstream container details and install notes: -https://deinfreu.github.io/hytale-server-container/installation/container_installation/ +[https://deinfreu.github.io/hytale-server-container/installation/container_installation/](https://deinfreu.github.io/hytale-server-container/installation/container_installation/) ## Key Notes From 929c0a185ee5ea5617268b076103add22eb18b6e Mon Sep 17 00:00:00 2001 From: Alex Kretzschmar Date: Wed, 21 Jan 2026 08:57:00 -0500 Subject: [PATCH 3/3] Address PR 191 review feedback --- README.md | 1 + services/hytale/.env | 1 + services/hytale/README.md | 4 ++-- services/hytale/compose.yaml | 8 ++++---- 4 files changed, 8 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 3bdb253..efd09a2 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,7 @@ If you would like to add your own config, you can use the [service-template](tem | 🎧 **Audiobookshelf** | A self-hosted audiobook and podcast server with multi-user support and playback syncing. | [Details](services/audiobookshelf) | | 🎥 **Bazarr** | A companion tool to Radarr and Sonarr for managing subtitles. | [Details](services/bazarr) | | 📚 **BookLore** | A self-hosted application for managing and reading books. | [Details](services/booklore) | +| 🎮 **Hytale** | A self-hosted Hytale game server. | [Details](services/hytale) | | 🖼️ **Immich** | A self-hosted Google Photos alternative with face recognition and mobile sync. | [Details](services/immich) | | 📺 **Jellyfin** | An open-source media system that puts you in control of managing and streaming your media. | [Details](services/jellyfin) | | 📺 **Jellyseerr** | A request management and media discovery tool for Jellyfin and Plex users. | [Details](services/jellyseerr) | diff --git a/services/hytale/.env b/services/hytale/.env index bfeaf59..fa59f4a 100644 --- a/services/hytale/.env +++ b/services/hytale/.env @@ -3,6 +3,7 @@ #COMPOSE_PROJECT_NAME= # Optional: only use when running multiple deployments on the same infrastructure. # Service Configuration +SERVICE=hytale IMAGE_URL=deinfreu/hytale-server:experimental # Network Configuration diff --git a/services/hytale/README.md b/services/hytale/README.md index d22456a..6ca3291 100644 --- a/services/hytale/README.md +++ b/services/hytale/README.md @@ -4,7 +4,7 @@ This Docker Compose configuration sets up a Hytale game server with Tailscale as ## Hytale Server -The Hytale server runs from `deinfreu/hytale-server:experimental` and is configured for UDP port `5520`. The game server data is stored in a named volume (`hytale-data`) to persist across restarts. +The Hytale server runs from `deinfreu/hytale-server:experimental` and is configured for UDP port `5520`. The game server data is stored in the `${SERVICE}-data` directory to persist across restarts. Upstream container details and install notes: [https://deinfreu.github.io/hytale-server-container/installation/container_installation/](https://deinfreu.github.io/hytale-server-container/installation/container_installation/) @@ -16,7 +16,7 @@ Upstream container details and install notes: ## Configuration Overview -In this setup, the `tailscale` service runs the Tailscale client to join your private mesh network. The `hytale` service is configured with `network_mode: service:tailscale`, so all network traffic for the game server is routed through the Tailscale container. The sidecar binds UDP `5520` for Tailnet access only. +In this setup, the `tailscale` service runs the Tailscale client to join your private mesh network. The `application` service is configured with `network_mode: service:tailscale`, so all network traffic for the game server is routed through the Tailscale container. The sidecar binds UDP `5520` for Tailnet access only. ## Files to check diff --git a/services/hytale/compose.yaml b/services/hytale/compose.yaml index 89c4f6f..8654692 100644 --- a/services/hytale/compose.yaml +++ b/services/hytale/compose.yaml @@ -2,9 +2,9 @@ services: # Make sure you have updated/checked the .env file with the correct variables. # All the ${ xx } need to be defined there. # Tailscale Sidecar Configuration - hytale-ts: + tailscale: image: tailscale/tailscale:latest # Image to be used - container_name: hytale-ts # Name for local container management + container_name: tailscale-${SERVICE} # Name for local container management hostname: ${SERVICE} # Name used within your Tailscale environment environment: - TS_AUTHKEY=${TS_AUTHKEY} @@ -34,10 +34,10 @@ services: restart: always # ${SERVICE} - hytale-server: + application: image: ${IMAGE_URL} # Image to be used network_mode: service:tailscale # Sidecar configuration to route ${SERVICE} through Tailscale - container_name: hytale-server # Name for local container management + container_name: app-${SERVICE} # Name for local container management environment: - SERVER_IP=${SERVER_IP} - SERVER_PORT=${SERVER_PORT}