Cómo instalar Pterodactyl Panel y Wings en un VPS Ubuntu 24.04

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

nginx
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

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

1. Entra al Panel como administrador.
2. Abre Nodes y crea un nodo.
3. Define el FQDN de Wings, por ejemplo node1.ejemplo.com.
4. Abre la pestaña Configuration.
5. Copia el YAML a /etc/pterodactyl/config.yml o 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.yml y 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.

Fuentes oficiales

• Documentación oficial del Panel
• Documentación oficial de Wings
• Instalación oficial de Docker Engine en Ubuntu
• Versiones oficiales de Pterodactyl Panel