Skip to main content

​
Pterodactyl Installation Guide

Pterodactyl is an open-source game server management panel built with PHP, React, and Go.
This guide covers Panel + Wings (Daemon) installation on a fresh Ubuntu 22.04 / 24.04 server.

​
Prerequisites

Before you begin, ensure you have:
RequirementDescription
OSUbuntu 22.04+ (root or sudo access)
Web ServerNGINX (recommended)
DatabaseMariaDB or MySQL
PHP8.2 or newer with required extensions
RedisInstalled and running
DockerRequired for Wings
DomainExample: panel.example.com
SSLLet’s Encrypt or manual

​
Install System Dependencies

sudo apt update && sudo apt upgrade -y
sudo apt install -y software-properties-common curl apt-transport-https ca-certificates gnupg lsb-release
Add PHP and Redis repositories: 
LC_ALL=C.UTF-8 sudo add-apt-repository ppa:ondrej/php -y
curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list
sudo apt update
Install required packages: 
sudo apt install -y nginx mariadb-server redis-server tar unzip git composer php8.2 php8.2-{cli,common,gd,mbstring,bcmath,xml,fpm,curl,zip,tokenizer}

​
Step 1: Configure MariaDB

Log into MySQL and create a database + user: 
sudo mysql -u root

CREATE DATABASE pterodactyl;
CREATE USER 'ptero'@'127.0.0.1' IDENTIFIED BY 'StrongPasswordHere';
GRANT ALL PRIVILEGES ON pterodactyl.* TO 'ptero'@'127.0.0.1';
FLUSH PRIVILEGES;
EXIT;

​
Step 2: Install the Panel

cd /var/www/
curl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz
tar -xzvf panel.tar.gz
mv panel pterodactyl
cd pterodactyl
Install dependencies: 
cp .env.example .env
composer install --no-dev --optimize-autoloader
php artisan key:generate --force

​
Configure Environment

Open .env and edit database + app settings: 
nano .env
Example values: 
APP_URL=https://panel.example.com
APP_TIMEZONE=UTC
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=pterodactyl
DB_USERNAME=ptero
DB_PASSWORD=StrongPasswordHere
Migrate and seed the database: 
php artisan migrate --seed --force

​
Set Permissions

chown -R www-data:www-data /var/www/pterodactyl
chmod -R 755 /var/www/pterodactyl

​
Step 3: NGINX Configuration

Create new site config: 
sudo nano /etc/nginx/sites-available/pterodactyl.conf
Paste this: 
server {
    listen 80;
    server_name panel.example.com;

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

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

    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
    }

    location ~ /\.ht {
        deny all;
    }
}
Enable the site: 
sudo ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

​
Step 4: Secure with SSL

Install Certbot and generate certificates: 
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d panel.example.com
Auto-renew setup: 
sudo crontab -e
# Add the line below:
0 23 * * * certbot renew --quiet --deploy-hook "systemctl reload nginx"

​
Step 5: Setup Cron & Queue

Add to crontab: 
* * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1
(Optional) Start queue worker manually: 
php artisan queue:work --daemon

​
Step 6: Install Wings (Daemon)

​
Install Docker

curl -fsSL https://get.docker.com | sh
systemctl enable --now docker

​
Install Wings

mkdir -p /etc/pterodactyl
cd /etc/pterodactyl
curl -Lo wings https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_amd64
chmod +x wings

​
Configure Wings

In your Panel → Nodes → Configuration, copy the generated YAML config and paste it into: 
nano /etc/pterodactyl/config.yml

​
Create Systemd Service

sudo nano /etc/systemd/system/wings.service
Paste: 
[Unit]
Description=Pterodactyl Wings
After=docker.service

[Service]
User=root
WorkingDirectory=/etc/pterodactyl
ExecStart=/etc/pterodactyl/wings
Restart=always
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target
Enable and start: 
systemctl enable wings
systemctl start wings

​
Step 7: Access Panel

Open your browser and go to: 
https://panel.example.com
You’ll be guided through initial setup.

​
Troubleshooting

ProblemSolution
502 Bad GatewayCheck php8.2-fpm service and NGINX config
Database connection failedVerify .env credentials
Wings not connectingCheck node token and domain SSL
Permission errorsEnsure correct file ownership (www-data)

​
References

Tip: For faster installs, check out pterodactyl-installer (unofficial).
Your panel is now live! Login at your domain, connect nodes, and start deploying game servers.