Skip to content

Deployment Overview of Pterodactyl Control Panel on Server

Prerequisites and Basic Requirements

The deployment of the Pterodactyl Control Panel requires a server running Ubuntu 22.04 (Jammy). The system must have root privileges to install dependencies, configure services, and manage file permissions. The following components are required:

  • Operating System: Ubuntu 22.04 (Jammy)

  • Privileges: Root access

  • Domain: A subdomain under the hostkey.in zone

  • Ports:

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

  • Port 8000 for internal application communication

  • Port 12333 for external Wings proxy access

  • Port 3306 for MariaDB

  • Port 6379 for Redis

FQDN of the Final Panel

The Fully Qualified Domain Name (FQDN) for the Pterodactyl panel follows the format: pterodactyl<Server ID>.hostkey.in

The application is accessible via HTTPS on port 443 and via the Wings proxy on port 12333.

File and Directory Structure

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

  • Application Root: /var/www/pterodactyl

  • Public Assets: /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

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

  • SSL Certificates: /etc/letsencrypt/live/pterodactyl<Server ID>.hostkey.in

  • Systemd Services: /etc/systemd/system/pteroq.service

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

Application Installation Process

The Pterodactyl Panel is installed using the latest release archive from the official repository. The installation process involves the following steps:

  1. System Preparation: Update the package cache and install required dependencies including nginx, mariadb-server, redis-server, php8.2, and composer.

  2. Repository Configuration: Add the Ondrej PHP PPA and the official Redis repository to ensure the correct versions of PHP and Redis are installed.

  3. Service Activation: Enable and start php8.2-fpm, mariadb, redis-server, nginx, and cron.

  4. Application Deployment:

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

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

    • Create necessary directories (storage, bootstrap, bootstrap/cache) and set ownership to www-data.

  5. Dependency Installation: Run composer install to install PHP dependencies.

  6. Database Initialization:

    • Configure MariaDB to set the root password.

    • Create the panel database.

    • Run database migrations and seed the initial data.

  7. User Creation: Create the first administrative user with the email, username, and password defined in the configuration.

  8. Queue Worker Setup: Install and enable the pteroq systemd service to handle background jobs.

  9. Scheduler Setup: Configure a cron job to run the Laravel scheduler every minute.

Access Rights and Security

Security is enforced through service isolation, firewall rules, and strict file permissions.

  • Firewall: The server allows traffic on ports 80, 443, 8000, 12333, 3306, and 6379.

  • Users:

  • The web server and application files are owned by the www-data user and group.

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

  • The root user manages system-level configurations and cron jobs.

  • Restrictions:

  • Access to hidden files (starting with .) is denied in the Nginx configuration.

  • The HTTP_PROXY environment variable is cleared in the PHP-FPM configuration to prevent HTTPoxy attacks.

  • SSL is enforced for all web traffic.

Databases

The application uses a local MariaDB instance for data storage.

  • Connection Method: Localhost TCP connection.

  • Storage Location: Managed by the mariadb service on the host.

  • Configuration:

  • Database Name: panel

  • Host: 127.0.0.1

  • Port: 3306

  • Username: root

  • Password: Defined in the system configuration.

Redis is used for caching and queue management.

  • Host: 127.0.0.1

  • Port: 6379

  • Password: Not set (null).

Docker Containers and Their Deployment

A Docker container is used to manage the Nginx proxy and SSL certificates via Certbot.

  • Container Image: jonasal/nginx-certbot:latest

  • Deployment Method: Docker Compose

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

  • Volumes:

  • nginx_secrets: Mounted to /etc/letsencrypt for certificate storage.

  • /data/nginx/user_conf.d: Mounted to /etc/nginx/user_conf.d for custom configurations.

  • /var/www/pterodactyl/public: Mounted read-only to /var/www/pterodactyl/public.

  • Network Mode: Host

  • Restart Policy: unless-stopped

Proxy Servers

The deployment utilizes Nginx as a reverse proxy with SSL termination.

  • Nginx Configuration:

  • A dedicated site configuration is located at /etc/nginx/sites-available/pterodactyl.conf.

  • HTTP traffic on port 80 is redirected to HTTPS.

  • PHP requests are proxied to the local PHP-FPM socket at unix:/run/php/php8.2-fpm.sock.

  • SSL/TLS:

  • Certificates are obtained and managed by Certbot via the Docker container.

  • SSL is enabled for the domain pterodactyl<Server ID>.hostkey.in.

  • TLS protocols TLSv1.2 and TLSv1.3 are enforced.

  • Wings Proxy:

  • A separate Nginx configuration handles the Wings daemon traffic on port 12333.

  • This configuration proxies requests to http://host.docker.internal:8000.

  • WebSocket support is enabled with upgrade headers.

Permission Settings

File and directory permissions are strictly set to ensure security and proper functionality:

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

  • Storage and Cache: Subdirectories storage, bootstrap, and bootstrap/cache are owned by www-data:www-data with mode 0755.

  • Nginx Configuration: Files in /etc/nginx/sites-available and /etc/nginx/sites-enabled are owned by root:root with mode 0644.

  • Docker Compose: The compose file at /root/nginx/compose.yml is owned by root:root with mode 0644.

Location of Configuration Files and Data

Key configuration files and data locations include:

  • Environment File: /var/www/pterodactyl/.env

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

  • Wings Proxy Config: Defined within the Docker container or host Nginx configuration for port 12333.

  • Systemd Service: /etc/systemd/system/pteroq.service

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

  • Initialization Marker: /var/www/pterodactyl/.ansible_ptero_initialized

Available Ports for Connection

The following ports are configured for external and internal access:

  • Port 80: HTTP (redirects to HTTPS).

  • Port 443: HTTPS (Pterodactyl Panel).

  • Port 12333: HTTPS (Wings Proxy).

  • Port 8000: Internal application port (proxied).

  • Port 3306: MariaDB (local only).

  • Port 6379: Redis (local only).

Starting, Stopping, and Updating

Service management is handled via systemd for native services and docker compose for the proxy container.

Native Services:

  • Start/Stop/Restart Nginx: 

    systemctl restart nginx

  • Start/Stop/Restart MariaDB: 

    systemctl restart mariadb

  • Start/Stop/Restart Redis: 

    systemctl restart redis-server

  • Start/Stop/Restart PHP-FPM: 

    systemctl restart php8.2-fpm

  • Start/Stop/Restart Queue Worker: 

    systemctl restart pteroq

Docker Container:

  • Start/Stop/Restart Nginx-Certbot: 
    cd /root/nginx
docker compose up -d

Application Updates:

  • Clear and cache configuration: 

    cd /var/www/pterodactyl
php artisan config:clear
php artisan config:cache
php artisan route:clear
php artisan view:clear

  • Run migrations (if schema changes): 

    php artisan migrate --force

question_mark
Is there anything I can help you with?
question_mark
AI Assistant ×