Migrating from Pterodactyl
Complete step-by-step manual guide for migrating an existing Pterodactyl Panel installation to Aquadactyl Panel.
This guide walks you through migrating an existing Pterodactyl Panel (v1.x) installation to Aquadactyl Panel.
Because Aquadactyl maintains database compatibility with Pterodactyl while adding bundled Blueprint framework tooling, updated PHP 8.5/8.4 support, and modern frontend compilation, you can migrate your existing servers, users, and node configurations with zero loss of game server data.
Daemon Compatibility: Running game servers and your existing Wings daemons are completely compatible with Aquadactyl. Wings daemon tokens and configurations do not need to be changed during panel migration.
Migration Overview
Key differences between standard Pterodactyl and Aquadactyl:
| Component | Pterodactyl | Aquadactyl |
|---|---|---|
| Default Location | /var/www/pterodactyl | /var/www/aquadactyl |
| Supported PHP | PHP 8.1 / 8.2 / 8.3 | PHP 8.5 (recommended) or PHP 8.4 |
| Node.js & Frontend | Yarn / Prebuilt release | Node.js 24 & pinned pnpm 12.10.1 (pnpm run build) |
| Framework Extensions | None / Manual patching | Bundled Blueprint beta-2026-08 integration |
| Permissions Model | www-data:www-data entire tree | Strict least-privilege: root:www-data code, only storage/ and bootstrap/cache/ writable |
Step 1: Maintenance Mode & Stop Queue Worker
Before touching files or running migrations, place your current Pterodactyl panel into maintenance mode and halt the background queue worker:
cd /var/www/pterodactyl
# Put Pterodactyl into maintenance mode
sudo -u www-data php artisan down --retry=60
# Stop the background queue worker
sudo systemctl stop pteroq.serviceStep 2: Create Full Backups
Always take a complete snapshot of your database and existing Pterodactyl directory before making changes:
# Create backup directory outside the web root
sudo mkdir -p /var/backups/pterodactyl-migration
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
# Backup the database (adjust database credentials if needed)
sudo mysqldump -u root -p --single-transaction --quick --routines pterodactyl > /var/backups/pterodactyl-migration/database-${TIMESTAMP}.sql
# Backup existing Pterodactyl files
sudo tar -czf /var/backups/pterodactyl-migration/pterodactyl-files-${TIMESTAMP}.tar.gz -C /var/www/pterodactyl .Step 3: Upgrade System Prerequisites (PHP 8.5 & Node.js 24)
Pterodactyl often runs on older PHP versions (such as PHP 8.1, 8.2, or 8.3). Aquadactyl requires PHP 8.5 (or 8.4) and Node.js 24 with pnpm 12.10.1.
Add Sury PHP Repository & Install PHP 8.5
sudo apt-get update
sudo apt-get install -y lsb-release ca-certificates curl apt-transport-https gnupg
# Add Ondřej Surý PHP repository
curl -sSLo /tmp/debsuryorg-archive-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb
sudo dpkg -i /tmp/debsuryorg-archive-keyring.deb
rm -f /tmp/debsuryorg-archive-keyring.deb
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/debsuryorg-archive-keyring.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt-get update
# Install PHP 8.5 and required modules
sudo apt-get install -y php8.5 php8.5-cli php8.5-fpm php8.5-gd php8.5-mysql php8.5-mbstring \
php8.5-bcmath php8.5-xml php8.5-curl php8.5-zip php8.5-posix php8.5-intl php8.5-redis \
rsync git tar zip unzipInstall Node.js 24 & Pinned pnpm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm install 24
nvm use 24
npm install --global npm@latest
npm install --global [email protected]Step 4: Download Aquadactyl Panel
Set up the new Aquadactyl directory at /var/www/aquadactyl:
# Create Aquadactyl directory
sudo mkdir -p /var/www/aquadactyl
cd /var/www/aquadactyl
# Download the latest panel release archive (or specify target tag)
RELEASE_TAG="v0.2.0"
curl -L -o /tmp/panel.tar.gz "https://github.com/Aquadactyl/aquadactyl/releases/download/${RELEASE_TAG}/panel.tar.gz"
# Extract into /var/www/aquadactyl
sudo tar -xzf /tmp/panel.tar.gz -C /var/www/aquadactyl
rm -f /tmp/panel.tar.gzStep 5: Migrate Configuration (.env) & Storage
Copy your existing environment configuration and persistent files (such as custom eggs and server assets) from Pterodactyl into Aquadactyl:
# Copy existing configuration file
sudo cp /var/www/pterodactyl/.env /var/www/aquadactyl/.env
sudo chmod 640 /var/www/aquadactyl/.env
# Migrate uploaded storage (excluding old logs and framework cache)
sudo rsync -av \
--exclude='logs/' \
--exclude='framework/cache/' \
--exclude='framework/sessions/' \
--exclude='framework/views/' \
/var/www/pterodactyl/storage/ /var/www/aquadactyl/storage/
# Ensure HASHIDS_SALT is set in .env
if ! grep -q "^HASHIDS_SALT=" /var/www/aquadactyl/.env || grep -q "^HASHIDS_SALT=$" /var/www/aquadactyl/.env; then
echo "HASHIDS_SALT=$(openssl rand -hex 16)" | sudo tee -a /var/www/aquadactyl/.env
fiNever replace or overwrite your APP_KEY from the original .env. The
APP_KEY encrypts sensitive credentials and API tokens stored in your
database.
Step 6: Install Dependencies
Install PHP Composer dependencies and frontend Node packages:
cd /var/www/aquadactyl
# Clear old cached manifests
sudo rm -f bootstrap/cache/{config,packages,services,events,routes-v7}.php
# Install Composer PHP packages
sudo COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --prefer-dist --no-interaction --no-scripts --optimize-autoloader
# Install frontend dependencies with pinned pnpm
sudo pnpm install --frozen-lockfile
# Discover Laravel packages
sudo php artisan package:discover --ansiStep 7: Run Database Migrations & Seeders
Apply database migrations to update your Pterodactyl database schema and seed the bundled Blueprint framework tables:
cd /var/www/aquadactyl
# Apply schema migrations
sudo php artisan migrate --force
# Seed Blueprint database tables
sudo php artisan db:seed --class=BlueprintSeeder --forceStep 8: Initialize Blueprint & Build Frontend
Initialize the bundled Blueprint integration and compile frontend production assets:
cd /var/www/aquadactyl
# Make blueprint executable
sudo chmod 0750 blueprint.sh
# Initialize Blueprint integration
sudo BLUEPRINT_ENVIRONMENT=ci bash blueprint.sh
sudo php artisan bp:cache
# Compile frontend production assets
sudo pnpm run buildStep 9: Configure File Permissions
Set the strict least-privilege permissions model:
cd /var/www/aquadactyl
# Source code owned by root:www-data
sudo chown -R root:www-data /var/www/aquadactyl
sudo chmod 0750 blueprint.sh artisan
# Writable directories owned by www-data:www-data
sudo mkdir -p storage/framework/{cache/data,sessions,views} storage/logs bootstrap/cache
sudo chown -R www-data:www-data storage bootstrap/cache
sudo find storage bootstrap/cache -type d -exec chmod 0750 {} +
sudo find storage bootstrap/cache -type f -exec chmod 0640 {} +
sudo chmod 0640 .envStep 10: Update Web Server & Systemd Services
Update your web server configuration, background worker, and cron scheduler to point to the new /var/www/aquadactyl path and PHP 8.5.
Update Nginx Configuration
Edit your Nginx virtual host configuration (e.g. /etc/nginx/sites-available/pterodactyl.conf or rename to aquadactyl.conf):
- Update the web root path:
root /var/www/aquadactyl/public; - Update the PHP-FPM socket to PHP 8.5:
fastcgi_pass unix:/run/php/php8.5-fpm.sock;
Test and reload Nginx:
sudo nginx -t && sudo systemctl reload nginxMigrate Queue Worker (pteroq.service → aquaq.service)
Disable the legacy Pterodactyl queue worker and install the new Aquadactyl aquaq.service:
# Stop and disable old Pterodactyl queue worker
sudo systemctl stop pteroq.service 2>/dev/null || true
sudo systemctl disable pteroq.service 2>/dev/null || true
sudo rm -f /etc/systemd/system/pteroq.service
# Install and enable aquaq.service
sudo cp /var/www/aquadactyl/deploy/systemd/aquaq.service /etc/systemd/system/aquaq.service
sudo systemctl daemon-reload
sudo systemctl enable aquaq.serviceThe production aquaq.service unit definition:
[Unit]
Description=Aquadactyl queue worker
After=network-online.target mariadb.service redis-server.service
Wants=network-online.target
[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/aquadactyl
ExecStart=/usr/bin/php artisan queue:work --queue=high,standard,low --sleep=3 --tries=3 --timeout=120 --max-time=3600
Restart=always
RestartSec=5
TimeoutStopSec=180
KillSignal=SIGTERM
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true
[Install]
WantedBy=multi-user.targetUpdate Cron Scheduler
Update the cron task to execute /var/www/aquadactyl/artisan:
# Check if cron is located in /etc/cron.d/
sudo sed -i 's|/var/www/pterodactyl|/var/www/aquadactyl|g' /etc/cron.d/pterodactyl 2>/dev/null || true
if [ -f /etc/cron.d/pterodactyl ]; then
sudo mv /etc/cron.d/pterodactyl /etc/cron.d/aquadactyl
fi
# Or if configured in crontab:
(sudo crontab -u www-data -l 2>/dev/null | sed 's|/var/www/pterodactyl|/var/www/aquadactyl|g') | sudo crontab -u www-data -Step 11: Warm Caches & Bring Panel Online
Clear and re-cache Laravel settings, restart services, and exit maintenance mode:
cd /var/www/aquadactyl
# Warm Laravel caches
sudo -u www-data php artisan config:cache
sudo -u www-data php artisan route:cache
sudo -u www-data php artisan view:cache
# Restart PHP-FPM and queue worker
sudo systemctl restart php8.5-fpm
sudo systemctl start aquaq.service
# Bring the panel online
sudo -u www-data php artisan upStep 12: Verify Migration
- Log in to Panel: Open your browser at your panel domain. Log in with your existing administrator credentials.
- Check Nodes & Wings: Navigate to Admin -> Nodes. Your nodes should show green heartbeats. Your game servers will continue running with zero downtime.
- Verify Background Jobs: Check
sudo systemctl status aquaq.serviceto confirm the worker is actively processing queue jobs. - Clean up old files (Optional): Once you have fully verified the migration, you can archive or remove the old
/var/www/pterodactyldirectory.