🎮 Servidor Hytale Docker

Servidor de Hytale en contenedor Docker con descarga automática de assets y soporte para autenticación OAuth2

Características • Instalación • Uso • Configuración

📋 Estado

✅ Funcionando y listo para producción

Este proyecto es completamente funcional y listo para uso en producción. Todas las características funcionan como se pretende.

✨ Características

🚀 Descarga automática de assets de Hytale mediante CLI oficial
🔐 Autenticación OAuth2 mediante Device Code Flow
🔄 Refresco automático de tokens - Tokens de sesión se refrescan en cada inicio
💾 Persistencia de datos en volúmenes Docker
⚡ Smart caching - Solo descarga cuando es necesario
🧹 Limpieza automática de archivos temporales
🔍 Verificación de tokens - Fácil chequeo de estado de tokens
🔄 Modos flexibles - Offline o Autenticado
🏗️ Multi-arquitectura - Soporte para x86_64 y ARM64

📦 Requisitos

Requisito	Versión mínima	Notas
Docker	20.10+	Instalar
Docker Compose	2.0+	Instalar
macOS	Apple Silicon	Requiere emulación x86_64

🚀 Instalación

Opción A: Usar imagen publicada (recomendado)

# Clonar el repositorio
git clone <repo-url>
cd HytaleDocker

# Importante: Modificar docker-compose.yml para usar tu imagen
# ghcr.io/dogalyir/hytale-server-docker:main
# Esta imagen se construye automáticamente en GitHub Container Registry cuando haces push a main

# Iniciar el servidor
docker-compose up -d

💡 Tip: La imagen se construye automáticamente en GitHub Container Registry cada vez que haces push a la rama main.

Opción B: Construir localmente

# Clonar el repositorio
git clone <repo-url>
cd HytaleDocker

# Descomentar la línea 'build: .' en docker-compose.yml
# Comentar la línea 'image: ...'

# Construir e iniciar
docker-compose up -d --build

🎯 Uso

1️⃣ Modo Offline (sin autenticación)

Para pruebas locales sin conexión a servicios de Hytale:

docker-compose up -d

2️⃣ Modo Autenticado (OAuth2 Device Code Flow)

Para producción y conexión con jugadores:

📝 Paso 1: Obtener tokens de autenticación

# Ejecutar el script interactivo de autenticación
./auth.sh

📖 ¿Qué hace el script?

El auth.sh automatiza todo el proceso OAuth2 Device Code Flow:

🔄 Solicita un device_code a los servidores de Hytale OAuth
🌐 Muestra URL y código para autorización en navegador
⏳ Espera que completes la autorización (hasta 15 min)
🎉 Obtiene access_token y refresh_token
🎮 Crea sesión de juego mediante API
💾 Guarda tokens en hytale_tokens.env

🚀 Paso 2: Iniciar el servidor autenticado

# Cargar tokens e iniciar el servidor
docker-compose --env-file hytale_tokens.env up -d

🔄 Gestión automática de tokens

⚡ Gestión automática de tokens - ¡El servidor hace todo por ti!

Cómo funciona:

Configuración inicial: Ejecuta ./auth.sh una vez para generar los tokens
Guardado automático: Los tokens se guardan automáticamente en hytale_data/.tokens/tokens.env
Refresco automático: En cada inicio del servidor, el entrypoint:
- Carga los tokens guardados desde hytale_data/.tokens/
- Refresca el access token de OAuth usando el refresh_token
- Crea una nueva sesión de juego con el access_token refrescado
- Guarda todos los tokens actualizados
Operación continua: ¡No necesitas preocuparte por refrescar tokens!

Expiración de tokens:

Tipo de Token	Expiración	¿Auto-refrescado?
OAuth Access Token	1 hora	✅ Sí
OAuth Refresh Token	30 días	❌ No (ejecutar `./auth.sh`)
Game Session	1 hora	✅ Sí (en cada inicio)

Refresco manual (si es necesario):

# Volver a ejecutar el script de autenticación para refrescar todos los tokens (cada 30 días)
./auth.sh

Verificar estado de tokens:

# Verificar validez de tokens y expiración
./check-tokens.sh

# O verificar tokens en un contenedor corriendo
docker exec hytale-server /check-tokens.sh

💡 Mejor práctica: Proporciona los tokens de OAuth (HYTALE_ACCESS_TOKEN, HYTALE_REFRESH_TOKEN, HYTALE_PROFILE_UUID) una sola vez. El servidor los guardará automáticamente en hytale_data/.tokens/ y refrescará los tokens de sesión en cada inicio!

⚙️ Configuración

📂 Estructura de archivos

hytale-docker/
├── 🐳 Dockerfile                      # Imagen del contenedor
├── 📦 docker-compose.yml               # Orquestación del servicio
├── 🔧 entrypoint.sh                    # Script de inicialización
├── 🔐 auth.sh                        # Script de autenticación OAuth2
├── 🔍 check-tokens.sh                # Script de verificación de tokens
├── 💎 hytale_tokens.env                # Tokens generados (creado automáticamente)
├── 📝 hytale_tokens.env.example        # Ejemplo de archivo de tokens
├── 📚 README.md                        # Documentación en inglés
├── 📚 README_ES.md                     # Esta documentación
├── 🔄 .github/
│   └── workflows/
│       └── docker-build.yml           # GitHub Actions workflow
└── 🗄️ hytale_data/                     # Datos del servidor (creado automáticamente)
    ├── Server/                         # Archivos del servidor
    │   ├── HytaleServer.jar
    │   ├── config.json
    │   └── ...
    ├── Assets.zip                      # Assets del juego
    ├── universe/                       # Mundos y saves
    ├── logs/                           # Logs del servidor
    ├── .cache/                         # Cache optimizado
    └── .tokens/                        # Tokens auto-refrescados (creado por entrypoint)
        └── tokens.env                  # Tokens OAuth y de sesión guardados

🔧 Variables de entorno

Variable	Descripción	Default
`HYTALE_SERVER_SESSION_TOKEN`	Token de sesión del servidor (JWT, refrescado automáticamente)	-
`HYTALE_SERVER_IDENTITY_TOKEN`	Token de identidad del servidor (JWT, refrescado automáticamente)	-
`HYTALE_ACCESS_TOKEN`	OAuth access token (para auto-refresco)	-
`HYTALE_REFRESH_TOKEN`	OAuth refresh token (válido 30 días)	-
`HYTALE_PROFILE_UUID`	UUID del perfil para crear sesión	-
`WORKDIR`	Directorio de trabajo del servidor	`/app`

🌐 Puertos

Puerto	Protocolo	Descripción
`5520`	UDP	Puerto por defecto del servidor Hytale (QUIC)

⚠️ Importante: Hytale usa QUIC sobre UDP, no TCP. Asegúrate de configurar firewalls y port forwarding correctamente.

🔧 Para cambiar el puerto, modifica el archivo docker-compose.yml o usa la variable de entorno del servidor.

🛠️ Comandos útiles

# Ver logs del servidor en tiempo real
docker-compose logs -f

# Detener el servidor
docker-compose down

# Reconstruir la imagen desde cero
docker-compose build --no-cache

# Reiniciar el servidor
docker-compose restart

# Limpiar todos los datos del servidor (¡cuidado!)
rm -rf hytale_data/

# Verificar estado del contenedor
docker ps -a | grep hytale-server

📝 Notas importantes

🔒 Sobre la autenticación

El servidor requiere autenticación para aceptar conexiones de jugadores
Los tokens de sesión expiran cada hora y se refrescan automáticamente al iniciar el servidor si se proporcionan tokens OAuth
Los refresh tokens de OAuth son válidos por 30 días - después necesitas volver a ejecutar ./auth.sh
El sistema de refresco automático usa el siguiente flujo:
1. Servidor inicia → entrypoint verifica tokens OAuth
2. Refresca el access token de OAuth usando refresh_token
3. Crea nueva sesión de juego con el access_token fresco
4. Guarda todos los nuevos tokens para el próximo reinicio
El límite predeterminado es de 100 servidores concurrentes por licencia de juego

💡 Sobre el rendimiento

RAM mínima: 4GB (recomendado 8GB+ para múltiples jugadores)
El servidor usa protocolo QUIC para mejor rendimiento
Considera limitar la view distance para reducir consumo de RAM
Los assets se descargan solo la primera vez o cuando se actualizan

🔄 Sobre las actualizaciones

Los archivos del servidor se mantienen en hytale_data/
Para actualizar, borra hytale_data/Server/ y reinicia el servidor
Los mundos y configuraciones en universe/ se conservan
Los assets se verifican automáticamente al inicio

🔗 Recursos

📄 Licencia

Este proyecto está bajo la Licencia MIT - ver el archivo LICENSE para detalles.

Hecho con ❤️ para la comunidad de Hytale

⬆ Volver al inicio

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

🎮 Servidor Hytale Docker

📋 Estado

✨ Características

📦 Requisitos

🚀 Instalación

Opción A: Usar imagen publicada (recomendado)

Opción B: Construir localmente

🎯 Uso

1️⃣ Modo Offline (sin autenticación)

2️⃣ Modo Autenticado (OAuth2 Device Code Flow)

📝 Paso 1: Obtener tokens de autenticación

🚀 Paso 2: Iniciar el servidor autenticado

🔄 Gestión automática de tokens

⚙️ Configuración

📂 Estructura de archivos

🔧 Variables de entorno

🌐 Puertos

🛠️ Comandos útiles

📝 Notas importantes

🔗 Recursos

📄 Licencia

Uh oh!

FilesExpand file tree

README_ES.md

Latest commit

History

README_ES.md

File metadata and controls

🎮 Servidor Hytale Docker

📋 Estado

✨ Características

📦 Requisitos

🚀 Instalación

Opción A: Usar imagen publicada (recomendado)

Opción B: Construir localmente

🎯 Uso

1️⃣ Modo Offline (sin autenticación)

2️⃣ Modo Autenticado (OAuth2 Device Code Flow)

📝 Paso 1: Obtener tokens de autenticación

🚀 Paso 2: Iniciar el servidor autenticado

🔄 Gestión automática de tokens

⚙️ Configuración

📂 Estructura de archivos

🔧 Variables de entorno

🌐 Puertos

🛠️ Comandos útiles

📝 Notas importantes

🔗 Recursos

📄 Licencia