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.
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.
--dry-run.Sistemas compatibles
| Sistema | Versión | Panel nativo | Panel Docker | Daemons |
|---|---|---|---|---|
| Ubuntu | 22.04 / 24.04 / 26.04 | Sí | Sí | Sí |
| Debian | 12 / 13 | Sí | Sí | Sí |
| Ubuntu | 20.04 | No | Sí | No |
| Debian | 11 | No | Sí | No |
| Rocky / AlmaLinux | 8 / 9 | No | Sí | No |
| Fedora | 40+ | No | Sí | No |
| Arch Linux | — | No | Sí | 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ón | Qué hace |
|---|---|
--docker | Instala el panel con Docker Compose. |
--native | Instala el panel de forma nativa con nginx, PHP-FPM y MariaDB/MySQL. |
--basic / --custom | Instalación básica (por defecto) o personalizada. |
--local | Modo local de pruebas: localhost, sin DNS ni SSL. |
--environment=production|test | Producción desactiva debug; test lo activa. |
--source=stable|canary|custom | Elige la rama del panel. |
--repo=URL | Repositorio del panel; implica --source=custom. |
--ref=BRANCH | Rama o etiqueta del repositorio personalizado. |
--domain=DOMAIN | Dominio del panel; por defecto localhost en pruebas. |
--dir=PATH | Directorio del panel; por defecto /var/www/hydrodactyl. |
--db=mariadb|mysql | Motor de base de datos para la instalación nativa. |
--db-name=NAME | Nombre de la base de datos (por defecto panel). |
--db-user=USER | Usuario de la base de datos (por defecto hydrodactyl). |
--db-password=PASS | Contraseña de la base de datos; se genera si se omite. |
--reset-db | Borra una base de datos nativa anterior si su .env/APP_KEY no es válido. |
--php=8.4|8.5 | Versión de PHP para la instalación nativa. |
--timezone=TZ | Zona horaria de la aplicación (por defecto UTC). |
--locale=LOCALE | Configuración regional (por defecto en-US). |
--http-port=PORT | Puerto HTTP del panel (por defecto 80). |
--firewall / --no-firewall | Configura ufw (SSH, HTTP, HTTPS y puertos del daemon) o lo omite. |
--daemon=wings|elytra | Instala un daemon Wings o Elytra. |
--daemon-config=PATH | Fichero de configuración del nodo descargado del panel. |
--daemon-version=TAG | Versión del daemon; por defecto la última. |
--daemon-port=PORT | Puerto de escucha del daemon (por defecto 8080). |
--sftp-port=PORT | Puerto SFTP (por defecto 2022). |
--node-scheme=http|https | Esquema del panel al daemon (por defecto http). |
--behind-proxy | El nodo está detrás de un proxy. |
--panel-url=URL | URL del panel para configurar el nodo. |
--api-key=KEY | Application API key; se crea sola para un panel local. |
--node-name=NAME | Nombre del nodo (por defecto el hostname). |
--node-fqdn=HOST | FQDN/IP del nodo accesible desde el panel. |
--memory=MB / --disk=MB | Recursos del nodo; por defecto se detectan. |
--ports=LIST | Asignaciones separadas por comas (por defecto 25565-25665,27015-27150). |
--no-node | No crea el nodo automáticamente. |
--test-server / --no-test-server | Crea u omite un servidor Minecraft de prueba. |
--test-server-egg=EGG | Plantilla del servidor de prueba (por defecto vanilla). |
--test-server-port=PORT | Puerto del servidor de prueba (por defecto 25565). |
--test-server-memory=MB | Memoria del servidor de prueba (por defecto 1024). |
--test-server-disk=MB | Disco del servidor de prueba (por defecto 5120). |
--admin-email=EMAIL | Correo del primer administrador. |
--admin-username=NAME | Usuario del primer administrador (por defecto admin). |
--admin-password=PASS | Contraseña del primer administrador; se genera si se omite. |
--no-auto-admin | No crea el primer administrador automáticamente. |
--check-updates | Muestra 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. |
--purge | Con --uninstall, borra también bases de datos y datos. |
--ssl | Solicita un certificado Let's Encrypt. |
--no-verify | Omite la comprobación final de que el panel responde. |
--dry-run | Muestra el plan y sale sin instalar. |
--version | Muestra la versión del instalador. |
--lang=en|es | Idioma de la interfaz. |
-y, --yes | Modo no interactivo con valores por defecto. |
-h, --help | Muestra la ayuda. |
Ejemplos con flags
| Objetivo | Comando |
|---|---|
| Panel con Docker + SSL | sudo bash install.sh --docker --domain panel.example.com --ssl |
| Panel nativo desde canary | sudo bash install.sh --native --source=canary --domain panel.example.com --ssl -y |
| Panel desde tu fork | sudo bash install.sh --native --repo=https://github.com/tu-usuario/hydrodactyl --ref=mi-rama --domain panel.example.com |
| Prueba local sin DNS | sudo bash install.sh --native --local -y |
| Solo daemon Wings | sudo bash install.sh --daemon=wings --panel-url=http://127.0.0.1 --api-key=ptla_xxx -y |
| Ver el plan sin instalar | sudo bash install.sh --dry-run |
--source=stable|canary|customelige la rama del panel.--environment=production|testcontrola debug, caché y avisos de dominio.--db=mariadb|mysql,--php=8.4|8.5,--timezone,--localey--http-portajustan el panel nativo.--reset-dbborra una base de datos nativa anterior si su.env/APP_KEY no se puede usar.--firewall/--no-firewally--sslconfiguran ufw y Let's Encrypt.--daemon=wings|elytra,--daemon-port,--sftp-porty--node-schemeajustan el daemon.--test-servercrea un servidor Minecraft de prueba en el puerto 25565;--no-test-serverlo omite.--check-updates,--updatey--uninstallgestionan 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.
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.02
Location y nodo
Crea una location si falta y reutiliza un nodo con el mismo FQDN o crea uno nuevo.
03
Asignaciones
Añade solo los puertos que faltan; por defecto
25565-25665,27015-27150.04
Daemon
Ejecuta
wings configureoelytra configure, inicia el servicio systemd y comprueba que escucha.
--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-updatesmuestra la versión instalada y la última disponible del panel y los daemons.--updateactualiza el panel y los daemons detectados;--update=panelo--update=daemonlimita el alcance.--uninstallelimina servicios y configuración;--purgeborra también bases de datos y datos. No hay vuelta atrás.--localcrea una instalación de prueba enlocalhost, sin DNS ni SSL, con admin automático.--dry-runmuestra 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.1concurl --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
--localen 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.ymloficial, rellena base de datos, dominio, zona horaria, locale y correo, y ejecutadocker 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, ejecutacomposer install,pnpm install,pnpm run buildymigrate --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.envy 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-urly--api-key. - Si pediste
--test-server, conéctate a<ip-del-nodo>:25565y 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/pterodactylo/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
--portscon un rango libre o--no-nodey 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 ejecutasystemctl restart wings. - Wings no escucha en 8080: revisa
systemctl status wings,journalctl -u wings -n 100 --no-pageryss -ltnp | grep -E ':8080|:2022'; comprueba también que Docker esté en marcha condocker info. - Panel local inaccesible desde la LAN:
localhostsolo 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/rooto/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.shejecuta las pruebas unitarias (requierejq).- 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 --hardy 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.