Install Pterodactyl Panel on VPS (2026)

E-E-A-THands-on installation guide

A production-ready walkthrough for deploying Pterodactyl Panel and Wings on a fresh VPS — with secure defaults, SSL, and Docker — on Debian 12 and Ubuntu 22.04/24.04.

Tested on fresh Debian 12 (Bookworm) and Ubuntu 22.04 LTS / 24.04 LTS VPS instances in March 2026.
Commands validated with Pterodactyl Panel v1.x and Wings v1.x (latest stable releases).
Security configurations follow CIS Benchmarks and Pterodactyl's official hardening recommendations.

Updated on 5 mars 2026 Tested on Debian 12 & Ubuntu 22.04/24.04

Minimum 2 GB RAM for the panel — 4 GB+ recommended for Wings on the same machine.

PHP 8.3, MariaDB 10.11+, Redis, and Nginx are the core stack.

Wings requires Docker and a separate node configuration generated from the panel.

1. VPS Requirements & Prerequisites

Before starting, make sure your VPS meets the minimum hardware and software requirements. Pterodactyl Panel is relatively lightweight, but Wings (the game server daemon) can be resource-intensive depending on how many game servers you plan to host.

You also need a domain name (or subdomain) pointing to your server's IP — Certbot requires it for automatic SSL certificate issuance.

Debian 12 / Ubuntu 22.04 or 24.04 LTS

RAM (Panel only)

Minimum 2 GB — 4 GB recommended

RAM (Panel + Wings)

Minimum 4 GB — 8 GB recommended

Disk

20 GB NVMe minimum — 50 GB+ for game servers

Domain

A record pointed to your VPS IP (e.g. panel.example.com)

Access

Root or sudo privileges

If you plan to run Wings on the same machine as the panel (single-node setup), start with at least 4 GB RAM and 2 vCPU. For a multi-node setup, install Wings on separate VPS instances.

2. System Preparation

Start with a full system update and install the essential build tools. This ensures your package list is up to date and all later installations resolve dependencies correctly.

Debian 12 / Ubuntu 22.04 & 24.04

apt update && apt upgrade -y
apt install -y curl wget tar unzip git software-properties-common apt-transport-https ca-certificates gnupg lsb-release

3. Install PHP 8.3 & Required Extensions

Pterodactyl Panel requires PHP 8.1 or higher. We recommend PHP 8.3 for the best performance and long-term support. The setup differs slightly between Debian and Ubuntu — use the matching block below.

Verify PHP is installed correctly: run `php -v` — you should see PHP 8.3.x.

Ubuntu 22.04 / 24.04 — add Ondrej PPA

add-apt-repository ppa:ondrej/php -y
apt update

Debian 12 — add Sury repository

curl -sSL https://packages.sury.org/php/apt.gpg | gpg --dearmor -o /usr/share/keyrings/sury-php.gpg
echo "deb [signed-by=/usr/share/keyrings/sury-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main"   > /etc/apt/sources.list.d/sury-php.list
apt update

Both — install PHP 8.3 and required extensions

apt install -y php8.3 php8.3-cli php8.3-fpm php8.3-mysql \
  php8.3-gd php8.3-mbstring php8.3-bcmath php8.3-xml \
  php8.3-zip php8.3-curl php8.3-intl php8.3-redis php8.3-tokenizer

4. Install MariaDB & Create the Database

Pterodactyl uses a relational database to store all panel data: users, servers, nodes, and configurations. MariaDB 10.11+ is recommended for full compatibility.

Replace 'your_strong_password' with a secure, randomly generated password. Store it safely — you will need it in the .env configuration step.

Install MariaDB

apt install -y mariadb-server
systemctl enable --now mariadb
mysql_secure_installation

Create the panel database and user

mysql -u root -p

# Inside the MySQL shell:
CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'your_strong_password';
CREATE DATABASE panel;
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1' WITH GRANT OPTION;
FLUSH PRIVILEGES;
EXIT;

5. Install Redis

Redis is used by Pterodactyl for queue management and caching. It dramatically improves panel responsiveness for real-time server status updates.

Install and enable Redis

apt install -y redis-server
systemctl enable --now redis-server

6. Install Nginx

Nginx serves as the reverse proxy and web server for Pterodactyl Panel. It handles HTTPS termination and PHP-FPM communication.

Install Nginx

apt install -y nginx
systemctl enable --now nginx

7. Download & Install the Panel

Pterodactyl Panel is a Laravel application. First install Composer (the PHP dependency manager), then download the latest panel release and set up the required directory permissions.

Install Composer

curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

Download Pterodactyl Panel

mkdir -p /var/www/pterodactyl
cd /var/www/pterodactyl

curl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz
tar -xzvf panel.tar.gz
rm panel.tar.gz

chmod -R 755 storage/* bootstrap/cache/

Install PHP dependencies

cd /var/www/pterodactyl
composer install --no-dev --optimize-autoloader

8. Configure the Environment

This step sets up your application key, connects the panel to the database, and creates your first administrator account. Take your time here — errors in this step are the most common source of installation failures.

When running p:environment:setup, set your APP_URL to the full HTTPS domain you will use (e.g. https://panel.example.com). This is required for correct webhook and OAuth callbacks.

Copy the example .env and generate the app key

cd /var/www/pterodactyl
cp .env.example .env
php artisan key:generate --force

Run the interactive setup wizard

# Environment setup (app URL, timezone, cache/session/queue drivers)
php artisan p:environment:setup

# Database setup (uses credentials from step 4)
php artisan p:environment:database

# Optional: mail setup for password resets and notifications
php artisan p:environment:mail

Run migrations and seed the database

php artisan migrate --seed --force

Create your first admin user

php artisan p:user:make

Set correct file ownership

chown -R www-data:www-data /var/www/pterodactyl/*

9. Configure the Queue Worker

Pterodactyl uses a queue worker to process background tasks: server state changes, backups, and notifications. We run it as a systemd service so it restarts automatically on reboot or crash.

Create /etc/systemd/system/pteroq.service

[Unit]
Description=Pterodactyl Queue Worker
After=redis-server.service

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/pterodactyl/artisan queue:work \
  --queue=high,standard,low --sleep=3 --tries=3
StartLimitInterval=180
StartLimitBurst=30
RestartSec=5s

[Install]
WantedBy=multi-user.target

Enable and start the queue worker

systemctl enable --now pteroq.service
systemctl status pteroq.service

10. Configure Nginx & Enable SSL with Let's Encrypt

We configure Nginx to serve the Pterodactyl panel over HTTPS. Certbot handles the SSL certificate automatically via the Let's Encrypt ACME protocol. Replace `panel.example.com` with your actual domain throughout.

After running these commands, visit https://panel.example.com — you should see the Pterodactyl login screen. Log in with the admin account you created in step 8.

Install Certbot

apt install -y certbot python3-certbot-nginx

Create /etc/nginx/sites-available/pterodactyl.conf

server {
    listen 80;
    server_name panel.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name panel.example.com;

    root /var/www/pterodactyl/public;
    index index.php;

    access_log /var/log/nginx/pterodactyl.app-access.log;
    error_log  /var/log/nginx/pterodactyl.app-error.log error;

    client_max_body_size 100m;
    client_body_timeout 120s;

    ssl_certificate     /etc/letsencrypt/live/panel.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/panel.example.com/privkey.pem;
    ssl_session_cache   shared:SSL:10m;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;

    add_header X-Content-Type-Options nosniff;
    add_header X-Frame-Options DENY;
    add_header X-XSS-Protection "1; mode=block";
    add_header Referrer-Policy same-origin;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param HTTP_PROXY "";
        fastcgi_buffer_size 16k;
        fastcgi_buffers 4 16k;
        fastcgi_connect_timeout 300;
        fastcgi_send_timeout 300;
        fastcgi_read_timeout 300;
    }

    location ~ /\.ht {
        deny all;
    }
}

Issue the SSL certificate and activate the site

# Issue the certificate (Nginx must already be running)
certbot certonly --nginx -d panel.example.com

# Enable the site
ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

11. Install Docker & Wings (the Daemon)

Wings is the lightweight Go daemon that actually runs game servers inside Docker containers. It communicates with the Panel over a secure WebSocket connection. Install it on the same VPS (single-node) or on separate machines (multi-node).

Install Docker

curl -sSL https://get.docker.com/ | CHANNEL=stable bash
systemctl enable --now docker

Download Wings binary

mkdir -p /etc/pterodactyl

curl -L -o /usr/local/bin/wings \
  "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_amd64"

chmod u+x /usr/local/bin/wings

Create /etc/systemd/system/wings.service

[Unit]
Description=Pterodactyl Wings Daemon
After=docker.service
Requires=docker.service

[Service]
User=root
WorkingDirectory=/etc/pterodactyl
LimitNOFILE=4096
PIDFile=/var/run/wings/daemon.pid
ExecStart=/usr/local/bin/wings
Restart=on-failure
StartLimitInterval=180
StartLimitBurst=30
RestartSec=5s

[Install]
WantedBy=multi-user.target

Enable Wings (don't start yet — configure first)

systemctl enable wings

12. Create a Node & Connect Wings to the Panel

The final step is to create a node in the Pterodactyl admin area, generate a configuration token, and feed it to Wings. Once Wings starts, the node will appear as Online in the panel and you can deploy your first game server.

Congratulations — your Pterodactyl installation is complete! For multi-node setups, repeat steps 11 and 12 on each additional VPS, pointing each Wings instance to the same Panel.

In the Pterodactyl admin panel, go to Admin → Locations → Create New Location.
Then go to Admin → Nodes → Create New Node. Set the FQDN to your server's domain or IP, set the scheme to HTTPS if using a domain, and configure your memory and disk allocation limits.
After saving the node, click the Configuration tab and then Generate Token.
Back on your server, run the command shown by the panel — it writes /etc/pterodactyl/config.yml automatically.
Start Wings: systemctl start wings — then check systemctl status wings to confirm it is active.
Return to the panel; the node should now show a green Online indicator. You can now create Allocations, install Eggs (game templates), and launch your first server.

FAQ

Can I install Pterodactyl Panel and Wings on the same server?

Yes, this is called a single-node setup. It works well for personal use or small communities. Use at least 4 GB RAM and ensure the panel's Nginx config doesn't conflict with Wings' port (8080/8443 by default). For production environments hosting many players, a dedicated Wings node is recommended.

Which OS is best: Debian 12 or Ubuntu 22.04?

Both work equally well with Pterodactyl. Debian 12 is slightly leaner and a common choice for stable server environments. Ubuntu 22.04/24.04 LTS is also fully supported and benefits from broader community documentation. Choose whichever you are more comfortable managing.

Wings fails to start — what should I check first?

Run `journalctl -u wings --no-pager -n 50` to view the last 50 log lines. Common causes: missing /etc/pterodactyl/config.yml (did you run the configuration command from the panel?), Docker not running, or a port conflict on 8080/8443. Ensure Docker is active with `systemctl status docker`.

How do I update Pterodactyl Panel after installation?

Put the panel in maintenance mode (php artisan down), download the new release tarball, extract it over your existing installation, run composer install --no-dev --optimize-autoloader, then php artisan migrate --force, php artisan view:clear, php artisan config:clear, and finally php artisan up. Always back up your database before upgrading.

Do I need to open any firewall ports?

Yes. Open ports 80 and 443 (HTTP/HTTPS for the panel), and 8080 and 8443 (Wings API and SFTP) on the Wings node. If using ufw: ufw allow 80/tcp && ufw allow 443/tcp && ufw allow 8080/tcp && ufw allow 8443/tcp.

Sources et references

Sujets

#pterodactyl#vps#debian#ubuntu#game-panel#wings#nginx#ssl

Retour au blog