Deployment Overview of Pterodactyl Panel on Server¶

Prerequisites and Basic Requirements¶

The deployment requires a server running Ubuntu 22.04 (Jammy) with root privileges. The following components must be available on the system:

• Operating System: Ubuntu 22.04 (Jammy)

• Privileges: Root access or sudo privileges

• Domain: A valid domain name configured to point to the server IP

• Ports:

  • Port 80 and 443 for web traffic (HTTP/HTTPS)

  • Port 3306 for MariaDB (local only)

  • Port 6379 for Redis (local only)

  • Port 12333 for Wings proxy (external)

  • Port 8000 for Wings internal API

FQDN of the Final Panel¶

The Fully Qualified Domain Name (FQDN) for the Pterodactyl Panel follows the format:

pterodactyl<Server ID>.hostkey.in

The panel is accessible via HTTPS on the standard port 443. The Wings proxy component listens on port 12333 for the same domain.

File and Directory Structure¶

The application files, configuration, and data are organized in the following locations:

• Application Root: /var/www/pterodactyl

• Public Directory: /var/www/pterodactyl/public

• Storage Directory: /var/www/pterodactyl/storage

• Bootstrap Cache: /var/www/pterodactyl/bootstrap/cache

• Nginx Configuration: /etc/nginx/sites-available/pterodactyl.conf

• Docker Compose Configuration: /root/nginx/compose.yml

• Systemd Service Files:

  • /etc/systemd/system/pteroq.service

• Cron Job: /etc/cron.d/pterodactyl

• SSL Certificates: Managed by Certbot within the Docker container, stored in /etc/letsencrypt (mapped volume)

Application Installation Process¶

The Pterodactyl Panel is installed manually on the host system using the latest release archive. The installation process involves the following steps:

1. System Preparation:

   • Update the package cache.

   • Install dependencies including software-properties-common, curl, git, unzip, cron, and ca-certificates.

   • Add the Ondrej PPA for PHP and the official Redis repository.

2. Core Services Installation:

   • Install nginx, mariadb-server, redis-server, and php8.2 with required extensions (cli, fpm, mbstring, xml, mysql, bcmath, zip).

   • Enable and start php8.2-fpm, mariadb, redis-server, nginx, and cron.

3. Composer Installation:

   • Install Composer v2 globally to /usr/local/bin/composer.

4. Panel Deployment:

   • Create the installation directory /var/www/pterodactyl.

   • Download the latest panel.tar.gz from the official GitHub releases.

   • Extract the archive into /var/www/pterodactyl.

   • Create required directories (storage, bootstrap, bootstrap/cache) with www-data ownership.

5. Configuration:

   • Copy .env.example to .env.

   • Install Composer dependencies with composer install --no-dev --optimize-autoloader.

   • Generate the application key using php artisan key:generate.

   • Configure the database connection using php artisan p:environment:database.

   • Run database migrations and seed the database using php artisan migrate --seed --force.

   • Create the initial administrator user using php artisan p:user:make.

6. Service Configuration:

   • Set ownership of the entire installation directory to www-data.

   • Install the scheduler cron job.

   • Install and enable the pteroq systemd service for queue processing.

Access Rights and Security¶

Security is enforced through service isolation, firewall rules (implied by port configuration), and file permissions.

• Web Server User: All application files are owned by www-data.

• Database Access: The MariaDB service is configured to accept connections from root with a specific password. The application connects as root to the panel database.

• Queue Worker: The pteroq service runs as the www-data user.

• SSL/TLS: SSL is enabled using Let's Encrypt certificates. The Nginx configuration enforces TLSv1.2 and TLSv1.3 with strong cipher suites.

• HTTPoxy Protection: The Nginx configuration explicitly sets fastcgi_param HTTP_PROXY "" to prevent HTTPoxy attacks.

Databases¶

The application uses a local MariaDB instance for data storage.

• Database Name: panel

• Database User: root

• Database Password: Configured via the system password variable

• Host: 127.0.0.1

• Port: 3306

• Connection Method: The application connects via TCP to the local MariaDB socket.

Docker Containers and Their Deployment¶

A Docker container is used specifically for the Nginx reverse proxy and SSL certificate management.

• Container Image: jonasal/nginx-certbot:latest

• Deployment Method: Docker Compose

• Compose File Location: /root/nginx/compose.yml

• Network Mode: host

• Volumes:

  • nginx_secrets (external) mapped to /etc/letsencrypt

  • /data/nginx/user_conf.d mapped to /etc/nginx/user_conf.d

  • /var/www/pterodactyl/public mapped to /var/www/pterodactyl/public (read-only)

• Environment:

  • CERTBOT_EMAIL: [email protected]

  • env_file: /data/nginx/nginx-certbot.env

Proxy Servers¶

The deployment utilizes Nginx as a reverse proxy for both the Panel and the Wings daemon.

• Panel Proxy:

  • Managed by the host Nginx service (/etc/nginx/sites-available/pterodactyl.conf).

  • Listens on port 80 and redirects to HTTPS.

  • Listens on port 443 with SSL.

  • Proxies PHP requests to 127.0.0.1:9000 (PHP-FPM).

  • Serves static files from /var/www/pterodactyl/public.

• Wings Proxy:

  • Managed by the Docker container (jonasal/nginx-certbot).

  • Listens on port 12333 with SSL.

  • Proxies traffic to http://host.docker.internal:8000.

  • Supports WebSocket upgrades for real-time communication.

  • Uses SSL certificates located at /etc/letsencrypt/live/pterodactyl<Server ID>.hostkey.in/.

• SSL Management:

  • Certbot is used to obtain and renew Let's Encrypt certificates.

  • Certificates are stored in /etc/letsencrypt via a Docker volume.

Permission Settings¶

File and directory permissions are strictly set to ensure the web server can read and execute the application while preventing unauthorized modification.

• Root Directory: /var/www/pterodactyl is owned by www-data:www-data with mode 0755.

• Recursive Ownership: All subdirectories and files within the installation directory are recursively owned by www-data.

• Specific Directories:

  • storage, bootstrap, and bootstrap/cache are explicitly set to 0755 with www-data ownership.

• Configuration Files:

  • Nginx configuration files are set to 0644.

  • Docker Compose files are set to 0644.

  • Systemd service files are set to 0644.

Location of Configuration Files and Data¶

Key configuration files and data locations are as follows:

Available Ports for Connection¶

The following ports are configured for external and internal access:

• Port 80: HTTP traffic (redirects to HTTPS)

• Port 443: HTTPS traffic for the Pterodactyl Panel

• Port 12333: HTTPS traffic for the Wings proxy (game server management)

• Port 3306: MariaDB (Localhost only)

• Port 6379: Redis (Localhost only)

• Port 8000: Wings internal API (Localhost only, proxied via 12333)

Starting, Stopping, and Updating¶

Services are managed using systemd and docker compose.

• Panel Services:

  • Start/Stop/Restart Nginx: systemctl restart nginx

  • Start/Stop/Restart PHP-FPM: systemctl restart php8.2-fpm

  • Start/Stop/Restart MariaDB: systemctl restart mariadb

  • Start/Stop/Restart Redis: systemctl restart redis-server

  • Start/Stop/Restart Queue Worker: systemctl restart pteroq

• Proxy Container:

  • Start/Stop/Restart: docker compose up -d (executed from /root/nginx)

• Application Updates:

  • Clear configuration cache: php artisan config:clear

  • Cache configuration: php artisan config:cache

  • Clear routes: php artisan route:clear

  • Clear views: php artisan view:clear

  • Run migrations: php artisan migrate --force