Documentación · índice

[10] Documentación

Hydrodactyl Installer.

Guía del instalador de Hydrodactyl: instalación con Docker o nativa, Wings/Elytra, nodo automático, SSL, actualización, desinstalación y solución de problemas.

Última revisión · noviembre 2026

Qué es

hydrodactyl-installer es un instalador, actualizador y desinstalador no oficial para el panel Hydrodactyl y sus daemons de juego (Pterodactyl Wings o pyrohost Elytra). Instala el panel con Docker o nativo, crea el nodo automáticamente, actualiza panel y daemons o lo elimina todo con un comando.

  • Escrito en Bash para Linux; interfaz en inglés y español.
  • Versión actual: v0.9.0. Es una versión temprana: pruébala en una VM desechable antes de usarla en producción.
  • Licencia GPLv3; repositorio en GitHub.
  • No está asociado oficialmente con Hydrodactyl, Blueprint ni Pterodactyl.
El instalador está pensado para administradores con acceso root. No lo ejecutes en una máquina con datos importantes sin backup y sin probar antes --dry-run.

Sistemas compatibles

SistemaVersiónPanel nativoPanel DockerDaemons
Ubuntu22.04 / 24.04 / 26.04SíSíSí
Debian12 / 13SíSíSí
Ubuntu20.04NoSíNo
Debian11NoSíNo
Rocky / AlmaLinux8 / 9NoSíNo
Fedora40+NoSíNo
Arch Linux—NoSíNo
  • Panel nativo: Ubuntu 22.04+ o Debian 12+, con PHP 8.4 desde los repositorios de ondrej/php o packages.sury.org.
  • Daemons: Ubuntu/Debian en amd64 o arm64, las únicas arquitecturas publicadas por Wings y Elytra.
  • Panel Docker: cualquier distribución donde se pueda instalar Docker Engine.

Instalación rápida

Ejecuta el script como root. Si usas una instalación mínima de Ubuntu, instala curl primero. El menú ofrece instalación, actualización y desinstalación.

apt update && apt install -y curl
bash <(curl -fsSL https://raw.githubusercontent.com/Jaie55/hydrodactyl-installer/main/install.sh)

También puedes fijar una etiqueta o rama del propio instalador:

HYDRODACTYL_SCRIPT_REF=v0.9.0 bash <(curl -fsSL https://raw.githubusercontent.com/Jaie55/hydrodactyl-installer/main/install.sh)
  • Básico: usa los valores por defecto y pregunta solo lo imprescindible.
  • Personalizado: pregunta cada opción con ejemplos (zona horaria, locale, puertos, PHP, firewall y recursos del nodo).
  • Producción o test: producción desactiva debug y activa comprobaciones estrictas de dominio/HTTPS; test activa debug.

Opciones de línea de comandos

Todas las opciones se pueden combinar en modo no interactivo con -y. Ejecuta --help para ver la lista exacta de la versión instalada.

OpciónQué hace
--dockerInstala el panel con Docker Compose.
--nativeInstala el panel de forma nativa con nginx, PHP-FPM y MariaDB/MySQL.
--basic / --customInstalación básica (por defecto) o personalizada.
--localModo local de pruebas: localhost, sin DNS ni SSL.
--environment=production|testProducción desactiva debug; test lo activa.
--source=stable|canary|customElige la rama del panel.
--repo=URLRepositorio del panel; implica --source=custom.
--ref=BRANCHRama o etiqueta del repositorio personalizado.
--domain=DOMAINDominio del panel; por defecto localhost en pruebas.
--dir=PATHDirectorio del panel; por defecto /var/www/hydrodactyl.
--db=mariadb|mysqlMotor de base de datos para la instalación nativa.
--db-name=NAMENombre de la base de datos (por defecto panel).
--db-user=USERUsuario de la base de datos (por defecto hydrodactyl).
--db-password=PASSContraseña de la base de datos; se genera si se omite.
--reset-dbBorra una base de datos nativa anterior si su .env/APP_KEY no es válido.
--php=8.4|8.5Versión de PHP para la instalación nativa.
--timezone=TZZona horaria de la aplicación (por defecto UTC).
--locale=LOCALEConfiguración regional (por defecto en-US).
--http-port=PORTPuerto HTTP del panel (por defecto 80).
--firewall / --no-firewallConfigura ufw (SSH, HTTP, HTTPS y puertos del daemon) o lo omite.
--daemon=wings|elytraInstala un daemon Wings o Elytra.
--daemon-config=PATHFichero de configuración del nodo descargado del panel.
--daemon-version=TAGVersión del daemon; por defecto la última.
--daemon-port=PORTPuerto de escucha del daemon (por defecto 8080).
--sftp-port=PORTPuerto SFTP (por defecto 2022).
--node-scheme=http|httpsEsquema del panel al daemon (por defecto http).
--behind-proxyEl nodo está detrás de un proxy.
--panel-url=URLURL del panel para configurar el nodo.
--api-key=KEYApplication API key; se crea sola para un panel local.
--node-name=NAMENombre del nodo (por defecto el hostname).
--node-fqdn=HOSTFQDN/IP del nodo accesible desde el panel.
--memory=MB / --disk=MBRecursos del nodo; por defecto se detectan.
--ports=LISTAsignaciones separadas por comas (por defecto 25565-25665,27015-27150).
--no-nodeNo crea el nodo automáticamente.
--test-server / --no-test-serverCrea u omite un servidor Minecraft de prueba.
--test-server-egg=EGGPlantilla del servidor de prueba (por defecto vanilla).
--test-server-port=PORTPuerto del servidor de prueba (por defecto 25565).
--test-server-memory=MBMemoria del servidor de prueba (por defecto 1024).
--test-server-disk=MBDisco del servidor de prueba (por defecto 5120).
--admin-email=EMAILCorreo del primer administrador.
--admin-username=NAMEUsuario del primer administrador (por defecto admin).
--admin-password=PASSContraseña del primer administrador; se genera si se omite.
--no-auto-adminNo crea el primer administrador automáticamente.
--check-updatesMuestra versiones instaladas y últimas disponibles.
--update[=panel|daemon]Actualiza el panel, los daemons o ambos.
--uninstall[=panel|daemon|all|wings|elytra]Desinstala los objetivos indicados.
--purgeCon --uninstall, borra también bases de datos y datos.
--sslSolicita un certificado Let's Encrypt.
--no-verifyOmite la comprobación final de que el panel responde.
--dry-runMuestra el plan y sale sin instalar.
--versionMuestra la versión del instalador.
--lang=en|esIdioma de la interfaz.
-y, --yesModo no interactivo con valores por defecto.
-h, --helpMuestra la ayuda.

Ejemplos con flags

ObjetivoComando
Panel con Docker + SSLsudo bash install.sh --docker --domain panel.example.com --ssl
Panel nativo desde canarysudo bash install.sh --native --source=canary --domain panel.example.com --ssl -y
Panel desde tu forksudo bash install.sh --native --repo=https://github.com/tu-usuario/hydrodactyl --ref=mi-rama --domain panel.example.com
Prueba local sin DNSsudo bash install.sh --native --local -y
Solo daemon Wingssudo bash install.sh --daemon=wings --panel-url=http://127.0.0.1 --api-key=ptla_xxx -y
Ver el plan sin instalarsudo bash install.sh --dry-run
  • --source=stable|canary|custom elige la rama del panel.
  • --environment=production|test controla debug, caché y avisos de dominio.
  • --db=mariadb|mysql, --php=8.4|8.5, --timezone, --locale y --http-port ajustan el panel nativo.
  • --reset-db borra una base de datos nativa anterior si su .env/APP_KEY no se puede usar.
  • --firewall / --no-firewall y --ssl configuran ufw y Let's Encrypt.
  • --daemon=wings|elytra, --daemon-port, --sftp-port y --node-scheme ajustan el daemon.
  • --test-server crea un servidor Minecraft de prueba en el puerto 25565; --no-test-server lo omite.
  • --check-updates, --update y --uninstall gestionan el ciclo de vida.

Nodo automático

Cuando el panel está en la misma máquina, el instalador crea la API key de aplicación con permisos limitados y configura el nodo sin copiar datos a mano.

  1. 01

    Admin inicial

    Crea el primer administrador si el panel no tiene ninguno. Las credenciales se imprimen al final y se guardan en /root/hydrodactyl-admin.txt.

  2. 02

    Location y nodo

    Crea una location si falta y reutiliza un nodo con el mismo FQDN o crea uno nuevo.

  3. 03

    Asignaciones

    Añade solo los puertos que faltan; por defecto 25565-25665,27015-27150.

  4. 04

    Daemon

    Ejecuta wings configure o elytra configure, inicia el servicio systemd y comprueba que escucha.

Si usas un panel remoto, pasa --panel-url y --api-key y no uses la creación automática del nodo. No compartas la API key ni la publiques en capturas.

Actualizar, desinstalar y probar

sudo bash install.sh --check-updates
sudo bash install.sh --update
sudo bash install.sh --update=panel
sudo bash install.sh --uninstall
sudo bash install.sh --uninstall --purge
  • --check-updates muestra la versión instalada y la última disponible del panel y los daemons.
  • --update actualiza el panel y los daemons detectados; --update=panel o --update=daemon limita el alcance.
  • --uninstall elimina servicios y configuración; --purge borra también bases de datos y datos. No hay vuelta atrás.
  • --local crea una instalación de prueba en localhost, sin DNS ni SSL, con admin automático.
  • --dry-run muestra el plan y sale sin instalar; úsalo antes de tocar producción.

Prueba local sin DNS

Para una máquina desechable no necesitas dominio público ni certificado. El modo local usa localhost, no requiere DNS y omite Let's Encrypt en localhost, *.test, *.local y direcciones privadas.

sudo bash install.sh --native --local -y
  • El instalador comprueba el panel contra 127.0.0.1 con curl --resolve.
  • Para abrir el panel desde otra máquina de la LAN, apunta el dominio a la IP del panel en tu /etc/hosts: echo '192.168.1.50 panel.test' | sudo tee -a /etc/hosts.
  • No uses --local en producción: el certificado y el acceso público quedan desactivados.

Qué hace cada modo

  • Docker: instala Docker si falta, descarga el docker-compose.example.yml oficial, rellena base de datos, dominio, zona horaria, locale y correo, y ejecuta docker compose up -d. Los datos viven en /srv/pterodactyl; ufw se omite porque Docker publica sus propios puertos.
  • Nativo: instala nginx, PHP, MariaDB/MySQL, Node.js + pnpm y Composer; clona el panel, crea la base de datos, escribe .env, ejecuta composer install, pnpm install, pnpm run build y migrate --seed; configura permisos, nginx, cron y el servicio de cola, y opcionalmente pide el certificado con certbot.
  • Reejecución: actualiza el repositorio a la referencia elegida con git reset --hard (se pierden cambios locales), reutiliza la contraseña de la base de datos del .env y reaplica la configuración.
  • Resumen final: muestra la URL del panel, las opciones elegidas, las credenciales del admin y el estado del nodo o del servidor de prueba.

Después de instalar

  • Revisa /root/hydrodactyl-admin.txt: contiene el correo y la contraseña generados del primer administrador. Cambia la contraseña al entrar.
  • La API key y el nodo se crean automáticamente cuando el panel está en la misma máquina. En un panel remoto, usa --panel-url y --api-key.
  • Si pediste --test-server, conéctate a <ip-del-nodo>:25565 y comprueba que el servidor aparece en el panel.
  • El registro completo del instalador queda en /var/log/hydrodactyl-installer.log.
  • Antes de reejecutar en producción, haz una copia de seguridad de la base de datos y de /srv/pterodactyl o /var/lib/pterodactyl.

Problemas habituales

  • El panel no responde: revisa nginx/PHP-FPM o los contenedores Docker, el firewall y el DNS del dominio.
  • SSL falla: el dominio debe apuntar a la IP y los puertos 80/443 deben estar libres. Prueba primero sin --ssl.
  • El nodo no conecta: comprueba la URL del panel, la API key, el FQDN y que el puerto del daemon esté abierto.
  • Puertos ocupados: usa --ports con un rango libre o --no-node y configura el nodo a mano.
  • Datos de admin: revisa /root/hydrodactyl-admin.txt; si no existe, crea el admin desde el panel o con artisan.
  • WebSocket 403 / `request origin not allowed`: Wings solo acepta el origen del navegador que coincide con la URL remote. Usa en el navegador la misma URL que el panel (APP_URL), edita /etc/pterodactyl/config.yml (remote) y ejecuta systemctl restart wings.
  • Wings no escucha en 8080: revisa systemctl status wings, journalctl -u wings -n 100 --no-pager y ss -ltnp | grep -E ':8080|:2022'; comprueba también que Docker esté en marcha con docker info.
  • Panel local inaccesible desde la LAN: localhost solo funciona en el servidor. Usa --domain=<ip-del-servidor> y accede por esa IP.
  • HTTP 500 al crear el nodo tras reinstalar: se conservó una base de datos anterior sin su .env/APP_KEY. Vuelve a ejecutar el instalador y acepta el borrado de la base de datos, o usa --reset-db.
  • API del panel devuelve un error: el instalador muestra ahora el código HTTP y el cuerpo de la respuesta para localizar el problema.
  • Wings está apagado al actualizar el nodo: el instalador continúa con la configuración actual del nodo en lugar de abortar la instalación.
  • Actualización Docker: haz una copia de seguridad de la base de datos antes de ejecutar --update.
  • `getcwd: cannot access parent directories`: el instalador cambia a / automáticamente, pero lo ideal es ejecutarlo desde /root o /tmp.
  • Bug del instalador: adjunta la versión, el sistema, el comando exacto y la salida con los datos sensibles ocultos en GitHub Issues.

Desarrollo y pruebas

for f in install.sh lib/*.sh lib/modes/*.sh lang/*.sh tests/*.sh; do bash -n "$f"; done
bash tests/run.sh
php -l config/panel-key.php
  • bash tests/run.sh ejecuta las pruebas unitarias (requiere jq).
  • Shellcheck se ejecuta en CI mediante .github/workflows/shellcheck.yml.
  • El instalador está pensado para una VM o contenedor nuevos con systemd. No lo pruebes contra un panel en producción: el modo nativo hace git reset --hard y vuelve a ejecutar migraciones.

Licencia

Copyright (C) 2026 Jaie55 y colaboradores. El instalador es software libre bajo GNU GPLv3: puedes usarlo, modificarlo y redistribuirlo conservando los avisos de copyright y publicando las versiones modificadas bajo la misma licencia. Hydrodactyl se distribuye aparte bajo Apache 2.0.

Notas y seguridad

  • El registro completo se escribe en /var/log/hydrodactyl-installer.log.
  • El script es idempotente en lo posible, pero está pensado para máquinas nuevas. Haz una copia de seguridad antes de reejecutarlo en un panel en producción.
  • Revisa el script antes de ejecutarlo como root y no publiques API keys, contraseñas ni capturas del resumen final.
  • Si distribuyes una versión modificada, conserva la licencia GPLv3 y los avisos de autoría.