Update Pterodactyl Panel and Wings

This guide updates a Pterodactyl Panel within the 1.x series (for example from 1.12.x to 1.15.x) and updates Wings on your nodes. It follows the official Pterodactyl documentation. It assumes the panel is installed in /var/www/pterodactyl; use your own folder if it is somewhere else.

At the time of writing the latest 1.x releases are Panel 1.15.1 and Wings 1.13.4. Check the releases pages for newer ones: Panel releases and Wings releases.

Before you update the panel#

Make a backup of the database, the .env file and the panel folder. See back up your server before an update.
Check which version you run now:
```
cd /var/www/pterodactyl
php artisan p:info
```
The first table shows Panel Version, Latest Version and Up-to-Date. The output also shows your database and mail settings (no passwords), so do not paste it publicly in full.
Check PHP and Composer. Panel 1.12 and newer need PHP 8.2 or 8.3 (8.3 is recommended) and Composer 2:
```
php -v
composer --version
```
Panel 1.x lists only PHP 8.2 and 8.3, not 8.4. If you are below 8.2, upgrade PHP first: see update PHP on Ubuntu or Debian.
Read the release notes of every version between yours and the new one.

Panel	Wings	PHP
1.11.x	1.11.x	8.1, 8.2, 8.3
1.12.x	1.12.x	8.2, 8.3
1.13.x to 1.15.x	1.13.x	8.2, 8.3

The first two rows come from the official version table. The last row comes from the releases themselves: the official table had not been updated past 1.12 when this was written. In most cases the base version of Wings should match that of the panel.

Update the panel step by step#

Run these commands on the panel server, in the panel folder.

Put the panel in maintenance mode, so users see a maintenance page instead of errors:
```
cd /var/www/pterodactyl
sudo php artisan down
```
Download the new release and unpack it over your current files. Use the exact version number, not latest:
```
curl -L https://github.com/pterodactyl/panel/releases/download/v1.15.1/panel.tar.gz | sudo tar -xzv
```
Set the permissions on the cache and storage folders:
```
sudo chmod -R 755 storage/* bootstrap/cache
```

Install the PHP dependencies:

sudo COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader

Clear the compiled templates and the configuration cache:
```
sudo php artisan view:clear
sudo php artisan config:clear
```
Update the database. This also updates the eggs that come with Pterodactyl:
```
sudo php artisan migrate --seed --force
```
Waarschuwing

Never edit the eggs that ship with Pterodactyl. This step overwrites them. Make a copy under your own name if you need changes.

Give the files back to the user your web server runs as. On Debian and Ubuntu that is usually www-data:

# NGINX, Apache or Caddy on Debian or Ubuntu
sudo chown -R www-data:www-data /var/www/pterodactyl/*

# NGINX on RHEL, Rocky Linux or AlmaLinux
sudo chown -R nginx:nginx /var/www/pterodactyl/*

# Apache on RHEL, Rocky Linux or AlmaLinux
sudo chown -R apache:apache /var/www/pterodactyl/*

Restart the queue worker, so it loads the new code:
```
sudo php artisan queue:restart
```
Take the panel out of maintenance mode:
```
sudo php artisan up
```

Update Wings on a node#

Do this on every node. Stopping Wings for a moment does not stop the game servers that run on it.

Check the version you run now:
```
wings version
```
Stop Wings:
```
sudo systemctl stop wings
```
Download the new binary. This picks the right file for your processor (amd64 or arm64). Replace v1.13.4 with the version you want:
```
sudo curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/download/v1.13.4/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
sudo chmod u+x /usr/local/bin/wings
```
The official guide downloads from releases/latest. That works too, but naming the version makes sure you get the one you checked.
Start Wings again:
```
sudo systemctl restart wings
```
Open connections to the console reconnect by themselves.

Check that the update worked#

Run php artisan p:info again: Up-to-Date should say Yes.
Run wings version on each node.
In the panel, open the admin area, then Nodes. Every node should show a green heart.
Open a server's console and check that it connects.
Check that the queue worker and Wings are running:
```
sudo systemctl status pteroq
sudo systemctl status wings
```
pteroq is the name the official installation guide gives the queue worker. Yours may have another name.

Look for new errors in the panel log:

tail -n 100 /var/www/pterodactyl/storage/logs/laravel-$(date +%F).log

Common errors after a panel update#

Permission denied in the log, or a blank page#

The log shows failed to open stream: Permission denied for a file in storage. Some files are owned by the wrong user, often because a command ran as root after the chown step. Run step 7 of the update again, then step 3.

Emails, schedules or backups no longer run#

The queue worker is still running the old code, or it stopped. Run sudo php artisan queue:restart, then check sudo systemctl status pteroq. If it is not running, start it with sudo systemctl restart pteroq and read its errors with sudo journalctl -u pteroq -n 50.

Old pages or settings after the update#

Clear the caches again: sudo php artisan view:clear and sudo php artisan config:clear. Then reload the page in your browser without its cache (Ctrl + Shift + R).

The database update fails#

php artisan migrate --seed --force stops with an error. Do not take the panel out of maintenance mode. Read the error: a database that cannot be reached or a user without rights is a different problem from a failing migration. If you cannot fix it, put back the backup you made: see back up your server before an update.

A PHP version error, or the panel still uses the old PHP#

The page or Composer says your PHP version does not meet the requirements. Check php -v: Panel 1.x lists only PHP 8.2 and 8.3. The command line and the web server can use different PHP versions. If you have just moved to a new PHP branch, point your web server at the new PHP-FPM socket (for NGINX, the fastcgi_pass line in your panel configuration, for example php8.3-fpm.sock) and reload it with sudo systemctl reload nginx.

An "invalid MAC" error#

The panel cannot decrypt its data because the APP_KEY in .env is not the key the data was encrypted with. This happens when a backup of the database is restored without its .env. Put back the original .env. Without the original key, the encrypted data cannot be recovered.

The panel stays in maintenance mode#

Run sudo php artisan up.