How to install Pterodactyl panel on Debian/Ubuntu

Pterodactyl panel is a feature-rich server management panel usually used for game servers. It allows you to easily create new servers, manage them and more. And the best part is that it’s completely open source!
Pterodactyl uses docker containers for the servers, so you don’t have to worry about dependencies and incompatibilities between your host system and docker (if it is supported. We will get to that later).
The installation and setup for it can be a little confusing, but not to worry! This guide will teach you all about it and some common problems you might encounter.
This guide will use Ubuntu 24.04, but the process is mostly the same for others.
This guide is based on the official setup guide for Pterodactyl. All credits go to them.

The requirements for using the panel is as follows:

• At least Ubuntu 20.04 or at least Debian 11. It also works with RHEL / Rocky Linux / AlmaLinux, but this guide only covers Debian and Ubuntu based distros.
• PHP 8.2 or 8.3 (recommended) with the following extensions: cli, openssl, gd, mysql, PDO, mbstring, tokenizer, bcmath, xml or dom, curl, zip, and fpm if you are planning to use NGINX.
• MySQL 5.7.22 and higher (MySQL 8 recommended) or MariaDB 10.2 and higher.
• Redis (redis-server) (automatically installed during panel setup)
• A webserver (Apache, NGINX, Caddy, etc.). This guide will use NGINX, but you can use whichever you prefer
• curl, tar, unzip, git, composer (v2) commands
• FQDN that you will use to access the panel and use SSL

You can install most of these extensions using the following commands:

# Add "add-apt-repository" command
sudo apt -y install software-properties-common curl apt-transport-https ca-certificates gnupg

# Add additional repositories for PHP (Ubuntu 20.04 and Ubuntu 22.04)
LC_ALL=C.UTF-8 add-apt-repository -y ppa:ondrej/php

# Add Redis official APT repository
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

# MariaDB repo setup script (Ubuntu 20.04)
curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | sudo bash

# Update repositories list
sudo apt update

# Install Dependencies
sudo apt -y install php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx tar unzip git redis-server

Installing Composer

Pterodactyl uses Composer to deal with PHP dependencies. This means you need it in order to install the panel. You can do so with the following command:

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

Downloading the panel

First off, you need to create a folder where the panel will exist. We then move our current directory with cd to work in that directory.

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

Next, we need to download the panel files itself. We are going to use curl for this. We will then need to unpack the archives and give permissions to some folders, so pterodactyl can keep a speedy cache.

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

Installing the panel

Now that we have all of the files, let’s configure some core aspects. First off, we need to setup a database. You can easily create it using the following commands:

# If using MariaDB (v11.0.0+) (This is the default when installing Pterodactyl by following this guide.)
mariadb -u root -p

# If using MySQL
mysql -u root -p

# Remember to change 'yourPassword' below to be a unique password
CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'yourPassword';
CREATE DATABASE panel;
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1' WITH GRANT OPTION;
exit

You can see a more advanced guide with more details by going to this link to the official pterodactyl docs: https://pterodactyl.io/tutorials/mysql_setup.html

Next up, lets copy over over the default config file, install the dependencies and generate a new encryption key.

cp .env.example .env
COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader

# Only run the command below if you are installing this Panel for
# the first time and do not have any Pterodactyl Panel data in the database.
php artisan key:generate --force

Enviroment configuration

Pterodactyl’s core environment is easily configured using a few different CLI commands built into the app. This step will cover setting up things such as sessions, caching, database credentials, and email sending.

php artisan p:environment:setup
php artisan p:environment:database

# Optional. Only use if you plan to send emails
# To use PHP's internal mail sending (not recommended), select "mail". To use a
# custom SMTP server, select "smtp".
php artisan p:environment:mail

Database setup

Now we need to setup all of the base data for the Panel in the database you created earlier. The command below may take some time to run depending on your machine. Please DO NOT exit the process until it is completed! This command will setup the database tables and then add all of the Nests & Eggs that power Pterodactyl.

php artisan migrate --seed --force

Add the first user

You’ll then need to create an administrative user so that you can log into the panel. To do so, run the command below. At this time passwords must meet the following requirements: 8 characters, mixed case, at least one number.

php artisan p:user:make

Set up permissions

The last step is to set up permissions for the webserver so it can use the panel’s files.

# If using NGINX, Apache or Caddy (not on RHEL / Rocky Linux / AlmaLinux)
chown -R www-data:www-data /var/www/pterodactyl/*

# If using NGINX on RHEL / Rocky Linux / AlmaLinux
chown -R nginx:nginx /var/www/pterodactyl/*

# If using Apache on RHEL / Rocky Linux / AlmaLinux
chown -R apache:apache /var/www/pterodactyl/*

After this step, you are done installing the panel! However, you still need to enable it. Follow the next steps:

Queue listeners

Crontab Configuration

The first thing we need to do is create a new cronjob that runs every minute to process specific Pterodactyl tasks, such as session cleanup and sending scheduled tasks to daemons. You’ll want to open your crontab using sudo crontab -e and then paste the line below.

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

Create Queue Worker

Next you need to create a new systemd worker to keep our queue process running in the background. This queue is responsible for sending emails and handling many other background tasks for Pterodactyl.

Create a file called pteroq.service in /etc/systemd/system with the contents below.

# Pterodactyl Queue Worker File
# ----------------------------------

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

[Service]
# On some systems the user and group might be different.
# Some systems use `apache` or `nginx` as the user and group.
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

If you are using redis for your system, you will want to make sure to enable that it will start on boot. You can do that by running the following command:

sudo systemctl enable --now redis-server

Finally, enable the service and set it to boot on machine start.

sudo systemctl enable --now pteroq.service

Webserver setup

You need to set up a webserver to access the panel. That part is out of focus for this guide, and we recommend following the official webserver set up guide for the panel.

Wings

Pterodactyl uses the panel to provide a front-end for you to manage your servers. This panel connects to a back-end service called Wings, which manages your servers using Docker. This section will teach you how to install Wings

Installing Docker

Wings relies on Docker for it’s servers. If you already have docker installed on your system, you can skip this step.

You can quickly install docker using this command:

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

Then make docker start up by default:

sudo systemctl enable --now docker

If you want to enable swap on Wings, you will need to configure some options on Docker. This guide will not cover this part, however you can find an easy guide on the official Wings installation guide

Installing Wings

First step is to create the necessary folders and download Wings. Run the following commands:

sudo 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")"
sudo chmod u+x /usr/local/bin/wings

Configuring

Once you have installed Wings and the required components, the next step is to create a node on your installed Panel. Go to your Panel administrative view, select Nodes from the sidebar, and on the right side click Create New button.

After you have created a node, click on it and there will be a tab called Configuration. Copy the code block content, paste it into a new file called config.yml in /etc/pterodactyl and save it.

Alternatively, you can click on the Generate Token button, copy the bash command and paste it into your terminal.

Starting wings

To start Wings, simply run the command below, which will start it in a debug mode. Once you confirmed that it is running without errors, use CTRL+C to terminate the process and daemonize it by following the instructions below. Depending on your server’s internet connection pulling and starting Wings for the first time may take a few minutes.

sudo wings --debug

You may optionally add the --debug flag to run Wings in debug mode.

Daemonizing (using systemd)

Running Wings in the background is a simple task, just make sure that it runs without errors before doing this. Place the contents below in a file called wings.service in the /etc/systemd/system directory.

[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

Then, run the commands below to reload systemd and start Wings.

sudo systemctl enable --now wings

Node Allocations

Allocation is a combination of IP and Port that you can assign to a server. Each created server must have at least one allocation. The allocation would be the IP address of your network interface. In some cases, such as when behind NAT, it would be the internal IP. To create new allocations go to Nodes > your node > Allocation.

Type hostname -I | awk '{print $1}' to find the IP to be used for the allocation. Alternatively, you can type ip addr | grep "inet " to see all your available interfaces and IP addresses. Do not use 127.0.0.1 for allocations.

Congratulations! If you made it this far without errors, that means you have successfully installed the panel and are ready to start creating servers. The official guide has some extra pages that can help you configure both panel and Wings to get the most out of them, but they are more edge-case scenarios. Good luck on your journey!