Migrating from Pterodactyl (Standalone)

This guide is for Pterodactyl installs that run directly on the host - no Docker, no containers, just a typical install at /var/www/pterodactyl or similar. If you're using Docker, head to the Dockerized guide instead.

The plan: install Calagopus alongside your existing Pterodactyl, point the importer at Pterodactyl's .env file, let it read everything from Pterodactyl's database, and write equivalent records into Calagopus's fresh database. Your users log in with the same credentials afterwards.

A reminder of what doesn't migrate: API keys. See the intro for the full reasoning - the short version is that the hashes aren't compatible and the API isn't either, so old keys wouldn't work even if we did import them.

Prerequisites

Before you start, you'll want:

• Your Pterodactyl .env file accessible (you'll point the importer at it)
• Calagopus Panel installed but not yet configured - we need to land on the Out-of-Box Experience (OOBE) screen and stop there

Install Calagopus First

If you haven't installed Calagopus yet, follow the installation guide to get it running. Once you reach the OOBE screen, stop. Don't click through it. Don't create the admin user. Just leave it on that screen and come back here.

Don't click through the OOBE

The importer needs an empty Calagopus database to write into. The OOBE creates initial records (admin user, default settings) that would conflict with what the importer wants to do.

I already clicked through - how do I undo it?

You'll need to drop and recreate the database. Pick the matching tab for how Calagopus is installed:

Head to the directory with your Calagopus compose file and stop the stack:

docker compose down

Delete the Postgres data directory:

# This wipes the Calagopus database. Don't run this if you have data you care about.
rm -r postgres

Start Calagopus back up:

docker compose up -d

Choose Your Calagopus Install Method

The exact import command depends on how Calagopus itself is installed. Pick the matching tab and follow along:

Copy Pterodactyl's .env file into the Calagopus container. Assuming Pterodactyl is at /var/www/pterodactyl:

docker compose cp /var/www/pterodactyl/.env web:/.env

Then run the importer:

docker compose exec web calagopus-panel import pterodactyl --environment /.env

This walks through users, servers, nodes, allocations, eggs, and so on. Larger Pterodactyl installs take longer; small ones finish in seconds. Progress is logged to stdout.

If the import errors out

Treat the database as poisoned. Partial imports leave Calagopus in an inconsistent state. Drop the Postgres data (the steps in the OOBE warning callout above), let Calagopus recreate it empty, and re-run the import.

When the import finishes, restart the stack:

docker compose down
docker compose up -d

Log in with your existing Pterodactyl credentials.

What's Next

Don't forget the node side. Calagopus uses Wings as its node agent, but it needs to be pointed at the new panel rather than the old one. See Wings - Updating for the swap.

After that, regenerate any API keys your external scripts were using. The old Pterodactyl keys won't work and the API itself is different anyway, so you're rewriting those scripts regardless.