Cómo instalar Pterodactyl en un VPS Linux

BoxToPlay-helper · June 19, 2026, 3:26pm

Instalar Pterodactyl en un servidor VPS Linux

Pterodactyl (también puedes consultar su repositorio oficial de GitHub) es un panel de gestión open source para servidores de juegos basado en dos componentes separados: el Panel, que proporciona la interfaz web de administración, y Wings, que ejecuta los servicios en el nodo mediante Docker. Si quieres desplegar esta solución en un servidor VPS, debes preparar correctamente Linux, la base de datos, el servidor web y luego conectar el nodo al panel.

Esta guía se ha probado en un VPS Ubuntu 24.04.4 LTS, con Pterodactyl Panel 1.12.4 y Wings 1.12.3. Los comandos siguientes se mantienen cerca de la documentación oficial, pero añaden las comprobaciones prácticas que a menudo solo se descubren durante la instalación.

Qué tendrás al final

Al terminar la instalación, tendrás:

un Panel Pterodactyl accesible desde la web.
una primera cuenta de administrador.
un servicio de cola funcional.
un nodo Wings conectado al panel.
asignaciones de IP y puertos listas para usarse.

Esta es la interfaz de administración obtenida después de instalar el Panel:

Requisitos previos antes de empezar

Antes de instalar nada, comprueba los puntos siguientes:

tienes acceso root a tu VPS.
utilizas una distribución Linux compatible, por ejemplo Ubuntu 22.04, Ubuntu 24.04, Debian 11, Debian 12 o Debian 13.
tu entorno soporta Docker.
no estás en un entorno OpenVZ o LXC incompatible con Docker.
tienes un nombre de dominio para el panel, e idealmente un subdominio separado para el nodo Wings.

Para Wings, el punto crítico es la compatibilidad con Docker. Si tu virtualización no soporta correctamente los contenedores, el nodo no podrá funcionar con normalidad.

Puedes comprobar la virtualización con:

systemd-detect-virt

En un VPS KVM, el comando puede devolver por ejemplo:

kvm

Si necesitas instalar Docker en tu máquina antes de continuar, te recomendamos seguir nuestra guía dedicada: Instalar Docker en Linux, guía práctica para empezar.

Paso 1: instalar las dependencias del Panel

El Panel Pterodactyl requiere especialmente:

PHP 8.2 o 8.3.
MariaDB o MySQL.
Redis.
NGINX u otro servidor web.
Composer v2.
curl, tar, unzip, git y lsb-release.

El ejemplo siguiente está pensado para una base Ubuntu con NGINX, MariaDB, Redis y PHP 8.3. En Debian, adapta los repositorios PHP en lugar de usar el PPA de Ubuntu.

apt update
apt -y install software-properties-common curl apt-transport-https ca-certificates gnupg lsb-release
LC_ALL=C.UTF-8 add-apt-repository -y ppa:ondrej/php
curl -fsSL https://packages.redis.io/gpg | gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/redis.list
apt update
apt -y install php8.3 php8.3-common php8.3-cli php8.3-gd php8.3-mysql php8.3-mbstring php8.3-bcmath php8.3-xml php8.3-fpm php8.3-curl php8.3-zip mariadb-server nginx tar unzip git redis-server

Instala después Composer:

curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

Si ejecutas Composer como root, algunos comandos pueden mostrar una advertencia interactiva. Para la instalación del Panel, utiliza COMPOSER_ALLOW_SUPERUSER=1 como se indica más abajo.

Paso 2: descargar los archivos del Panel

Crea el directorio de instalación, entra en él y descarga los archivos del panel.

mkdir -p /var/www/pterodactyl
cd /var/www/pterodactyl
curl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz
tar -xzvf panel.tar.gz
chmod -R 755 storage/* bootstrap/cache/

Paso 3: preparar la base de datos

El panel necesita una base de datos dedicada y un usuario con los permisos necesarios. Elige una contraseña segura y guárdala, porque se pedirá durante la configuración del entorno.

Conéctate a MariaDB:

mariadb -u root -p

Después, en la consola SQL:

CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'yourStrongPassword';
CREATE DATABASE panel;
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1' WITH GRANT OPTION;
exit

Utiliza 127.0.0.1 en lugar de localhost para evitar problemas de socket MySQL cuando el Panel se conecta a la base de datos.

Paso 4: configurar el Panel Pterodactyl

Copia el archivo de entorno, instala las dependencias PHP del proyecto y genera la clave de aplicación.

cd /var/www/pterodactyl
cp .env.example .env
COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader
php artisan key:generate --force

Después, lanza la configuración interactiva:

php artisan p:environment:setup
php artisan p:environment:database
php artisan p:environment:mail

Puntos importantes durante estos asistentes:

la URL del panel debe empezar por https:// o http://.
utiliza 127.0.0.1 como host MariaDB si la base de datos es local.
para la cola, se recomienda Redis.
si todavía no tienes SMTP, configura temporalmente el mailer en modo log o vuelve más tarde con una configuración de correo real.

Luego inicializa la base de datos:

php artisan migrate --seed --force

Por último, crea la primera cuenta de administrador:

php artisan p:user:make

Guardar una copia de APP_KEY

La variable APP_KEY es esencial. Sirve para cifrar los datos sensibles del panel. Si la pierdes, los datos cifrados no podrán restaurarse correctamente.

Para mostrarla:

grep APP_KEY /var/www/pterodactyl/.env

Guarda este valor en un lugar seguro fuera del servidor, junto con una copia de seguridad de tu archivo .env.

Paso 5: aplicar los permisos correctos

En un sistema Linux con NGINX, aplica los permisos al usuario web correcto:

chown -R www-data:www-data /var/www/pterodactyl

Paso 6: configurar el servidor web NGINX

Para que el panel sea accesible, debes configurar NGINX e instalar un certificado SSL con Certbot. En producción, prepara un nombre de dominio que ya apunte a la IP del VPS antes de solicitar el certificado.

Instala Certbot y su plugin NGINX:

apt update
apt -y install certbot python3-certbot-nginx

Genera el certificado SSL para tu nombre de dominio, sustituyendo panel.example.com por tu subdominio real:

certbot certonly --nginx -d panel.example.com

Después crea el archivo de configuración NGINX /etc/nginx/sites-available/pterodactyl.conf:

server {
    listen 80;
    server_name panel.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name panel.example.com;

    root /var/www/pterodactyl/public;
    index index.php;

    access_log /var/log/nginx/pterodactyl.app-access.log;
    error_log /var/log/nginx/pterodactyl.app-error.log error;

    client_max_body_size 100m;
    client_body_timeout 120s;
    sendfile off;

    ssl_certificate /etc/letsencrypt/live/panel.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/panel.example.com/privkey.pem;

    ssl_session_cache shared:SSL:10m;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384";
    ssl_prefer_server_ciphers on;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param PHP_VALUE "upload_max_filesize = 100M \n post_max_size=100M";
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param HTTP_PROXY "";
        fastcgi_intercept_errors off;
        fastcgi_buffer_size 16k;
        fastcgi_buffers 4 16k;
        fastcgi_connect_timeout 300;
        fastcgi_send_timeout 300;
        fastcgi_read_timeout 300;
    }

    location ~ /\.ht {
        deny all;
    }
}

Si utilizas una versión de PHP distinta de 8.3, adapta la ruta php8.3-fpm.sock.

Activa la configuración creando el enlace simbólico, elimina la configuración por defecto de NGINX si existe, valida y reinicia NGINX:

ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/pterodactyl.conf
rm -f /etc/nginx/sites-enabled/default
nginx -t
systemctl restart nginx

Después de este paso, abre tu dominio en el navegador e inicia sesión con la cuenta de administrador creada antes.

Paso 7: activar cron y la cola

Pterodactyl usa un planificador y una cola para las tareas en segundo plano.

Añade la tarea cron:

(crontab -l 2>/dev/null; echo "* * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1") | crontab -

Después crea el servicio systemd de la cola en /etc/systemd/system/pteroq.service con este contenido:

cat <<'EOF' > /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
EOF

Luego activa Redis y el worker:

systemctl enable --now redis-server
systemctl daemon-reload
systemctl enable --now pteroq.service
systemctl status pteroq.service --no-pager

Paso 8: instalar Docker para Wings

Wings se basa en Docker. Empieza instalándolo y activa el servicio al arrancar.

En una máquina nueva, utiliza esta secuencia para desinstalar los paquetes obsoletos e instalar la última versión estable de Docker Engine:

sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc | cut -f1)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
systemctl enable --now docker
docker version

Si Docker ya se usa en producción en el VPS, no elimines los paquetes existentes sin una ventana de mantenimiento. En ese caso, comprueba primero la versión instalada y el impacto sobre tus contenedores existentes.

En kernels Linux anteriores a 6.1, activar la gestión de swap también puede ser útil para evitar algunos problemas de memoria en los contenedores.

Paso 9: instalar Wings en el nodo Linux

Crea el directorio de configuración y descarga el binario Wings.

mkdir -p /etc/pterodactyl
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")"
chmod u+x /usr/local/bin/wings
wings version

Paso 10: crear el Node dans le Panel

Cuando el panel esté operativo, ve a Admin > Nodes > Create New. Indica el nombre del nodo, su ubicación, su FQDN, los límites de memoria y disco, y los puertos de Wings.

Algunas reglas sencillas:

utiliza un FQDN real para el nodo, por ejemplo node.example.com.
elige Use SSL Connection si Wings tiene un certificado válido para ese FQDN.
elige Use HTTP Connection solo para una prueba temporal o un entorno aislado.
mantén 8080 para la API Wings y 2022 para SFTP, salvo necesidad concreta.
no pongas 127.0.0.1 en las asignaciones de servidores de juegos.

Después de crear el nodo, abre la pestaña Configuration. El panel genera el contenido completo del archivo config.yml que debes copiar en /etc/pterodactyl/config.yml.

Después crea el archivo en el servidor:

nano /etc/pterodactyl/config.yml

Pega el contenido proporcionado por el panel, guarda y prueba Wings en modo debug:

wings --debug

Si el arranque es correcto, verás que Wings contacta la API del Panel, procesa la lista de servidores y escucha en el puerto API y el puerto SFTP. Después puedes detener el modo debug con Ctrl+C y pasar al servicio systemd.

Paso 11: ejecutar Wings como servicio systemd

Crea el servicio /etc/systemd/system/wings.service:

cat <<'EOF' > /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
EOF

Activa después el servicio:

systemctl daemon-reload
systemctl enable --now wings
systemctl status wings --no-pager

También puedes comprobar los puertos en escucha:

ss -ltnp | grep -E ':(8080|2022) '

Paso 12: añadir asignaciones de IP y puertos

Cada servicio creado en el nodo necesita al menos una asignación, es decir, una combinación IP + puerto. In la administración del nodo, añade los rangos de puertos necesarios con la dirección IP correcta de tu interfaz de red o la IP pública del VPS.

Para recuperar la IP principal del servidor:

hostname -I | awk '{print $1}'

Para comprobar la IP pública vista desde Internet:

curl -fsS https://api.ipify.org

No utilices 127.0.0.1 para las asignaciones. Este es un ejemplo de asignaciones creadas en la interfaz, con una IP de documentación ocultada:

Paso 13: configurar el firewall

Para que el Panel, Wings y tus servidores de juegos puedan comunicarse y ser accesibles desde el exterior, es indispensable configurar el firewall de tu VPS.

Pterodactyl utiliza generalmente los puertos siguientes:

80 y 443 en TCP para el acceso web al Panel.
8080 en TCP para la API Wings usada por el Panel.
2022 en TCP para el servidor SFTP integrado en Wings.
los puertos de tus servidores de juegos, por ejemplo 25565 en TCP/UDP para Minecraft.

Opción A: configuración con UFW

Antes de activar UFW, comprueba siempre su estado actual para evitar cortar tu acceso SSH:

ufw status

Autoriza primero SSH y abre después los puertos necesarios:

ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 8080/tcp
ufw allow 2022/tcp
ufw allow 25565:25600/tcp
ufw allow 25565:25600/udp
ufw enable

Ten en cuenta que la regla para el puerto 22/tcp (SSH) sirve únicamente para mantener tu acceso de administración remota al VPS, y no es necesaria para el funcionamiento de Pterodactyl en sí.

Si tu proveedor también aplica un firewall de red externo, abre los mismos puertos en su panel de cliente.

Opción B: configuración equivalente con iptables

Si tu distribución no utiliza UFW, puedes aplicar estas reglas directamente con iptables:

iptables -A INPUT -p tcp --dport 22 -j ACCEPT
iptables -A INPUT -p tcp --dport 80 -j ACCEPT
iptables -A INPUT -p tcp --dport 443 -j ACCEPT
iptables -A INPUT -p tcp --dport 8080 -j ACCEPT
iptables -A INPUT -p tcp --dport 2022 -j ACCEPT
iptables -A INPUT -p tcp --dport 25565:25600 -j ACCEPT
iptables -A INPUT -p udp --dport 25565:25600 -j ACCEPT

Del mismo modo, la regla para el puerto 22/tcp sirve únicamente para conservar tu acceso SSH de administración (el puerto por defecto es el 22, pero recuerda adaptarlo si lo has modificado).

Recuerda persistir tus reglas iptables según tu distribución, o pueden desaparecer al reiniciar.

Comprobaciones finales

Antes de crear tu primer servidor de juego, comprueba el estado de los servicios:

systemctl status nginx php8.3-fpm mariadb redis-server pteroq wings --no-pager

Comprueba también que los puertos esperados están en escucha:

ss -ltnp | grep -E ':(80|443|8080|2022) '

Por último, en el panel, vuelve a tu nodo. Si Wings se comunica correctamente con el Panel, podrás crear un servidor y asignarle una asignación disponible.

Ejemplo: crear un servidor Minecraft en Pterodactyl

Cuando el Panel, Wings y las asignaciones estén listos, la prueba más clara consiste en crear un primer servidor Minecraft. En la administración de Pterodactyl, ve a Admin > Servers > Create New.

Empieza con la información general: nombre del servidor, propietario, nodo de destino y asignación principal. Para una prueba simple, usa una sola asignación, por ejemplo el puerto 25565, y deja Start Server when Installed activado si quieres iniciar el servidor automáticamente después de la instalación.

Después indica los límites de aplicación y los recursos del contenedor. Para un pequeño servidor Paper de prueba, una base razonable puede ser:

Database Limit en 0 si no vas a usar una base de datos externa.
Allocation Limit en 1 si el servidor solo necesita un puerto.
Backup Limit en 2 para permitir algunas copias de seguridad.
CPU Limit en 100 para limitar el servidor a un núcleo lógico.
Memory en 2048 MiB para una prueba cómoda.
Swap en 0 para desactivar el swap del contenedor.
Disk Space en 8192 MiB para dar 8 GB al servidor.

En Nest Configuration, elige el nest Minecraft y luego el egg que quieras usar. En este ejemplo usamos Paper, porque es una elección habitual para un servidor Minecraft optimizado con plugins.

Para la imagen Docker, presta mucha atención a la versión de Java. Con latest, las versiones recientes de Minecraft pueden exigir Java 25. Por ejemplo, Paper para Minecraft 26.1 requiere Java 25, por lo que la imagen ghcr.io/pterodactyl/yolks:java_21 puede hacer fallar el arranque. Para un servidor latest, elige Java 25 o fija una versión de Minecraft compatible con la imagen Java elegida.

En Startup Configuration, deja el comando de arranque generado por el egg y comprueba las variables:

Minecraft Version: latest para la última versión, o una versión precisa si quieres evitar sorpresas.
Server Jar File: server.jar.
Build Number: latest para el último build de Paper.

Haz clic después en Create Server. El servidor aparece primero en instalación y pasa a estado Active cuando Wings termina la descarga y la preparación de los archivos.

Por último, abre la vista de usuario del servidor. La consola permite iniciar, reiniciar o detener el servidor, seguir los logs de Minecraft y controlar el uso de CPU/RAM/red. Después de pasar a Java 25, el servidor Paper debería arrancar correctamente si la asignación y los puertos son coherentes.

Si el servidor se queda bloqueado o vuelve a estar offline inmediatamente, abre los logs de la consola. Las causas clásicas son una imagen Java incompatible con la versión de Minecraft elegida, un puerto ya usado, una asignación incorrecta o una EULA de Minecraft que debe aceptarse según el egg y la versión utilizada.

Ajustes avanzados de Wings que conviene conocer

Cuando tu nodo funcione, puedes ajustar algunos parámetros avanzados en /etc/pterodactyl/config.yml:

registros Docker privados para autenticarse en un registro privado.
network name y network_mode para personalizar la red de los contenedores.
container_pid_limit para limitar el número de procesos dentro de un contenedor.
throttles para controlar la cantidad de logs o la intensidad de ciertas operaciones.
installer_limits para limitar los recursos usados durante las instalaciones.

Estos ajustes son potentes, pero una mala configuración puede romper el funcionamiento del nodo. Modifícalos solo si entiendes exactamente su efecto.

Errores frecuentes que debes evitar

Estos son los problemas más habituales durante este tipo de instalación:

composer parece bloqueado como root: vuelve a lanzar el comando con COMPOSER_ALLOW_SUPERUSER=1.
No application encryption key has been specified: comprueba que .env existe y vuelve a ejecutar php artisan key:generate --force.
el Panel genera enlaces incorrectos: comprueba que APP_URL contiene https:// o http://.
Wings no contacta con el Panel: comprueba remote en config.yml, el puerto 8080, el firewall y la elección HTTP/HTTPS del nodo.
el servidor Minecraft falla justo al arrancar: comprueba que la imagen Docker Java corresponde a la versión Minecraft solicitada, por ejemplo Java 25 para versiones recientes con latest.
los servidores no son accesibles: comprueba las asignaciones, los puertos abiertos y la IP pública utilizada.

Actualizar Wings más adelante

Actualizar Wings es rápido. Se recomienda mantener una versión coherente con la del Panel. Para una instalación en Pterodactyl 1.12.x, la rama esperada es Wings 1.12.x.

Comando de actualización:

systemctl stop wings
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")"
chmod u+x /usr/local/bin/wings
systemctl restart wings
systemctl status wings --no-pager

Buenas prácticas para una instalación limpia

Para terminar, estas son las recomendaciones que aplicamos en BoxToPlay para conseguir un despliegue estable en alojamiento VPS:

separar claramente el Panel y el nodo si aumenta tu carga.
usar certificados SSL válidos para el Panel y Wings.
guardar copias de seguridad de la base de datos y del archivo .env.
conservar una copia externa de APP_KEY.
configurar correctamente el firewall siguiendo el paso 13.
evitar cambios avanzados de red Docker sin una necesidad real.
probar Wings en modo debug antes de activar el servicio definitivo.

Si buscas un entorno fiable para desplegar este tipo de stack en un servidor VPS, en BoxToPlay damos prioridad a un rendimiento sólido y a una puesta en marcha clara. Puedes lanzar tu servidor gratis.