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.
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
rootaccess or asudouser- Two subdomains pointing to the server, with a DNS
Arecord:panel.your-domain.comandnode1.your-domain.com - Virtualization compatible with Docker
Check the virtualization type and the DNS:
systemd-detect-virt
getent hosts panel.your-domain.com node1.your-domain.comKVM 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:
sudo -iPorts 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:
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 8080/tcp
ufw allow 2022/tcp
ufw enable
ufw statusWith 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
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-serverDebian 12
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-serverUbuntu 24.04
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-serverUbuntu 22.04
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-serverComposer and Verification
On all systems, install Composer, enable Redis and check the versions:
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 pingphp -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:
openssl rand -base64 24Open MariaDB. If a password is requested and you have not set one, press Enter.
mariadb -u root -pCREATE 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;
exitStep 4: Download the Panel
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:
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/.envThen run the configuration wizards:
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.
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:
crontab -eAdd this line:
* * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1Create the queue service:
nano /etc/systemd/system/pteroq.service# 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.targetEnable it and check its status:
systemctl daemon-reload
systemctl enable --now pteroq.service
systemctl is-active pteroq.serviceThe 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.
apt install -y certbot python3-certbot-nginx
certbot certonly --nginx -d panel.your-domain.com
certbot certonly --nginx -d node1.your-domain.comCreate a script to apply renewed certificates to Nginx and Wings:
nano /etc/letsencrypt/renewal-hooks/deploy/pterodactyl.sh#!/bin/bash
systemctl reload nginx
systemctl try-restart wingschmod 750 /etc/letsencrypt/renewal-hooks/deploy/pterodactyl.sh
certbot renew --dry-runRestarting 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:
rm /etc/nginx/sites-enabled/default
nano /etc/nginx/sites-available/pterodactyl.confserver {
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:
ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/pterodactyl.conf
nginx -t
systemctl restart nginxOpen 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:
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
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 versionThis 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:
- Open Locations, click Create New and create a location, for example
fr - Open Nodes, then click Create New
- 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.
- After creation, open the node's Configuration tab and copy the block displayed
- Paste it on the server, then protect the file, which contains a secret token:
nano /etc/pterodactyl/config.yml
chmod 600 /etc/pterodactyl/config.ymlThe 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:
wings --debugWhen it runs without errors, stop it with Ctrl+C, then create its service:
nano /etc/systemd/system/wings.service[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.targetsystemctl daemon-reload
systemctl enable --now wings
systemctl is-active wings
curl https://node1.your-domain.com:8080The 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:
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:
- Create a GSLT token as described in Create a Garry's Mod Server
- Open Servers, then Create New
- Enter the name, owner, node and a free allocation
- Set the memory, disk and CPU limits
- Select the Source Engine nest and the Garrys Mod egg
- 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:
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-backupsThese 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.
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 upWings
Running game servers are not affected. Replace v1.13.5 with the version you want:
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 wingsRolling 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.
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 upAlways restore the .env file together with the database, because it contains APP_KEY. The archive above includes it.
Restore Wings
systemctl stop wings
cp -p /usr/local/bin/wings.bak /usr/local/bin/wings
systemctl start wingsTroubleshooting
Reading the Logs
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.logThe Node Stays Red or the Console Shows a Connection Error
- Check Wings with
systemctl status wings, then stop it and runwings --debug - Compare
/etc/pterodactyl/config.ymlwith the node's Configuration tab - Check that ports
8080and2022are 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:
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.