Migrating from Pterodactyl to FeatherPanel

This guide outlines the process of migrating your existing Pterodactyl installation to FeatherPanel. Our migration tool allows you to transfer your data—including users, servers, and configurations—seamlessly while keeping your original installation safe.

Migration Overview

The migration involves four key steps:

1. Installing FeatherPanel: Set up the panel on a new or existing domain.
2. Accessing the Importer: Navigate to the built-in migration tool in FeatherPanel.
3. Running the Migration: Execute the automated data transfer.
4. Upgrading Nodes: Replace the Pterodactyl Wings service with FeatherWings.

Step 1: Install FeatherPanel

You have two options for where to install FeatherPanel. Both are fully supported.

Option A: New Domain (Recommended)

Installing on a separate domain (e.g., panel.yourdomain.com) is the safest approach. It allows you to:

• Test FeatherPanel without affecting your live Pterodactyl panel.
• Run both panels simultaneously during the transition.
• Verify everything works before switching users over.

Option B: Same Domain

You can install FeatherPanel on the same domain as Pterodactyl. The migration tool handles the data transfer, but you will need to manage the web server configuration to switch which panel is live.

Action: Follow the Installation Guide to install FeatherPanel. Ensure the panel is accessible and you can log in before continuing.

Step 2: Access the Pterodactyl Importer

Once FeatherPanel is up and running:

1. Log in to your FeatherPanel Admin Area.
2. Navigate to the importer URL: /admin/pterodactyl-importer.
3. Review the on-screen instructions specific to your environment.

The importer interface will dynamically guide you based on your detected configuration.

Step 3: Run the Migration

Follow the steps provided on the specific importer page. The tool will:

• Connect to your Pterodactyl database.
• Import Users, Servers, Nodes, Nests, and Eggs.
• Convert necessary configurations to the FeatherPanel format.

Wait for the confirmation message indicating FeatherPanel is ready before proceeding.

Step 4: Replace Wings with FeatherWings

After the panel data is migrated, you must update your nodes to use FeatherWings, our enhanced daemon.

Perform the following steps on EACH node:

1. Stop Legacy Wings

Stop the Pterodactyl Wings service to prevent conflicts.

sudo systemctl stop wings
sudo systemctl disable wings

2. Install FeatherWings

Install the new daemon using our automated script:

curl -sSL https://get.featherpanel.com/beta.sh | bash

(Alternatively, see the FeatherWings Guide for manual installation.)

3. Update Configuration

You need to apply the new configuration from FeatherPanel to the node.

1. Go to Admin Area > Locations > Nodes.
2. Click Edit on the relevant node.
3. Scroll to the Wings Config section and copy the configuration block.
4. On your node server, open the config file:

sudo nano /etc/featherpanel/config.yml

5. Paste the copied configuration, ensuring you replace any old content.
6. Save and exit (Ctrl+X, Y, Enter).

4. Verify Connection

Start the service and check its status:

sudo systemctl restart featherwings
sudo systemctl status featherwings

You should see an "Active (running)" status. Repeat this for all nodes involved in the migration.

Post-Migration Checklist

Before opening the panel to your users, verify the following:

• Login: Can you log in with your migrated credentials?
• Servers: Are all servers listed in the panel?
• Nodes: Do all nodes show a green "Online" heartbeat?
• Power Actions: Can you Start, Stop, and Restart a test server?
• Files: Is the File Manager accessible for a server?

Troubleshooting

specific Issues?

• Database Errors: Ensure the database credentials in your .env file are correct and allow connections.
• Node Disconnected: double-check the config.yml on the node matches the "Wings Config" in the panel exactly. Ensure ports (usually 8080/8443) are open in your firewall.

If you need assistance, join our Discord Community for support.