Servidor Minecraft con Docker y Grafana
Resumen
El proyecto aborda el despliegue y la administración de un servidor multijugador de Minecraft Java. Sobre una máquina virtual Debian se implementó PaperMC para ejecutar el mundo, Prometheus para registrar su comportamiento y Grafana para consultar los resultados. Ocho scripts de Bash cubren la preparación de la máquina, el inicio de los servicios, la operación diaria y la programación de respaldos.
La validación se realizó con dos jugadores conectados por Wi-Fi. Durante la partida se comprobó que el contador de jugadores respondía a las conexiones y que una detonación de TNT coincidía con una caída en el ritmo de actualización del mundo. También se verificó la generación de una copia comprimida de los datos.
Problema y objetivos
Un jugador percibe un retraso cuando una acción tarda en reflejarse en pantalla. Esa observación, por sí sola, no identifica el origen: la conexión puede introducir demora, el servidor puede tardar en calcular el siguiente estado del mundo o la máquina puede estar bajo presión de recursos. El problema de administración consistía en registrar lo que ocurría en el servidor mientras los jugadores experimentaban ese retraso.
El objetivo general fue construir un servicio que pudiera desplegarse de nuevo a partir de archivos de configuración y cuyo funcionamiento pudiera examinarse durante una partida. Para evaluar ese objetivo se definieron tres comprobaciones concretas:
- Acceder al mismo mundo desde dos clientes y observar ambas conexiones desde el panel de administración.
- Registrar en el tiempo indicadores del juego y de Debian para relacionar un cambio de carga con sus efectos.
- Separar los datos del mundo del ciclo de vida del contenedor y comprobar la creación de un respaldo.
Arquitectura y flujo de datos
La máquina virtual se configuró en modo puente para que tuviera su propia dirección en la LAN. Los jugadores entraban a PaperMC desde Minecraft Java por el puerto 25565. Quien administraba la partida abría Grafana desde el navegador por el puerto 3000.
Docker Compose coordinaba cuatro contenedores. El complemento PrometheusExporter de PaperMC medía jugadores, entidades y memoria de Java. Node Exporter medía CPU, memoria, disco y red de Debian. Prometheus consultaba ambos cada 15 segundos y conservaba 15 días de datos. Grafana consultaba esas series para dibujar cuatro paneles. La recolección circulaba por la red interna de Docker.
Dos redes con funciones distintas
El adaptador puente conecta Debian a la red física del laboratorio. Un jugador utiliza la dirección de esa máquina para entrar al mundo. Dentro de Debian, Compose crea otra red para los contenedores. En ella, los servicios se encuentran por nombre: Prometheus lee mc-server:9225 y node-exporter:9100, y Grafana consulta prometheus:9090. Si Docker asigna otra IP a un contenedor al recrearlo, esos nombres siguen siendo válidos.
Qué se conserva al recrear un contenedor
El directorio /opt/minecraft-project de Debian contiene el estado de la plataforma. El montaje de mc-data en /data permite que una nueva instancia de PaperMC abra el mundo existente. prometheus-data contiene las series históricas y grafana-data almacena el estado de Grafana. Los archivos de grafana-provisioning describen cómo volver a conectar la fuente de datos y cargar los paneles.
Un montaje comparte archivos con el anfitrión y conserva sus permisos numéricos. Por eso el script asigna el mundo al usuario y grupo 1000:1000, los datos de Prometheus a 65534:65534 y los de Grafana a 472:472. Si un directorio no permite escribir al proceso correspondiente, la ruta puede existir y, aun así, impedir que se guarde una partida o una muestra.
Implementación y automatización
La implementación distingue el aprovisionamiento inicial de la operación cotidiana. Cada etapa inicial produce un recurso que necesita la siguiente: un motor de contenedores disponible, directorios con permisos y configuraciones, servicios en ejecución y una tarea periódica de respaldo. Una vez preparados esos recursos, las sesiones de juego utilizan cuatro scripts de operación.
Preparación del servidor
dependencia.shprepara Docker, Compose y las herramientas de Debian. Habilita cron para las tareas programadas.configuracion.shprepara los directorios persistentes y sus permisos, instala los complementos de PaperMC y configura los objetivos de Prometheus y los paneles de Grafana.despliegue.shgenera la definición de Compose, descarga las imágenes e inicia los cuatro servicios.backups.shprograma una copia diaria demc-dataa las 03:00. Comprime los datos en un archivo fechado y rota las copias antiguas.
Primera puesta en marcha. En una máquina Debian dedicada al proyecto, descarga los ocho scripts, descomprime el ZIP y abre una terminal en la carpeta extraída. Ejecuta cada etapa cuando la anterior haya terminado correctamente. La plantilla está preparada para una LAN de confianza; para un equipo con IP pública, revisa primero la configuración de acceso.
sudo bash dependencia.sh
sudo bash configuracion.sh
sudo bash despliegue.sh
sudo bash backups.sh
El tercer paso ya inicia los servicios. Comprueba su estado con sudo bash estado.sh y sigue el primer arranque con sudo docker logs -f mc-server. Cuando PaperMC anuncie Done, ya puedes entrar. Pulsa Ctrl+C para salir de la vista de registros.

Operación diaria
encender.shinicia el conjunto de servicios con el mundo guardado.estado.shmuestra cuáles están activos y cuánto procesador y memoria consume cada uno.consola.shabre la consola RCON para administrar la partida en marcha.apagar.shsolicita un cierre ordenado mediante Docker Compose.
Una sesión de ejemplo. Desde la carpeta de los scripts, ejecuta sudo bash encender.sh y entra desde Minecraft. Para observar la sesión en la LAN, abre http://IP_DE_LA_VM:3000 en el navegador, sustituyendo el marcador por la IP real. En Grafana, abre Minecraft Players y comprueba si aumenta el contador al entrar un segundo jugador. Después abre Minecraft Server para comparar el ritmo de los ticks con la actividad del mundo. Cuando todos salgan, ejecuta sudo bash apagar.sh.
Monitoreo e interpretación de indicadores
El proyecto recoge datos en dos niveles. En el nivel de aplicación se observa el trabajo que realiza PaperMC. En el nivel de sistema se mide la máquina Debian que lo sostiene. Comparar ambos durante el mismo intervalo permite investigar por qué una partida pierde fluidez.
- Jugadores, entidades y chunks
- El número de jugadores describe la concurrencia. Los chunks cargados representan regiones del mundo que el servidor mantiene disponibles. Dos jugadores próximos pueden compartir muchas de esas regiones; si exploran en direcciones distintas, la carga puede aumentar con el mismo número de conexiones.
- TPS y duración de los ticks
- Los TPS expresan el ritmo efectivo de la simulación y la duración del tick indica cuánto tarda una actualización. A 20 TPS, el presupuesto es de 50 ms por actualización. Una demora sostenida por encima de ese valor ayuda a explicar por qué las acciones del mundo empiezan a acumular retraso.
- Memoria de Java y recursos de Debian
- El panel de Minecraft sigue la memoria que usa la JVM. Node Exporter aporta la vista del anfitrión, donde también consumen recursos el sistema operativo y los demás contenedores. Para interpretar un pico se comparan las mismas marcas de tiempo en ambos paneles.
Prometheus toma muestras cada 15 segundos. Por eso una conexión puede tardar un intervalo de recolección, más el refresco de Grafana, en aparecer en pantalla. Una gráfica sirve para seguir tendencias y episodios de carga; su resolución temporal no permite reconstruir individualmente todos los ticks que ocurrieron entre dos muestras.


Metodología de prueba y resultados
La validación se realizó por etapas para distinguir un fallo de arranque de un fallo de recolección o de acceso al juego. Primero se consultó el estado de los cuatro contenedores. Después se comprobó, desde Prometheus, que los objetivos de recolección estaban activos. Finalmente entraron dos clientes al mundo desde la LAN y se contrastó su presencia con el contador de jugadores de Grafana. Esta última prueba recorrió la cadena completa: conexión del cliente, actualización del estado en PaperMC, lectura del exportador y visualización de la muestra.





Qué significó la caída de TPS
Minecraft intenta actualizar el mundo 20 veces por segundo. A ese ritmo dispone de 50 milisegundos por actualización o tick. La detonación de TNT concentró numerosos cambios de bloques en un intervalo breve. Durante ese episodio descendieron los ticks por segundo (TPS). El comportamiento es coherente con un hilo principal que necesita más tiempo para actualizar el mundo. La captura permite relacionar el evento con la pérdida de ritmo, aunque no cuantifica cuánto aportó cada recurso al retraso.

Verificación del respaldo
La evidencia de terminal muestra un archivo mc-backup-*.tar.gz en el directorio de respaldos, con su tamaño y marca de tiempo. Esta comprobación valida que la rutina produjo un archivo en la ubicación prevista. La recuperación del mundo a partir de ese archivo requiere una prueba adicional.

Cómo entrar y jugar una partida
- Consigue la dirección y la versión del juego. Pídeselas a quien administra el mundo. Dentro del mismo Wi-Fi se usa la IP local de la máquina Debian. Para entrar desde otra red, usa el dominio o la dirección pública que haya habilitado el administrador.
- Abre Minecraft: Java Edition con una versión compatible con el servidor. En el menú principal elige Multijugador y luego Añadir servidor. Ponle el nombre que quieras y escribe la dirección. Por ejemplo, si la IP de la máquina fuera
192.168.1.50, esa sería la dirección que escribirías desde la LAN. Si te indican un puerto distinto de 25565, añádelo después de la IP. - Guarda la entrada y selecciona «Entrar al servidor». Para jugar juntos, ambos jugadores eligen esa misma entrada desde sus respectivos equipos. Un modo sencillo de comprobarlo es encontrarse en el mundo y escribir un mensaje en el chat.



Si la partida aparece desconectada, comprueba primero que la versión del cliente coincide y que PaperMC terminó de arrancar. Si funciona desde el Wi-Fi pero falla desde otra red, revisa la ruta de acceso descrita en LAN e Internet.
Cómo ajustar el servidor a la máquina y a la partida
El proyecto asigna MEMORY: "2G" a PaperMC. Ese valor controla el espacio de memoria que Java usa para los objetos del juego, conocido como heap. Java también consume memoria fuera del heap. Debian, Docker, Grafana y Prometheus comparten la RAM física de la máquina.
Ejemplo de ajuste en Compose
En /opt/minecraft-project/docker-compose.yml, incorpora estas claves al servicio mc-server existente. El ejemplo supone una máquina con 8 GiB de RAM o más. Si la máquina virtual aún tiene los 4 GiB de la prueba, amplía primero su asignación o conserva un heap menor.
services:
mc-server:
environment:
MEMORY: "4G"
MAX_PLAYERS: "12"
VIEW_DISTANCE: "8"
SIMULATION_DISTANCE: "6"
- RAM de Java. Cambia
MEMORYpara ajustar a la vez el heap inicial y el máximo. Para que crezca con la partida, sustituye esa línea porINIT_MEMORY: "2G"yMAX_MEMORY: "4G". Si añades un límite total de contenedor conmem_limit, deja margen por encima del heap y comprueba el consumo bajo carga. - Jugadores.
MAX_PLAYERSfija los cupos simultáneos. Doce es un ejemplo de admisión. Para medir cuántos sostiene tu máquina, observa los TPS y el tiempo por tick mientras varios jugadores exploran zonas distintas. - Distancia visible.
VIEW_DISTANCEdetermina cuántos chunks alrededor de cada jugador envía el servidor. Un chunk mide 16 × 16 bloques en horizontal. Reducir el radio disminuye el terreno que debe mantener y transmitir. - Distancia de simulación.
SIMULATION_DISTANCEcontrola el radio donde el juego actualiza entidades y otras mecánicas. Con los valores del ejemplo, un jugador ve terreno más allá de la zona que sigue simulándose. - CPU. Las vCPU disponibles se asignan a la máquina virtual. La plantilla deja que Docker use la CPU disponible. Para imponer un techo al juego, añade, por ejemplo,
cpus: 2.0directamente bajomc-server, al mismo nivel queenvironment. Si los ticks superan 50 ms con memoria disponible, revisa la simulación, las entidades y la carga por núcleo antes de subir la RAM.
Aplicar y comprobar un cambio
Guarda una copia del mundo y avisa a los jugadores antes de recrear el servicio. Conserva el montaje ./mc-data:/data. Desde el directorio del proyecto, valida la configuración, aplica el cambio y comprueba el arranque.
cd /opt/minecraft-project
docker compose config --quiet
docker compose up -d --no-deps mc-server
docker compose logs --tail=60 mc-server
Compara en Grafana la memoria de Java, la RAM disponible de Debian y el tiempo por tick durante una actividad similar. Cuando el ajuste funcione, cópialo también a la plantilla de despliegue.sh. Ese script vuelve a generar el YAML cada vez que se ejecuta.
Métricas y copias de respaldo
Para cambiar la frecuencia de medición, ajusta scrape_interval en prometheus.yml y en la plantilla de configuracion.sh. El valor inicial es 15 segundos. Para conservar más historial, modifica --storage.tsdb.retention.time=15d en el servicio Prometheus. Medir con más frecuencia o guardar más días aumenta el uso de disco.
En backups.sh, 0 3 * * * programa la copia a las 03:00 según el reloj del servidor, y -mtime +7 selecciona copias antiguas para su eliminación. Tras editar el script, ejecútalo para actualizar la tarea de cron. Una prueba de recuperación consiste en extraer una copia en otro directorio y arrancar una instancia de prueba con ese mundo.
Documentación técnica: memoria de Java, propiedades de Minecraft y recursos y puertos de Compose.
Cómo se conectan los jugadores desde la LAN o Internet
PaperMC escucha conexiones de Minecraft Java por TCP. La línea "25565:25565" en Compose enlaza el puerto 25565 del anfitrión con el del contenedor. La dirección que se comparte depende de dónde esté el jugador.
- En la misma red. El cliente se conecta a la IP privada de la máquina virtual en modo puente. Conviene reservar esa IP en el router para que siga siendo la misma después de un reinicio.
- Desde Internet hacia una casa. Con IPv4 pública, configura en el router una redirección TCP del puerto 25565 a la IP privada de la máquina del juego. Permite ese tráfico en el cortafuegos correspondiente. Comparte la IP pública o un nombre DNS que apunte a ella. Si cambia periódicamente, un DNS dinámico permite conservar el mismo nombre. Si el proveedor usa CGNAT, la redirección doméstica por sí sola es insuficiente. Entre las opciones están solicitar una IP pública, usar una VPN compartida entre jugadores o alojar el servicio en un VPS.
- Desde Internet hacia un VPS. Publica el puerto del juego en Compose y permite TCP 25565 en las reglas del proveedor y del anfitrión. Los jugadores usan la IP pública o el dominio del VPS. Para comprobar la ruta completa, entra desde otra red, por ejemplo mediante datos móviles.
Identidad y administración
La demostración usó ONLINE_MODE: "FALSE" en una LAN de confianza. Para recibir conexiones desde Internet, configura ONLINE_MODE: "TRUE" antes de abrir el acceso. Así el servidor verifica la identidad de las cuentas. Para un grupo privado, activa la lista de admitidos y agrega los nombres autorizados. Si ya existe un mundo con jugadores en modo offline, prueba el cambio sobre una copia: sus identificadores pueden variar y afectar inventarios o permisos.
Publica hacia los jugadores únicamente el puerto del juego. Para administrar Grafana desde una máquina con IP pública, cambia su mapeo a "127.0.0.1:3000:3000" y accede por un túnel SSH. Cambia la contraseña inicial de Grafana. Prometheus, los exportadores y RCON pueden seguir en la red interna de Docker.
Conclusiones y alcance
La contribución del proyecto es una forma documentada de volver a construir y operar el servicio. Los scripts expresan cómo se prepara Debian, Compose describe cómo se relacionan los procesos y los directorios persistentes identifican qué datos deben sobrevivir al reemplazo de un contenedor. Esta separación permite intervenir sobre el despliegue conservando el mundo y su historial de monitoreo.
La evidencia respalda el funcionamiento multijugador en LAN y la capacidad de observar una alteración de rendimiento durante la partida. La prueba tuvo dos participantes y un episodio de carga controlada. Para establecer una capacidad máxima harían falta ensayos repetidos con distintos números de jugadores, patrones de exploración y configuraciones de recursos.
En continuidad operativa, la evidencia llega hasta la generación del archivo comprimido. El siguiente ensayo consiste en restaurarlo en una instancia independiente y comprobar que abre el mundo esperado. Una copia externa cubriría además la pérdida del disco que aloja tanto el mundo como sus respaldos. El acceso desde Internet se presenta como una adaptación de la arquitectura; la validación documentada corresponde a la red local.
Material del proyecto
- Leer el informe completo (PDF) · Arquitectura, decisiones y doce figuras de evidencia.
- Descargar la presentación (PowerPoint) · Las catorce diapositivas que guiaron la demostración.
- Descargar los ocho scripts (ZIP) · Archivos Bash del laboratorio.