Testing the Upgrade

Introduction

Try the upgrade on a copy before you upgrade your live Panel. A test run shows how long the upgrade takes and whether your eggs, integrations, and extensions still work, without affecting your users.

Making a Safe Copy

Your copy uses real data, so it can reach real systems. Keep it isolated.

1. Back up your database and .env file as described in Back Up Your Panel.
2. Restore them on a separate machine with the same 1.x version installed. Do not change your live Panel or its backup.
3. Block the copy from reaching your live Wings nodes, database hosts, mail server, backup storage, and webhooks. Your database contains their addresses and credentials.
4. Use a separate Redis server for the copy.
5. Keep the queue worker and the cron entry stopped until you have checked the database.

Recording Your Data

Before you upgrade the copy, record what it contains so you can compare afterwards. At a minimum, count users, servers, eggs, nodes, allocations, schedules, backups, and API keys.

Running the Upgrade

Follow Upgrading From 1.x on the copy. Time the database migration and note any errors.

Then compare your data with the counts you recorded. They should match.

Checking the Result

Once the data matches, start the queue worker, bring the copy online, and check each of these:

• Sign in with an existing account, including one that uses two-factor authentication.
• Use an existing API key with the Application API and the Client API.
• Connect a test Wings node, and start, stop, and restart a test server. Open its console, files, and SFTP.
• Run a schedule and create a backup.
• Test your billing module against the copy, for example by creating, suspending, and deleting a test service.
• Enable your extensions one at a time.

Practicing a Rollback

Finally, follow Rolling Back on the copy and check that 1.x works again. Know how to roll back before you upgrade your live Panel.

For the live upgrade, plan a maintenance window, and agree in advance on the point at which you will roll back instead of fixing forward.

For Panel Developers

The Panel repository includes an automated test of the database upgrade. It imports the 1.15.1 database schema into a temporary MariaDB container, adds test data, and runs the 2.0 migrations against it.

To run it, install the Composer development dependencies in a 2.x Panel checkout, build a Panel image, and run:

bash .github/docker/migration-pilot.sh pterodactyl-panel:local

The test uses an isolated Docker network and removes everything when it finishes. It checks that:

• An incomplete 1.x database is refused before anything changes.
• Existing records and encrypted values are unchanged after the migration.
• Nests are converted into tags.
• Running the migrations a second time changes nothing.