Para instalar Pterodactyl en un VPS Ubuntu 24.04 necesitas un servidor KVM con acceso root, un dominio, Docker, PHP 8.3, MariaDB, Redis, nginx y certificados TLS. En esta guía configuraremos manualmente el Panel y Wings, verificaremos cada servicio y dejaremos claro cómo volver atrás si algo falla.
Compatibilidad usada en esta guía: Ubuntu 24.04 LTS, Pterodactyl Panel 1.12, Wings 1.12, PHP 8.3, MariaDB y nginx. La documentación oficial también admite Ubuntu 22.04 y Debian 11, 12 y 13. Wings no funciona en Windows y suele fallar en OpenVZ, Virtuozzo o LXC; KVM es la opción segura.
Qué es Pterodactyl y cómo se divide
Pterodactyl es un panel de administración de servidores de juegos que ejecuta cada instancia dentro de contenedores Docker aislados. La arquitectura tiene dos piezas:
- Panel: interfaz web, usuarios, bases de datos, ubicaciones, nodos, servidores y permisos.
- Wings: daemon que corre en cada nodo, controla Docker, almacenamiento, consola, SFTP y recursos.
Puedes instalar ambos en el mismo VPS para un entorno pequeño. Para producción o varios nodos, conviene separar el Panel del servidor donde se ejecutan los juegos.
Requisitos previos
- VPS KVM con Ubuntu 24.04 de 64 bits.
- Acceso root o usuario con sudo.
- Dominio o subdominio apuntando a la IPv4 del VPS.
- Al menos 2 GB de RAM para una instalación pequeña; 4 GB o más si Panel y Wings compartirán servidor.
- Puertos 80 y 443 para el Panel; 8080 para Wings y 2022 para SFTP, salvo que uses otros.
- Una copia de seguridad o snapshot antes de comenzar.
Comprueba la virtualización
systemd-detect-virt
uname -r
Si el primer comando devuelve kvm, puedes continuar. Si muestra openvz, lxc o virtuozzo, confirma con tu proveedor que Docker y las funciones de red necesarias están habilitadas.
1. Actualiza Ubuntu y crea un respaldo básico
sudo apt update
sudo apt upgrade -y
sudo mkdir -p /root/pterodactyl-backup
sudo cp -a /etc/nginx /root/pterodactyl-backup/nginx-before 2>/dev/null || true
Si el proveedor permite snapshots, créalo ahora. El rollback más limpio de una instalación nueva es restaurar ese snapshot.
2. Instala las dependencias del Panel
sudo apt install -y software-properties-common curl ca-certificates gnupg tar unzip git
sudo apt update
sudo apt install -y php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx redis-server
sudo systemctl enable --now mariadb nginx redis-server php8.3-fpm
Verifica las versiones:
php -v
mariadb --version
nginx -v
redis-cli ping
redis-cli ping debe responder PONG.
3. Instala Composer
curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer
composer --version
4. Crea la base de datos
Entra a MariaDB:
sudo mariadb
Cambia UNA_CLAVE_LARGA_Y_UNICA por una contraseña real:
CREATE DATABASE panel;
CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'UNA_CLAVE_LARGA_Y_UNICA';
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1';
FLUSH PRIVILEGES;
EXIT;
5. Descarga e instala Pterodactyl Panel
sudo mkdir -p /var/www/pterodactyl
cd /var/www/pterodactyl
sudo curl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz
sudo tar -xzvf panel.tar.gz
sudo chmod -R 755 storage bootstrap/cache
sudo cp .env.example .env
sudo COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader
sudo php artisan key:generate --force
Respalda APP_KEY
grep APP_KEY /var/www/pterodactyl/.env
Guarda esa línea fuera del servidor. Sin APP_KEY, los datos cifrados no podrán recuperarse aunque tengas copia de la base de datos.
6. Configura el entorno y migra la base
cd /var/www/pterodactyl
sudo php artisan p:environment:setup
sudo php artisan p:environment:database
sudo php artisan p:environment:mail
sudo php artisan migrate --seed --force
sudo php artisan p:user:make
sudo chown -R www-data:www-data /var/www/pterodactyl
Usa la URL HTTPS definitiva del Panel durante el asistente. Para correo, selecciona SMTP si dispones de credenciales; la función mail de PHP no es recomendable en producción.
7. Configura nginx
Crea el virtual host:
sudo nano /etc/nginx/sites-available/pterodactyl.conf
server {
listen 80;
listen [::]:80;
server_name panel.ejemplo.com;
root /var/www/pterodactyl/public;
index index.php;
client_max_body_size 100m;
client_body_timeout 120s;
sendfile off;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
fastcgi_param PHP_VALUE "upload_max_filesize=100M \n post_max_size=100M";
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_read_timeout 300;
}
location ~ /\.ht {
deny all;
}
}
Activa el sitio y valida la configuración:
sudo ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/pterodactyl.conf
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx
8. Activa HTTPS con Let's Encrypt
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d panel.ejemplo.com
sudo certbot renew --dry-run
No continúes con Wings bajo TLS hasta que el dominio resuelva correctamente y el certificado sea válido.
9. Configura cron y el worker de colas
Edita el crontab de root:
sudo crontab -e
Añade:
* * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1
Ejecuta Pterodactyl sobre un VPS KVM
Elige un VPS con virtualización KVM para instalar Docker, Panel y Wings sin las limitaciones habituales de OpenVZ o LXC.
Crea el servicio:
sudo nano /etc/systemd/system/pteroq.service
[Unit]
Description=Pterodactyl Queue Worker
After=redis-server.service
[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/pterodactyl/artisan queue:work --queue=high,standard,low --sleep=3 --tries=3
StartLimitInterval=180
StartLimitBurst=30
RestartSec=5s
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now pteroq.service
sudo systemctl status pteroq.service --no-pager
10. Instala Docker desde el repositorio oficial
sudo apt remove -y docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc || true
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker run --rm hello-world
Importante: los puertos publicados por Docker pueden saltarse reglas de UFW. Filtra tráfico con las cadenas compatibles de iptables y la cadena DOCKER-USER, o aplica el firewall en el proveedor.
11. Instala Wings
sudo mkdir -p /etc/pterodactyl
sudo curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
sudo chmod u+x /usr/local/bin/wings
/usr/local/bin/wings --version
12. Crea el nodo y carga config.yml
- Entra al Panel como administrador.
- Abre Nodes y crea un nodo.
- Define el FQDN de Wings, por ejemplo
node1.ejemplo.com. - Abre la pestaña Configuration.
- Copia el YAML a
/etc/pterodactyl/config.ymlo ejecuta el comando de token generado por el Panel.
Si el Panel usa HTTPS, Wings también debe usar un certificado válido para su FQDN.
13. Prueba Wings y créalo como servicio
sudo wings --debug
Cuando arranque sin errores, pulsa Ctrl+C y crea:
sudo nano /etc/systemd/system/wings.service
[Unit]
Description=Pterodactyl Wings Daemon
After=docker.service
Requires=docker.service
PartOf=docker.service
[Service]
User=root
WorkingDirectory=/etc/pterodactyl
LimitNOFILE=4096
PIDFile=/var/run/wings/daemon.pid
ExecStart=/usr/local/bin/wings
Restart=on-failure
StartLimitInterval=180
StartLimitBurst=30
RestartSec=5s
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now wings
sudo systemctl status wings --no-pager
14. Configura asignaciones y firewall
En el nodo, crea las allocations con la IP pública y los puertos que usarán los servidores. No uses 127.0.0.1.
hostname -I | awk '{print $1}'
sudo ss -lntup
Abre únicamente los puertos necesarios. Como referencia:
- 80/tcp y 443/tcp: Panel.
- 8080/tcp: API de Wings, si mantuviste el valor predeterminado.
- 2022/tcp: SFTP administrado por Wings.
- Rango de allocations: solo los puertos realmente asignados a juegos.
Checklist de verificación
sudo nginx -t
sudo systemctl is-active nginx php8.3-fpm mariadb redis-server pteroq docker wings
curl -I https://panel.ejemplo.com
sudo journalctl -u pteroq -n 50 --no-pager
sudo journalctl -u wings -n 100 --no-pager
sudo docker info
La instalación está lista cuando puedes iniciar sesión, el nodo aparece con corazón verde, Wings responde sin errores y un servidor de prueba puede instalarse, iniciar y aceptar conexiones.
Errores comunes
El nodo aparece en rojo
Revisa DNS, certificado, FQDN y puerto de Wings. Comprueba que el Panel pueda alcanzar el nodo y que el reloj del sistema esté sincronizado.
dig +short node1.ejemplo.com
curl -vk https://node1.ejemplo.com:8080
sudo timedatectl status
Wings no puede comunicarse con Docker
sudo systemctl status docker --no-pager
sudo docker info
sudo journalctl -u docker -n 100 --no-pager
Confirma que el VPS no usa una virtualización incompatible y que el kernel no tenga modificaciones restrictivas.
502 Bad Gateway en el Panel
sudo systemctl status php8.3-fpm --no-pager
ls -l /run/php/php8.3-fpm.sock
sudo tail -n 100 /var/log/nginx/error.log
El socket configurado en nginx debe coincidir con el socket real de PHP-FPM.
Las tareas o correos no se procesan
sudo systemctl status pteroq --no-pager
sudo journalctl -u pteroq -n 100 --no-pager
sudo crontab -l
redis-cli ping
Rollback y desinstalación
Antes de desinstalar, respalda .env, la base de datos y APP_KEY:
sudo cp /var/www/pterodactyl/.env /root/pterodactyl-backup/
sudo mariadb-dump panel > /root/pterodactyl-backup/panel.sql
sudo tar -czf /root/pterodactyl-backup/pterodactyl-files.tar.gz /var/www/pterodactyl /etc/pterodactyl
Para detener la instalación sin borrar datos:
sudo systemctl disable --now wings pteroq
sudo systemctl stop nginx
Si era un VPS nuevo, restaurar el snapshot previo es más seguro que eliminar paquetes uno por uno.
Mantenimiento posterior
- Revisa las notas de versiones de Panel y Wings antes de actualizar.
- Respalda base de datos,
.env,APP_KEY,config.ymly datos de servidores. - Aplica actualizaciones de seguridad de Ubuntu con regularidad.
- Monitorea disco, RAM, CPU, I/O y espacio consumido por imágenes Docker.
- No expongas bases de datos ni Redis directamente a Internet.
- Usa autenticación de dos factores para administradores.
Preguntas frecuentes
¿Puedo instalar Panel y Wings en el mismo VPS?
Sí, para pruebas o instalaciones pequeñas. En producción, separarlos mejora el aislamiento y facilita escalar nodos.
¿Pterodactyl funciona en OpenVZ o LXC?
No es una opción fiable. La documentación oficial advierte que suele fallar por limitaciones de Docker. Usa KVM o un servidor dedicado.
¿Necesito un dominio?
Es muy recomendable y prácticamente necesario para una configuración HTTPS limpia de Panel y Wings.
¿Cuánta RAM necesita?
El Panel puede funcionar con recursos modestos, pero los juegos determinan el consumo real. Calcula por servidor, jugadores, mods, plugins y carga, y deja margen para Docker, caché y sistema operativo.
Conclusión
Una instalación correcta de Pterodactyl no termina cuando aparece la pantalla de login. Debes validar colas, cron, Docker, Wings, TLS, allocations, backups y recuperación. Esa diferencia convierte una instalación que “parece funcionar” en una plataforma administrable.