Testing the Upgrade

Introduction

Before you upgrade your live Panel, you should try the upgrade on a copy. A test run shows you how long the upgrade takes, and whether your eggs, integrations, and extensions still work. Your users are not affected.

This page explains how to make a safe copy, what to check, and how to practice rolling back.

Making a Safe Copy

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

1. Back up your database and your .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, write down what it contains, so you can compare it afterwards. At a minimum, count your 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. The numbers should match.

Checking the Result

Once the data matches, start the queue worker and bring the copy online. Then 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, its files, and SFTP.
• Run a schedule, and create a backup.
• Test your billing module against the copy. For example, create, suspend, and delete 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. You should know how to roll back before you upgrade your live Panel.

When you do upgrade your live Panel, plan a maintenance window. 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.