Add New Service: Minecraft Server

README.md

@@ -252,8 +252,8 @@ A huge thank you to all our contributors! ScaleTail wouldn’t be what it is tod
 
 <!-- readme: contributors -start -->
 <table>
- <tbody>
-  <tr>
+	<tbody>
+		<tr>
             <td align="center">
                 <a href="https://github.com/crypt0rr">
                     <img src="https://avatars.githubusercontent.com/u/57799908?v=4" width="100;" alt="crypt0rr"/>
@@ -282,22 +282,29 @@ A huge thank you to all our contributors! ScaleTail wouldn’t be what it is tod
                     <sub><b>michaelhodges</b></sub>
                 </a>
             </td>
+            <td align="center">
+                <a href="https://github.com/LaijieJi">
+                    <img src="https://avatars.githubusercontent.com/u/108839952?v=4" width="100;" alt="LaijieJi"/>
+                    <br />
+                    <sub><b>LaijieJi</b></sub>
+                </a>
+            </td>
             <td align="center">
                 <a href="https://github.com/adamsthws">
                     <img src="https://avatars.githubusercontent.com/u/52178922?v=4" width="100;" alt="adamsthws"/>
                     <br />
                     <sub><b>adamsthws</b></sub>
                 </a>
             </td>
+		</tr>
+		<tr>
             <td align="center">
                 <a href="https://github.com/theryukverse">
                     <img src="https://avatars.githubusercontent.com/u/22323518?v=4" width="100;" alt="theryukverse"/>
                     <br />
                     <sub><b>theryukverse</b></sub>
                 </a>
             </td>
-  </tr>
-  <tr>
             <td align="center">
                 <a href="https://github.com/KhaaL">
                     <img src="https://avatars.githubusercontent.com/u/692524?v=4" width="100;" alt="KhaaL"/>
@@ -333,15 +340,15 @@ A huge thank you to all our contributors! ScaleTail wouldn’t be what it is tod
                     <sub><b>mikkotor</b></sub>
                 </a>
             </td>
+		</tr>
+		<tr>
             <td align="center">
                 <a href="https://github.com/NI-R0">
                     <img src="https://avatars.githubusercontent.com/u/98448863?v=4" width="100;" alt="NI-R0"/>
                     <br />
                     <sub><b>NI-R0</b></sub>
                 </a>
             </td>
-  </tr>
-  <tr>
             <td align="center">
                 <a href="https://github.com/RychidM">
                     <img src="https://avatars.githubusercontent.com/u/106770998?v=4" width="100;" alt="RychidM"/>
@@ -377,15 +384,15 @@ A huge thank you to all our contributors! ScaleTail wouldn’t be what it is tod
                     <sub><b>pjv</b></sub>
                 </a>
             </td>
+		</tr>
+		<tr>
             <td align="center">
                 <a href="https://github.com/wedge22">
                     <img src="https://avatars.githubusercontent.com/u/34723349?v=4" width="100;" alt="wedge22"/>
                     <br />
                     <sub><b>wedge22</b></sub>
                 </a>
             </td>
-  </tr>
-  <tr>
             <td align="center">
                 <a href="https://github.com/Jacob-JA-Shanks">
                     <img src="https://avatars.githubusercontent.com/u/44290899?v=4" width="100;" alt="Jacob-JA-Shanks"/>
@@ -421,15 +428,15 @@ A huge thank you to all our contributors! ScaleTail wouldn’t be what it is tod
                     <sub><b>cdkooistra</b></sub>
                 </a>
             </td>
+		</tr>
+		<tr>
             <td align="center">
                 <a href="https://github.com/Aurorainic">
                     <img src="https://avatars.githubusercontent.com/u/88829187?v=4" width="100;" alt="Aurorainic"/>
                     <br />
                     <sub><b>Aurorainic</b></sub>
                 </a>
             </td>
-  </tr>
-  <tr>
             <td align="center">
                 <a href="https://github.com/ironicbadger">
                     <img src="https://avatars.githubusercontent.com/u/2773080?v=4" width="100;" alt="ironicbadger"/>
@@ -451,8 +458,8 @@ A huge thank you to all our contributors! ScaleTail wouldn’t be what it is tod
                     <sub><b>orchard0</b></sub>
                 </a>
             </td>
-  </tr>
- <tbody>
+		</tr>
+	<tbody>
 </table>
 <!-- readme: contributors -end -->
 

services/minecraft/.env

@@ -0,0 +1,43 @@
+#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
+SERVICE=minecraft # Service name (e.g., adguard). Used as hostname in Tailscale and for container naming (app-${SERVICE}).
+IMAGE_URL=itzg/minecraft-server:latest # Docker image URL from container registry (e.g., adguard/adguard-home).
+
+# Network Configuration
+SERVICEPORT=25565 # Port to expose to local network. Uncomment the "ports:" section in compose.yaml to enable.
+DNS_SERVER=9.9.9.9 # Preferred DNS server for Tailscale. Uncomment the "dns:" section in compose.yaml to enable.
+
+# Tailscale Configuration
+TS_AUTHKEY= # Auth key from https://tailscale.com/admin/authkeys. See: https://tailscale.com/kb/1085/auth-keys#generate-an-auth-key for instructions.
+
+# Optional Service variables
+# PUID=1000
+
+#Time Zone setting for containers 
+TZ=Europe/Amsterdam # See: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+
+# Any Container environment variables are declared below. See https://docs.docker.com/compose/how-tos/environment-variables/
+
+# Minecraft server type: VANILLA, PAPER, FABRIC, FORGE, SPIGOT, BUKKIT
+SERVER_TYPE=VANILLA
+
+# Minecraft version: LATEST or a specific version like 1.21.4
+MINECRAFT_VERSION=LATEST
+
+# Server difficulty: peaceful, easy, normal, hard
+DIFFICULTY=normal
+
+# Maximum number of concurrent players
+MAX_PLAYERS=10
+
+# Message of the day shown in the server list
+MOTD=A Minecraft Server on Tailscale
+
+# JVM memory allocation (increase for larger servers or more players)
+MEMORY=2G
+
+# Online mode: true = requires valid Minecraft account, false = allows offline/cracked clients
+ONLINE_MODE=true

services/minecraft/README.md

@@ -0,0 +1,79 @@
+# Minecraft Server with Tailscale Sidecar Configuration
+
+This Docker Compose configuration sets up a [Minecraft Java Edition](https://www.minecraft.net/) server with Tailscale as a sidecar container, enabling private multiplayer access over your Tailnet. No port forwarding or public IP required — only players on your Tailscale network can connect.
+
+## Minecraft
+
+[Minecraft](https://www.minecraft.net/) is one of the most popular sandbox games in the world, offering open-ended survival, building, and exploration gameplay. This configuration uses the [itzg/minecraft-server](https://hub.docker.com/r/itzg/minecraft-server) Docker image, the community standard with support for Vanilla, Paper, Fabric, Forge, and other server types.
+
+## Key Features
+
+* **Private multiplayer** — no router ports need to be opened; all traffic stays on your Tailnet.
+* **MagicDNS hostname** — players connect using `minecraft.<tailnet-name>.ts.net:25565`.
+* **Multiple server types** — switch between Vanilla, Paper, Fabric, Forge, Spigot, and Bukkit via an environment variable.
+* **Persistent world data** — world files and server config are stored in a named Docker volume.
+* **Fully configurable** — server type, version, difficulty, player limit, MOTD, and memory are all set through `.env`.
+
+## Networking Note
+
+Unlike web-based services in this repository, Minecraft uses **raw TCP on port 25565**. Tailscale Serve and Funnel only proxy HTTP/HTTPS traffic, so they are **not used here**. Instead, the Minecraft server listens directly on the Tailscale interface and players connect at:
+
+```text
+minecraft.<tailnet-name>.ts.net:25565
+```
+
+No `serve.json` configuration is needed for this service.
+
+## Configuration Overview
+
+In this setup, the `tailscale-minecraft` service runs the Tailscale client to join your private mesh network. The `minecraft` service is configured with `network_mode: service:tailscale-minecraft`, so all network traffic for the game server is routed through the Tailscale container. The Minecraft server binds TCP port 25565, which is reachable only from devices on your Tailnet.
+
+## Setup
+
+1. Clone the repository and navigate to the service directory:
+
+   ```bash
+   git clone https://github.com/tailscale-dev/ScaleTail.git
+   cd ScaleTail/services/minecraft
+   ```
+
+2. Edit `.env` and paste in your Tailscale auth key (from [https://login.tailscale.com/admin/settings/keys](https://login.tailscale.com/admin/settings/keys)).
+
+3. (Optional) Adjust `SERVER_TYPE`, `MEMORY`, `MAX_PLAYERS`, or other variables in `.env`.
+
+4. Start the stack:
+
+   ```bash
+   docker compose up -d
+   ```
+
+5. Find your Tailnet name in the [Tailscale admin console](https://login.tailscale.com/admin/machines).
+
+6. Connect in Minecraft: **Multiplayer** → **Add Server** → `minecraft.<tailnet-name>.ts.net`
+
+## Connecting
+
+* All players must be on the same Tailnet (or have been shared access to the node).
+* `ONLINE_MODE=false` allows offline/non-premium accounts but reduces security — only use this on trusted networks.
+* Bedrock Edition uses UDP port 19132, which is not proxied through Tailscale Serve. Bedrock players can still connect directly via the Tailscale IP on port 19132, but this requires using the Bedrock edition of itzg/minecraft-server (set `TYPE=BEDROCK`) and is outside the scope of this configuration.
+
+## Environment Variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `TS_AUTHKEY` | _(empty)_ | Tailscale auth key from the admin console |
+| `SERVER_TYPE` | `PAPER` | Server software: VANILLA, PAPER, FABRIC, FORGE, SPIGOT, BUKKIT |
+| `MINECRAFT_VERSION` | `LATEST` | Game version: LATEST or a pinned version like 1.21.4 |
+| `DIFFICULTY` | `normal` | Game difficulty: peaceful, easy, normal, hard |
+| `MAX_PLAYERS` | `10` | Maximum concurrent players |
+| `MOTD` | `A Minecraft Server on Tailscale` | Message shown in the server browser |
+| `MEMORY` | `2G` | JVM heap size — increase for larger worlds or player counts |
+| `ONLINE_MODE` | `true` | Require valid Minecraft accounts (set false for offline/LAN play) |
+
+## Useful Links
+
+* [itzg/minecraft-server on Docker Hub](https://hub.docker.com/r/itzg/minecraft-server)
+* [itzg/minecraft-server documentation](https://docker-minecraft-server.readthedocs.io)
+* [Tailscale Serve docs](https://tailscale.com/kb/1242/tailscale-serve)
+* [Tailscale Funnel docs](https://tailscale.com/kb/1223/funnel)
+* [Tailscale Docker guide](https://tailscale.com/blog/docker-tailscale-guide)

services/minecraft/compose.yaml

@@ -0,0 +1,70 @@
+configs:
+  ts-serve:
+    content: |
+      {"TCP":{"443":{"HTTPS":true}},
+      "Web":{"$${TS_CERT_DOMAIN}:443":
+          {"Handlers":{"/":
+          {"Proxy":"http://127.0.0.1:25565"}}}},
+      "AllowFunnel":{"$${TS_CERT_DOMAIN}:443":false}}
+
+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
+  tailscale:
+    image: tailscale/tailscale:latest # Image to be used
+    container_name: tailscale-${SERVICE} # 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_SERVE_CONFIG=/config/serve.json # Tailscale Serve configuration to expose the web interface on your local Tailnet - remove this line if not required
+      - TS_USERSPACE=false
+      - TS_ENABLE_HEALTH_CHECK=true # Enable healthcheck endpoint: "/healthz"
+      - TS_LOCAL_ADDR_PORT=127.0.0.1:41234 # The <addr>:<port> for the healthz endpoint
+      #- TS_ACCEPT_DNS=true # Uncomment when using MagicDNS
+      - TS_AUTH_ONCE=true
+    configs:
+      - source: ts-serve
+        target: /config/serve.json
+    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:
+    #  - 0.0.0.0:${SERVICEPORT}:${SERVICEPORT} # Binding port ${SERVICEPORT} to the local network - may be removed if only exposure to your Tailnet is required
+    # 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}
+  application:
+    image: ${IMAGE_URL} # Image to be used
+    network_mode: service:tailscale # Sidecar configuration to route ${SERVICE} through Tailscale
+    container_name: app-${SERVICE} # Name for local container management
+    environment:
+      - EULA=TRUE # Required — accepted by the user
+      - TYPE=${SERVER_TYPE} # VANILLA, PAPER, FABRIC, FORGE, etc.
+      - VERSION=${MINECRAFT_VERSION} # e.g. LATEST or 1.21.4
+      - DIFFICULTY=${DIFFICULTY}
+      - MAX_PLAYERS=${MAX_PLAYERS}
+      - MOTD=${MOTD}
+      - MEMORY=${MEMORY}
+      - ONLINE_MODE=${ONLINE_MODE} # Set false for cracked/offline servers
+      - TZ=${TZ}
+    volumes:
+      - ./${SERVICE}-data:/data # Persistent world and server data
+    depends_on:
+      tailscale:
+        condition: service_healthy
+    restart: always