Installation Guide

This guide will walk you through installing Pterodactyl Panel and the Wings daemon. Follow each step carefully to ensure a successful installation.

This installation assumes you have a fresh server meeting all system requirements. Installing on an existing server with other applications may cause conflicts.

Overview

Pterodactyl installation consists of three main components:

Panel Installation

Install the web interface and management system

Wings Installation

Install the server control daemon on game server nodes

Configuration

Connect Wings to the Panel and configure your first server

Prerequisites

Before beginning, ensure you have:

A server meeting system requirements
Root or sudo access to the server
A domain name pointing to your server IP
Basic knowledge of Linux command line

It’s recommended to run the Panel and Wings on separate servers in production. However, they can be installed on the same machine for testing.

Part 1: Panel Installation

Step 1: Install Dependencies

First, update your system and install required dependencies.

# Update system
apt update && apt upgrade -y

# Install dependencies
apt install -y software-properties-common curl apt-transport-https ca-certificates gnupg

# Add PHP repository
LC_ALL=C.UTF-8 add-apt-repository -y ppa:ondrej/php
apt update

# Install PHP and extensions
apt install -y php8.2 php8.2-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip}

# Install MariaDB
apt install -y mariadb-server

# Install NGINX
apt install -y nginx

# Install Redis
apt install -y redis-server

# Start and enable services
systemctl enable --now mariadb
systemctl enable --now redis-server

Step 2: Install Composer

Composer is required to install PHP dependencies.

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

Verify installation:

composer --version

Step 3: Download Panel Files

Create the directory for the Panel and download the files.

# Create directory
mkdir -p /var/www/pterodactyl
cd /var/www/pterodactyl

# Download Panel
curl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz
tar -xzvf panel.tar.gz
chmod -R 755 storage/* bootstrap/cache/

Step 4: Configure Database

Secure your MySQL installation and create the Panel database.

# Run MySQL secure installation
mysql_secure_installation

When prompted, set a strong root password and answer ‘Y’ to all security questions.

Now create the Panel database and user:

mysql -u root -p

CREATE DATABASE panel;
CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'yourStrongPassword';
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1' WITH GRANT OPTION;
FLUSH PRIVILEGES;
exit;

Replace yourStrongPassword with a secure password. Never use the root MySQL user for the Panel.

Step 5: Install Panel Dependencies

Install PHP dependencies using Composer.

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

This process may take several minutes depending on your server’s speed.

Step 6: Environment Configuration

Generate the environment file and application key.

# Copy environment file
cp .env.example .env

# Generate application key
php artisan key:generate --force

Now configure the environment:

php artisan p:environment:setup

You’ll be prompted to enter:

Author Email: Your email address for Let’s Encrypt
Application URL: Your Panel URL (e.g., https://panel.example.com)
Timezone: Your timezone (e.g., America/New_York)
Cache Driver: Select redis (recommended)
Session Driver: Select redis (recommended)
Queue Driver: Select redis (recommended)

Next, configure database settings:

php artisan p:environment:database

Enter the database credentials:

Database Host: 127.0.0.1
Database Port: 3306
Database Name: panel
Username: pterodactyl
Password: The password you set earlier

Step 7: Database Setup

Run database migrations to set up the Panel schema.

php artisan migrate --seed --force

Step 8: Create Admin User

Create your first administrator account.

php artisan p:user:make

Enter:

Email: Your email address
Username: Your username
First Name: Your first name
Last Name: Your last name
Password: A strong password
Admin: yes

Step 9: Set Permissions

Set the correct ownership and permissions.

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

Step 10: Configure Queue Worker

Create a systemd service for the queue worker.

nano /etc/systemd/system/pteroq.service

Paste the following:

[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 service:

systemctl enable --now pteroq.service

Step 11: Configure Cron Job

Add a cron job for scheduled tasks.

crontab -e

Add this line:

* * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1

Step 12: Configure Web Server

Configure NGINX or Apache to serve the Panel.

NGINX
Apache

Remove the default configuration:

rm /etc/nginx/sites-enabled/default

Create the Panel configuration:

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

Paste the following (replace panel.example.com with your domain):

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

server {
    listen 443 ssl http2;
    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;

    # SSL Configuration - Replace with your certificates
    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_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384";
    ssl_prefer_server_ciphers on;

    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Robots-Tag none;
    add_header Content-Security-Policy "frame-ancestors 'self'";
    add_header X-Frame-Options DENY;
    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.2-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param PHP_VALUE "upload_max_filesize = 100M \n post_max_size=100M";
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param HTTP_PROXY "";
        fastcgi_intercept_errors off;
        fastcgi_buffer_size 16k;
        fastcgi_buffers 4 16k;
        fastcgi_connect_timeout 300;
        fastcgi_send_timeout 300;
        fastcgi_read_timeout 300;
        include /etc/nginx/fastcgi_params;
    }

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

Enable the configuration:

ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/pterodactyl.conf

Test and restart NGINX:

nginx -t
systemctl restart nginx

Create the Panel configuration:

nano /etc/apache2/sites-available/pterodactyl.conf

Paste the following (replace panel.example.com):

<VirtualHost *:80>
  ServerName panel.example.com
  RewriteEngine On
  RewriteCond %{HTTPS} !=on
  RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]
</VirtualHost>

<VirtualHost *:443>
  ServerName panel.example.com
  DocumentRoot "/var/www/pterodactyl/public"
  
  AllowEncodedSlashes On
  
  php_value upload_max_filesize 100M
  php_value post_max_size 100M
  
  <Directory "/var/www/pterodactyl/public">
    Require all granted
    AllowOverride all
  </Directory>
  
  SSLEngine on
  SSLCertificateFile /etc/letsencrypt/live/panel.example.com/fullchain.pem
  SSLCertificateKeyFile /etc/letsencrypt/live/panel.example.com/privkey.pem
</VirtualHost>

Enable required modules and site:

a2enmod rewrite
a2enmod ssl
a2ensite pterodactyl.conf
systemctl restart apache2

Step 13: Install SSL Certificate

Install Certbot and obtain an SSL certificate.

apt install -y certbot
# For NGINX:
apt install -y python3-certbot-nginx
# For Apache:
apt install -y python3-certbot-apache

Obtain the certificate:

certbot --nginx -d panel.example.com

Certbot will automatically configure SSL and set up auto-renewal.

Panel Installation Complete!

You should now be able to access your Panel at https://panel.example.com. Log in with the admin account you created.

Part 2: Wings Installation

Wings must be installed on every server where you want to run game servers. This can be the same server as the Panel or separate machines.

Step 1: Install Docker

Install Docker on your Wings node.

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

Verify Docker is running:

docker --version

Step 2: Enable Swap (Optional but Recommended)

Enable swap to prevent out-of-memory issues.

# Check if swap exists
swapon --show

# If no swap, create a 2GB swap file
fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile

# Make it permanent
echo '/swapfile none swap sw 0 0' | tee -a /etc/fstab

Step 3: Download Wings

Download the Wings binary.

mkdir -p /etc/pterodactyl
curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
chmod u+x /usr/local/bin/wings

Step 4: Create Node in Panel

Before configuring Wings, you need to create a node in the Panel.

Access Admin Panel

Create Location

Go to Locations → Create New and create a location (e.g., “US East”)

Create Node

Go to Nodes → Create New and fill in:

Name: A descriptive name (e.g., “Node-1”)
Location: Select the location you created
FQDN: Your node’s domain or IP (e.g., node1.example.com)
Communicate Over SSL: Enable if using HTTPS
Behind Proxy: Enable if behind a proxy
Memory: Total RAM to allocate to servers
Disk Space: Total disk space to allocate

Get Configuration

After creating the node, go to the Configuration tab and copy the configuration file

Step 5: Configure Wings

Create the Wings configuration file.

nano /etc/pterodactyl/config.yml

Paste the configuration from the Panel (Step 4). It should look similar to:

debug: false
uuid: your-node-uuid
token_id: your-token-id
token: your-token
api:
  host: 0.0.0.0
  port: 8080
  ssl:
    enabled: false
    cert: /etc/letsencrypt/live/node1.example.com/fullchain.pem
    key: /etc/letsencrypt/live/node1.example.com/privkey.pem
system:
  root_directory: /var/lib/pterodactyl/volumes
  log_directory: /var/log/pterodactyl
  data: /var/lib/pterodactyl
  sftp:
    bind_port: 2022
allowed_mounts: []
remote: 'https://panel.example.com'

Ensure the remote URL points to your Panel URL and matches exactly (including https:// and no trailing slash).

Step 6: Create Wings Service

Create a systemd service for Wings.

nano /etc/systemd/system/wings.service

Paste:

[Unit]
Description=Pterodactyl Wings Daemon
After=docker.service
Requires=docker.service
PartOf=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 and start Wings:

systemctl enable --now wings

Check status:

systemctl status wings

Step 7: Configure Firewall

Open necessary ports for Wings.

# Wings API (for Panel communication)
ufw allow 8080/tcp

# SFTP
ufw allow 2022/tcp

# Game server ports (adjust range as needed)
ufw allow 25565:25665/tcp
ufw allow 25565:25665/udp

# Enable firewall
ufw enable

Step 8: Verify Connection

In your Panel, navigate to Admin → Nodes and check if the node shows as online with a green heart icon.

If the node appears offline, check:

Wings service is running: systemctl status wings
Firewall allows port 8080
The remote URL in config.yml is correct
Wings logs: journalctl -u wings -n 50

Part 3: Creating Your First Server

Now that both Panel and Wings are installed, create your first game server.

Step 1: Import Eggs

Eggs are server templates. Import default eggs:

Download Eggs

Visit pterodactyl-eggs repository and download eggs for your desired games

Import to Panel

Go to Admin → Nests → Select a nest → Import Egg and upload the JSON file

The Panel comes with some default eggs, but the community repository has many more options.

Step 2: Create Allocations

Allocations are IP:Port combinations for game servers.

Go to Admin → Nodes → Select your node → Allocation
Enter:
- IP Address: Your server’s IP
- Ports: Port range (e.g., 25565-25665)
Click Submit

Step 3: Create Server

Navigate to Servers

Go to Admin → Servers → Create New

Core Details

Server Name: Name your server
Server Owner: Select a user
Description: Optional description

Allocation

Node: Select your node
Default Allocation: Select an available allocation

Application Feature Limits

Configure database and backup limits

Resource Management

Memory: Allocated RAM (MB)
Disk Space: Allocated disk (MB)
CPU Limit: CPU percentage (100 = 1 core)

Nest Configuration

Nest: Select game category (e.g., Minecraft)
Egg: Select server type (e.g., Paper)
Docker Image: Default is usually fine
Startup Command: Customize if needed

Create Server

Click Create Server and wait for installation

Step 4: Access Server

Once created, access your server:

Go to the client area (not admin)
Click on your server
Use the console to start/stop and manage your server

Troubleshooting

Panel Issues

500 Error - Missing manifest.json

This occurs when assets aren’t built. If using pre-built releases, ensure you extracted all files correctly.For development:

cd /var/www/pterodactyl
yarn install
yarn build:production

Queue worker not processing jobs

Check the queue worker status:

systemctl status pteroq

View logs:

journalctl -u pteroq -n 100

Can't connect to database

Verify database credentials in /var/www/pterodactyl/.envTest connection:

mysql -u pterodactyl -p panel

Wings Issues

Node appears offline

Check Wings status:

systemctl status wings

View logs:

journalctl -u wings -n 100

Verify:

Port 8080 is accessible from Panel
SSL configuration matches Panel settings
remote URL in config.yml is correct

Server installation fails

Check Wings logs:

tail -f /var/log/pterodactyl/wings.log

Verify:

Docker is running: systemctl status docker
Disk space available: df -h
Permissions on /var/lib/pterodactyl

Can't connect to SFTP

Verify:

Wings is running
Port 2022 is open in firewall
Using Panel username and password
SFTP address is node_address:2022

Post-Installation

Security Hardening

Enable 2FA

Enable Two-Factor Authentication for all admin accounts

Configure Firewall

Ensure only necessary ports are open

Regular Updates

Keep Panel, Wings, and system packages updated

Backup Strategy

Configure automated backups for database and server files

Optimization

Configure Redis for better performance
Set up queue workers for background processing
Enable OPcache for PHP performance
Consider CDN for static assets (large installations)
Monitor resource usage and scale as needed

Updating

To update Pterodactyl:

Panel Update
Wings Update

cd /var/www/pterodactyl

# Enter maintenance mode
php artisan down

# Download update
curl -L -o panel.tar.gz https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz
tar -xzvf panel.tar.gz

# Update dependencies
composer install --no-dev --optimize-autoloader

# Clear caches
php artisan view:clear
php artisan config:clear

# Run migrations
php artisan migrate --seed --force

# Set permissions
chown -R www-data:www-data /var/www/pterodactyl/*

# Exit maintenance mode
php artisan up

# Restart queue worker
systemctl restart pteroq

# Stop Wings
systemctl stop wings

# Download latest Wings
curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
chmod u+x /usr/local/bin/wings

# Start Wings
systemctl start wings

Always backup your database and configuration files before updating!

Next Steps

Official Documentation

Read the complete documentation for advanced configuration

Community Discord

Join the community for support and discussions

API Documentation

Learn how to integrate with the Pterodactyl API

Community Eggs

Browse hundreds of community-maintained server eggs

Support

If you encounter issues:

Check the official documentation
Search existing GitHub issues
Join the Discord server for community help
Review logs for error messages

When asking for help, always provide:

Panel and Wings versions
Operating system and version
Error messages from logs
Steps to reproduce the issue

Getting Started

Panel Administration

Server Management

User Guide

Configuration

Advanced

​Installation Guide

​Overview

​Prerequisites

​Part 1: Panel Installation

​Step 1: Install Dependencies

​Step 2: Install Composer

​Step 3: Download Panel Files

​Step 4: Configure Database

​Step 5: Install Panel Dependencies

​Step 6: Environment Configuration

​Step 7: Database Setup

​Step 8: Create Admin User

​Step 9: Set Permissions

​Step 10: Configure Queue Worker

​Step 11: Configure Cron Job

​Step 12: Configure Web Server

​Step 13: Install SSL Certificate

​Panel Installation Complete!

​Part 2: Wings Installation

​Step 1: Install Docker

​Step 2: Enable Swap (Optional but Recommended)

​Step 3: Download Wings

​Step 4: Create Node in Panel

​Step 5: Configure Wings

​Step 6: Create Wings Service

​Step 7: Configure Firewall

​Step 8: Verify Connection

​Part 3: Creating Your First Server

​Step 1: Import Eggs

​Step 2: Create Allocations

​Step 3: Create Server

​Step 4: Access Server

​Troubleshooting

​Panel Issues

​Wings Issues

​Post-Installation

​Security Hardening

​Optimization

​Updating

​Next Steps

Official Documentation

Community Discord

API Documentation

Community Eggs

​Support

Build docs developers (and LLMs) love

Installation Guide

Overview

Prerequisites

Part 1: Panel Installation

Step 1: Install Dependencies

Step 2: Install Composer

Step 3: Download Panel Files

Step 4: Configure Database

Step 5: Install Panel Dependencies

Step 6: Environment Configuration

Step 7: Database Setup

Step 8: Create Admin User

Step 9: Set Permissions

Step 10: Configure Queue Worker

Step 11: Configure Cron Job

Step 12: Configure Web Server

Step 13: Install SSL Certificate

Panel Installation Complete!

Part 2: Wings Installation

Step 1: Install Docker

Step 2: Enable Swap (Optional but Recommended)

Step 3: Download Wings

Step 4: Create Node in Panel

Step 5: Configure Wings

Step 6: Create Wings Service

Step 7: Configure Firewall

Step 8: Verify Connection

Part 3: Creating Your First Server

Step 1: Import Eggs

Step 2: Create Allocations

Step 3: Create Server

Step 4: Access Server

Troubleshooting

Panel Issues

Wings Issues

Post-Installation

Security Hardening

Optimization

Updating

Next Steps

Support