To install Pterodactyl on an Ubuntu 24.04 VPS, you need a KVM server with root access, a domain, Docker, PHP 8.3, MariaDB, Redis, nginx, and TLS certificates. This guide walks through a manual Panel and Wings deployment, verifies each component, and includes a practical rollback path.
Compatibility used here: Ubuntu 24.04 LTS, Pterodactyl Panel 1.12, Wings 1.12, PHP 8.3, MariaDB, and nginx. Official documentation also supports Ubuntu 22.04 and Debian 11, 12, and 13. Wings does not run on Windows and commonly fails on OpenVZ, Virtuozzo, or LXC; KVM is the reliable choice.
How Pterodactyl is structured
Pterodactyl manages game servers inside isolated Docker containers. It has two main components:
- Panel: web interface for users, databases, locations, nodes, servers, and permissions.
- Wings: daemon installed on each node to control Docker, storage, console access, SFTP, and resource limits.
Panel and Wings can share one VPS for a small deployment. For production or multiple nodes, separating them provides better isolation and easier scaling.
Prerequisites
- 64-bit Ubuntu 24.04 KVM VPS.
- Root or sudo access.
- A domain or subdomain pointing to the VPS IPv4 address.
- At least 2 GB RAM for a small setup; 4 GB or more when Panel and Wings share the server.
- Ports 80 and 443 for Panel, 8080 for Wings, and 2022 for SFTP unless customized.
- A provider snapshot or backup before starting.
Check virtualization
systemd-detect-virt
uname -r
Continue when the first command returns kvm. If it returns openvz, lxc, or virtuozzo, ask the provider whether Docker and the required networking features are enabled.
1. Update Ubuntu
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
2. Install Panel dependencies
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
php -v
mariadb --version
nginx -v
redis-cli ping
Redis should return PONG.
3. Install Composer
curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer
composer --version
4. Create the database
sudo mariadb
CREATE DATABASE panel;
CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'A_LONG_UNIQUE_PASSWORD';
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1';
FLUSH PRIVILEGES;
EXIT;
5. Download 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
Back up APP_KEY
grep APP_KEY /var/www/pterodactyl/.env
Store the complete line outside the server. Losing APP_KEY makes encrypted data unrecoverable even when database backups exist.
6. Configure the environment
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
7. Configure nginx
sudo nano /etc/nginx/sites-available/pterodactyl.conf
nginx
server {
listen 80;
listen [::]:80;
server_name panel.example.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; }
}
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. Enable HTTPS
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d panel.example.com
sudo certbot renew --dry-run
9. Configure cron and queues
sudo crontab -e
* * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1
Run Pterodactyl on a KVM VPS
Choose a KVM VPS to run Docker, Panel, and Wings without the common limitations of OpenVZ or LXC.
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
10. Install Docker from the official repository
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
Firewall warning: Docker-published ports can bypass UFW rules. Filter traffic with compatible iptables rules and the DOCKER-USER chain, or use the provider firewall.
11. Install 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. Create the node and load config.yml
- Open the admin area.
- Create a node under Nodes.
- Set the Wings FQDN, for example
node1.example.com. - Open Configuration.
- Copy the YAML to
/etc/pterodactyl/config.ymlor run the generated token command.
When Panel uses HTTPS, Wings also needs a valid certificate for its own FQDN.
13. Test and daemonize Wings
sudo wings --debug
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. Configure allocations and firewall
hostname -I | awk '{print $1}'
sudo ss -lntup
Open only required ports: 80/443 for Panel, 8080 for Wings, 2022 for SFTP, and the exact allocation range assigned to game servers.
Validation checklist
sudo nginx -t
sudo systemctl is-active nginx php8.3-fpm mariadb redis-server pteroq docker wings
curl -I https://panel.example.com
sudo journalctl -u pteroq -n 50 --no-pager
sudo journalctl -u wings -n 100 --no-pager
sudo docker info
The deployment is ready when you can sign in, the node has a green heart, Wings reports no errors, and a test server installs, starts, and accepts connections.
Common problems
Node is red
dig +short node1.example.com
curl -vk https://node1.example.com:8080
sudo timedatectl status
Wings cannot reach Docker
sudo systemctl status docker --no-pager
sudo docker info
sudo journalctl -u docker -n 100 --no-pager
502 Bad Gateway
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
Queues or email do not run
sudo systemctl status pteroq --no-pager
sudo journalctl -u pteroq -n 100 --no-pager
sudo crontab -l
redis-cli ping
Rollback
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
sudo systemctl disable --now wings pteroq
For a fresh VPS, restoring the pre-installation snapshot is usually safer than removing every package manually.
Ongoing maintenance
- Read Panel and Wings release notes before updates.
- Back up the database,
.env,APP_KEY,config.yml, and game data. - Apply Ubuntu security updates regularly.
- Monitor disk, RAM, CPU, I/O, and Docker image usage.
- Never expose Redis or database ports to the public Internet.
- Enable two-factor authentication for administrators.
FAQ
Can Panel and Wings share one VPS?
Yes for testing and small installations. Separating them is preferable in production.
Does Pterodactyl work on OpenVZ or LXC?
Not reliably. Official documentation warns about Docker limitations. Use KVM or dedicated hardware.
Do I need a domain?
It is strongly recommended and effectively required for clean HTTPS configuration.
How much RAM does Pterodactyl need?
The game servers determine most resource usage. Size the node for players, mods, plugins, and workload, then reserve headroom for Docker and the operating system.
Conclusion
A proper Pterodactyl deployment does not end at the login screen. Validate queues, cron, Docker, Wings, TLS, allocations, backups, and recovery so the platform remains manageable after launch.
