EN

Game servers

Install the Pterodactyl Panel and Wings

Install Pterodactyl on your Linux server: panel, database, HTTPS, Docker, Wings, node, ports, allocations, first game server, updates and troubleshooting.

12 min read, updated on 18 November 2026

On this page

Your values

Enter them once and the commands in this guide update.

This guide explains how to install Pterodactyl on your Linux server to manage your game servers from a web interface. It covers the panel, Wings, HTTPS, ports, allocations and a first game server.

HostMyServers does not offer managed game hosting: you install and administer Pterodactyl yourself. This guide follows the project's official documentation for the stable 1.x branch.

Order a Server

Pterodactyl runs on a VPS or a dedicated server:

Plan for the resources of the panel, Docker and all the game servers you intend to run.

How It Works

Component Role
Panel PHP web application: accounts, servers, permissions. It uses MariaDB and Redis
Wings Service installed on each machine that hosts games. It controls Docker
Node Machine running Wings, declared in the panel
Allocation IP address and port pair assigned to a game server
Egg Template that describes how to install and launch a game

This guide installs the panel and Wings on the same machine. To put Wings on another machine, follow steps 9 to 13 there, open the node's ports there and get its certificate with certbot certonly --standalone, since no web server is needed on it.

Prerequisites

  • A 64-bit server running Debian 12 or 13, or Ubuntu 22.04 or 24.04
  • root access or a sudo user
  • Two subdomains pointing to the server, with a DNS A record: panel.your-domain.com and node1.your-domain.com
  • Virtualization compatible with Docker

Check the virtualization type and the DNS:

Terminal
systemd-detect-virt
getent hosts panel.your-domain.com node1.your-domain.com

KVM and none (physical machine) are suitable. With openvz or lxc, Wings will probably not work.

The following commands are run as root. Open a session with:

Terminal
sudo -i

Ports Used

Port Protocol Service Access
22 TCP SSH Administration
80 TCP Nginx, Let's Encrypt validation and redirection Public
443 TCP Panel over HTTPS Public
8080 TCP Wings API, used by the panel and browsers Public
2022 TCP Wings SFTP, for server files Public
Allocations TCP and UDP Games, for example 27015 to 27020 Public

MariaDB (3306) and Redis (6379) stay local: do not open them.

Step 1: Open the Ports

With UFW, allow SSH before enabling the firewall, adapting the port if you changed the SSH one:

Terminal
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 8080/tcp
ufw allow 2022/tcp
ufw enable
ufw status

With iptables or nftables, open the same TCP ports. Do not save the whole rule set once Docker is installed, because it adds its own rules: add your rules to your configuration file.

Step 2: Install the Panel Dependencies

The panel requires PHP 8.2 or 8.3 (8.3 recommended), MariaDB 10.2 or later, Redis, a web server and Composer 2. Only run the block for your system.

Debian 13

Terminal
apt update
apt install -y curl ca-certificates gnupg2 sudo lsb-release
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" | tee /etc/apt/sources.list.d/sury-php.list
curl -fsSL https://packages.sury.org/php/apt.gpg | gpg --dearmor -o /etc/apt/trusted.gpg.d/sury-keyring.gpg
apt update
apt install -y php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx tar unzip git redis-server

Debian 12

Terminal
apt update
apt install -y curl ca-certificates gnupg2 sudo lsb-release
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" | tee /etc/apt/sources.list.d/sury-php.list
curl -fsSL https://packages.sury.org/php/apt.gpg | gpg --dearmor -o /etc/apt/trusted.gpg.d/sury-keyring.gpg
curl -fsSL https://packages.redis.io/gpg | 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" | tee /etc/apt/sources.list.d/redis.list
curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | bash
apt update
apt install -y php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx tar unzip git redis-server

Ubuntu 24.04

Terminal
apt update
apt install -y software-properties-common curl apt-transport-https ca-certificates gnupg lsb-release
curl -fsSL https://packages.redis.io/gpg | 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" | tee /etc/apt/sources.list.d/redis.list
apt update
apt install -y php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx tar unzip git redis-server

Ubuntu 22.04

Terminal
apt update
apt install -y software-properties-common curl apt-transport-https ca-certificates gnupg lsb-release
LC_ALL=C.UTF-8 add-apt-repository -y ppa:ondrej/php
curl -fsSL https://packages.redis.io/gpg | 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" | tee /etc/apt/sources.list.d/redis.list
apt update
apt install -y php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx tar unzip git redis-server

Composer and Verification

On all systems, install Composer, enable Redis and check the versions:

Terminal
curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
systemctl enable --now redis-server
php -v
composer --version
mariadb --version
redis-cli ping

php -v must display a 8.3 version and redis-cli ping must answer PONG.

Step 3: Create the Database

Generate a password and keep it:

Terminal
openssl rand -base64 24

Open MariaDB. If a password is requested and you have not set one, press Enter.

Terminal
mariadb -u root -p
SQL
CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'GeneratedPassword';
CREATE DATABASE panel;
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1' WITH GRANT OPTION;
exit

Step 4: Download the Panel

Terminal
mkdir -p /var/www/pterodactyl
cd /var/www/pterodactyl
curl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/download/v1.15.2/panel.tar.gz
tar -xzvf panel.tar.gz
chmod -R 755 storage/* bootstrap/cache/

Step 5: Configure the Panel

Install the PHP dependencies and generate the encryption key:

Terminal
cp .env.example .env
COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader
php artisan key:generate --force
grep APP_KEY /var/www/pterodactyl/.env

Then run the configuration wizards:

Terminal
php artisan p:environment:setup
php artisan p:environment:database
php artisan p:environment:mail
Question Recommended answer
Egg Author Email Your email address
Application URL https://panel.your-domain.com
Application Timezone Europe/Paris or your time zone
Cache Driver, Session Driver and Queue Driver redis
Enable UI based settings editor? yes
Enable sending anonymous telemetry data? Your choice
Redis Host and port 127.0.0.1 and 6379, no password on a default local installation
Database Host and Database Port 127.0.0.1 and 3306
Database Name panel
Database Username pterodactyl
Database Password The password from step 3

For emails, the project recommends an SMTP server rather than PHP's internal mailer. The panel's telemetry is anonymous and documented by the project.

Create the tables, then your administrator account. The migration can take a while: do not interrupt it.

Terminal
php artisan migrate --seed --force
php artisan p:user:make
chown -R www-data:www-data /var/www/pterodactyl/*

Answer yes to the Is this user an administrator? question. The password must be at least 8 characters long, with uppercase letters, lowercase letters and a digit.

Step 6: Enable Background Tasks

Open root's crontab:

Terminal
crontab -e

Add this line:

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

Create the queue service:

Terminal
nano /etc/systemd/system/pteroq.service
Configuration
# Pterodactyl Queue Worker File
# ----------------------------------

[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 it and check its status:

Terminal
systemctl daemon-reload
systemctl enable --now pteroq.service
systemctl is-active pteroq.service

The command must answer active.

Step 7: Get the HTTPS Certificates

The panel and Wings each need a certificate. If the panel uses HTTPS, Wings must too.

Terminal
apt install -y certbot python3-certbot-nginx
certbot certonly --nginx -d panel.your-domain.com
certbot certonly --nginx -d node1.your-domain.com

Create a script to apply renewed certificates to Nginx and Wings:

Terminal
nano /etc/letsencrypt/renewal-hooks/deploy/pterodactyl.sh
Terminal
#!/bin/bash
systemctl reload nginx
systemctl try-restart wings
Terminal
chmod 750 /etc/letsencrypt/renewal-hooks/deploy/pterodactyl.sh
certbot renew --dry-run

Restarting Wings does not stop running game servers. The renewal test must finish without errors.

Step 8: Configure Nginx

Remove the default site and create the panel's:

Terminal
rm /etc/nginx/sites-enabled/default
nano /etc/nginx/sites-available/pterodactyl.conf
Nginx
server {
    listen 80;
    server_name panel.your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name panel.your-domain.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;

    # allow larger file uploads and longer script runtimes
    client_max_body_size 100m;
    client_body_timeout 120s;

    sendfile off;

    ssl_certificate /etc/letsencrypt/live/panel.your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/panel.your-domain.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.3-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 site:

Terminal
ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/pterodactyl.conf
nginx -t
systemctl restart nginx

Open https://panel.your-domain.com and log in with the account created in step 5. The browser padlock must be valid.

Step 9: Install Docker

Wings runs each game server in a Docker container. Install Docker Engine with the Install Docker Engine and Docker Compose guide, then check that it starts with the system:

Terminal
systemctl enable --now docker
docker info --format '{{.ServerVersion}}'

If docker info displays WARNING: No swap limit support and your kernel is older than 6.1, add swapaccount=1 to GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub, run update-grub and reboot. This setting is optional.

Step 10: Install Wings

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

This command pins version v1.13.5, the latest 1.x release at the time of writing. See the Wings releases before installing.

Step 11: Create the Node in the Panel

In the panel's administration area:

  1. Open Locations, click Create New and create a location, for example fr
  2. Open Nodes, then click Create New
  3. Fill in the form:
Field Value
Name node1
Location The location you created
FQDN node1.your-domain.com
Communicate Over SSL Use SSL Connection
Behind Proxy Not Behind Proxy
Daemon Server File Directory /var/lib/pterodactyl/volumes
Total Memory Memory reserved for games, in MiB
Memory Over-Allocation 0
Total Disk Space Disk reserved for games, in MiB
Disk Over-Allocation 0
Daemon Port 8080
Daemon SFTP Port 2022

Keep a margin for the system, the panel, MariaDB and Docker.

  1. After creation, open the node's Configuration tab and copy the block displayed
  2. Paste it on the server, then protect the file, which contains a secret token:
Terminal
nano /etc/pterodactyl/config.yml
chmod 600 /etc/pterodactyl/config.yml

The Generate Token button also provides a command that writes this file for you.

Step 12: Start Wings

First run Wings in the foreground to see any errors:

Terminal
wings --debug

When it runs without errors, stop it with Ctrl+C, then create its service:

Terminal
nano /etc/systemd/system/wings.service
Configuration
[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
Terminal
systemctl daemon-reload
systemctl enable --now wings
systemctl is-active wings
curl https://node1.your-domain.com:8080

The service must be active. The curl command must return a JSON message saying authorization is missing: this proves the API responds and the certificate is valid. In Nodes, the node must show a green heart.

Step 13: Create the Allocations

Get the server's IP address:

Terminal
hostname -I | awk '{print $1}'

In Nodes, open your node, then the Allocation tab. In Assign New Allocations:

  • IP Address: the address you got, never 127.0.0.1
  • IP Alias: optional, for example node1.your-domain.com
  • Ports: a port or a range, for example 27015-27020

Each game server needs at least one allocation. Wings publishes each one over TCP and UDP.

Step 14: Create a First Server

The panel provides eggs for Minecraft, Rust, Source games and voice servers. To test with Garry's Mod:

  1. Create a GSLT token as described in Create a Garry's Mod Server
  2. Open Servers, then Create New
  3. Enter the name, owner, node and a free allocation
  4. Set the memory, disk and CPU limits
  5. Select the Source Engine nest and the Garrys Mod egg
  6. Fill in Steam Account Token with your token, then confirm

The installation downloads the Docker image and the game files. Then open the server in the interface and click Start. It is ready when the console switches to the online state.

Verifying the Installation

Check Expected result
systemctl is-active nginx php8.3-fpm mariadb redis-server pteroq wings docker active for each service
https://panel.your-domain.com Login page with a valid certificate
Nodes Green heart on the node
A server's console Logs displayed live
SFTP on port 2022 Access to the server's files
Connecting to the game The server responds on its allocation

Backing Up

Back up before each update, and keep a copy outside the server:

Terminal
install -d -m 700 /root/pterodactyl-backups
DATE=$(date +%F_%H-%M)
mariadb-dump --single-transaction panel | gzip > /root/pterodactyl-backups/panel_$DATE.sql.gz
tar -czf /root/pterodactyl-backups/files_$DATE.tar.gz -C / var/www/pterodactyl etc/pterodactyl etc/nginx/sites-available/pterodactyl.conf
ls -lh /root/pterodactyl-backups

These archives contain secrets, including APP_KEY and the Wings token. Game data is stored separately, in /var/lib/pterodactyl/volumes, and backups created from the panel in /var/lib/pterodactyl/backups. Stop a game server before copying its files to get a consistent copy.

Updating

The Panel

Back up first, then replace v1.15.2 with the latest 1.x version. Do not use these steps to move to 2.0, nor php artisan p:upgrade without specifying a version: the upgrade to 2.0 has its own procedure.

Terminal
cd /var/www/pterodactyl
php artisan down
curl -L https://github.com/pterodactyl/panel/releases/download/v1.15.2/panel.tar.gz | tar -xzv
chmod -R 755 storage/* bootstrap/cache
COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader
php artisan view:clear
php artisan config:clear
php artisan migrate --seed --force
chown -R www-data:www-data /var/www/pterodactyl/*
php artisan queue:restart
php artisan up

Wings

Running game servers are not affected. Replace v1.13.5 with the version you want:

Terminal
cp -p /usr/local/bin/wings /usr/local/bin/wings.bak
systemctl stop wings
curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/download/v1.13.5/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
chmod u+x /usr/local/bin/wings
systemctl restart wings

Rolling Back

Restore the Panel

Replace DATE with the timestamp of your archives. These commands first check both archives, then replace the files and the database. Changes made since the backup are lost.

Terminal
tar -tzf /root/pterodactyl-backups/files_DATE.tar.gz > /dev/null
gunzip -t /root/pterodactyl-backups/panel_DATE.sql.gz
cd /var/www/pterodactyl
php artisan down
cd /
rm -rf /var/www/pterodactyl
tar -xzf /root/pterodactyl-backups/files_DATE.tar.gz -C / var/www/pterodactyl
mariadb -e 'DROP DATABASE panel; CREATE DATABASE panel;'
gunzip -c /root/pterodactyl-backups/panel_DATE.sql.gz | mariadb panel
cd /var/www/pterodactyl
php artisan config:clear
php artisan view:clear
php artisan queue:restart
php artisan up

Always restore the .env file together with the database, because it contains APP_KEY. The archive above includes it.

Restore Wings

Terminal
systemctl stop wings
cp -p /usr/local/bin/wings.bak /usr/local/bin/wings
systemctl start wings

Troubleshooting

Reading the Logs

Terminal
tail -n 100 /var/www/pterodactyl/storage/logs/laravel-$(date +%F).log
journalctl -u wings -n 100 --no-pager
journalctl -u pteroq -n 50 --no-pager
tail -n 50 /var/log/nginx/pterodactyl.app-error.log

The Node Stays Red or the Console Shows a Connection Error

  • Check Wings with systemctl status wings, then stop it and run wings --debug
  • Compare /etc/pterodactyl/config.yml with the node's Configuration tab
  • Check that ports 8080 and 2022 are open
  • Test curl https://node1.your-domain.com:8080
  • Check that the panel and Wings both use HTTPS, with valid certificates
  • Disable ad blockers for these domains
  • If you use Cloudflare, disable the proxy on these DNS records

nginx: [emerg] cannot load certificate

The indicated certificate does not exist or the domain does not match. List the available ones with certbot certificates.

the "listen ... http2" directive is deprecated

This is only a warning from recent Nginx versions, with no effect on operation.

502 Bad Gateway

PHP-FPM is not responding. Check systemctl status php8.3-fpm and the /run/php/php8.3-fpm.sock path.

failed to open stream: Permission denied

The panel's files do not belong to the right user:

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

SQLSTATE[HY000] [1045] Access denied for user 'pterodactyl'

The password or host does not match. Use 127.0.0.1 as the host and run php artisan p:environment:database again.

The MAC is invalid

The APP_KEY in the .env file does not match the one used to encrypt the data. Restore the original key. Without it, this data cannot be recovered.

bind: address already in use When Starting Wings

Another service is using the port. Identify it with ss -ltnp | grep -E ':8080|:2022'.

A Game Server Has No Internet Access

Containers use the DNS servers 1.1.1.1 and 1.0.0.1 by default. If these addresses are blocked on your network, replace them in the docker section of /etc/pterodactyl/config.yml, then restart Wings.

Scheduled Tasks Don't Run

Check the crontab line with crontab -l, then the service with journalctl -xeu pteroq and systemctl restart pteroq.

Official Resources