maxhoesel.pterodactyl.pterodactyl_panel

Install and initialize a pterodactyl panel instance in line with the official install instructions.

What this role does for you:

• Install a webserver (Apache or Nginx) with the distribution-provided PHP runtime
• Install redis for a in-memory cache
• Optionally generate a self-signed certificate or use an existing one
• Install the Pterodactyl Panel using Composer
• Set up an Admin user
• Perform upgrades between panel versions

What you need to provide:

• An SQL Database - you can use another role for this
• (Optional) A valid TLS certificate using something like Let's Encrypt

What this role won't do:

• Set up a HTTP-only panel. If you are running a public Panel you should always use TLS with a valid certificate. If you are running behind a reverse proxy or in a private network, you can use the selfsign SSL mode
• Configure Nodes or Game Servers
• Use non-distro PHP versions

Supported Distributions and Panel Versions

This role supports the Pterodactyl 1.x series of releases. We officially support the following distributions and releases:

Distribution	PHP Version	Supported Panel Release	Note
Ubuntu 24.04 LTS	8.3	latest
Ubuntu 22.04 LTS	8.1	<=1.11.9	last to support PHP 8.1
Debian 13	8.4	latest
Debian 12	8.2	latest
Debian 11	7.4	<=1.10.x	1.10 releases are the last to support PHP 7

Other versions are supported on a best-effort basis.

Requirements

• You need to supply your own MariaDB/MySQL database. See the role vars below for available parameters
• This role requires root access. Make sure it is run with become: true or equivalent

Role Variables

General

pterodactyl_panel_version

• Version of the panel to install
• Can be a specific tag (e.g. v1.3.2) or latest
• Note that the panel will automatically update itself if set to latest
• Default: latest

Webserver

pterodactyl_panel_webserver

• Which webserver to install the panel with.
• Options are apache2 and nginx.
• Default: apache2

pterodactyl_panel_webroot

• Path in which the panel should be installed
• Default: /var/www/pterodactyl

pterodactyl_panel_domain

• Domain for which Apache2 should respond to queries
• Default: {{ ansible_fqdn }}

pterodactyl_panel_ssl_mode

• Determines how the role should handle the TLS certificates for the panel
• If set to selfsign, the role creates a self-signed certificate and uses it for the Panel. You can use this for testing or behind a reverse proxy For production deployments, please use a service like Lets Encrypt to generate a valid certificate.
• If set to unmanaged, the role does not manage certificates - it just loads an existing server certificate from pterodactyl_panel_ssl_<cert/key>. You are responsible for providing such a certificate before running the role (for example via Lets Encrypt)
• Default: unmanaged

pterodactyl_panel_ssl_cert

• Certificate file for the apache2 webserver
• The behavior depends on pterodactyl_panel_ssl_mode:
  • If unmanaged: This is the certificate read by the role. The file must already be present on the remote host and be readable by www-data.
  • If selfsign: This is the path where the self-signed certificate will be stored by this role. The directory must already exist.
• Default (depends on pterodactyl_panel_ssl_mode):
  • If unmanaged: "/etc/letsencrypt/live/{{ pterodactyl_panel_domain }}/fullchain.pem" (the Let's Encrypt directory)
  • If selfsign: /etc/ssl/panel-selfsign.crt

pterodactyl_panel_ssl_key

• Key file for the apache2 webserver
• The behavior depends on pterodactyl_panel_ssl_mode:
  • If unmanaged: This is the key file read by the role. The file must already be present on the remote host and be readable by www-data.
  • If selfsign: This is the path where the self-signed key will be stored by this role. The directory must already exist.
• Default (depends on pterodactyl_panel_ssl_mode):
  • If unmanaged: "/etc/letsencrypt/live/{{ pterodactyl_panel_domain }}/privkey.pem" (the Let's Encrypt directory)
  • If selfsign: /etc/ssl/panel-selfsign.key

pterodactyl_panel_upload_limit

• Maximum allowed upload file size for the panel
• Default: 100M

Panel Settings

Prefix for all variables: pterodactyl_panel_

Name	Description	Required	Default
app_key	base64 encoded app key for the panel, as generated by php artisan key:generate. You can generate a key with this command: echo "base64:$(openssl rand -base64 32)"	X	undefined
hashids_salt	Salt for generating hash ids. 20-digit alphanumeric string. You can generate a salt with this command: tr -dc A-Za-z0-9 </dev/urandom | head -c 20 ; echo	X	undefined
timezone	Timezone for the panel installation		America/New_York
locale	Locale of the panel installation		en
egg_author	Email that should appear in egg exports		"no-reply@{{ pterodactyl_panel_domain }}"
url	URL under which the panel is reachable. If you're behind a reverse proxy, set this to the externally visible URL		"https://{{ ansible_fqdn }}"
theme	App theme		pterodactyl
clear_tasklog	N/A		720
delete_minutes	N/A		10

Database

Prefix for all options: pterodactyl_panel_db_

Name	Description	Required	Default
host	Hostname of the DB server		"127.0.0.1"
port	Port of the DB host		3306
name	Name of the panel database		panel
user	Username to connect as		pterodactyl
password	Password for the user	X	undefined

Mail

Prefix for all options: pterodactyl_panel_mail_

Name	Description	Required	Default
host	Hostname of the mail server		"127.0.0.1"
port	Port of the mail server		25
user	Username to connect as		""
password	Password for the user		""
encryption	Type of encryption to use. Can be "tls", "ssl" or "" for no encryption.		""
from	Address to send mails from		"no-reply@{{ ansible_fqdn }}"
from_name	Display name of the sender		Pterodactyl Panel

Admin User

Prefix for all options: pterodactyl_panel_admin_

Name	Description	Required	Default
mail	Email address of the admin user		"admin@{{ ansible_fqdn }}"
user	Username for the admin		admin
password	Password for the admin user		admin
firstname	First name of the admin user		Admin
lastname	Last name of the admin user		Admin

Backups

pterodactyl_panel_backup_configure

• Whether to configure the backup settings in the .env server settings file
• If disabled, the default panel configuration for backups (local backups on the wings nodes) will be used
• Default: false

pterodactyl_panel_backup_driver

• Only has an effect if pterodactyl_panel_backup_configure is set to true
• Choice of backup driver for the pterodactyl panel
• Choices are:
  • wings (the default if pterodactyl_panel_backup_configure is false)
  • s3 for S3 backup storage
• Default: s3

S3 Storage

The following variables are available for configuring the S3 backup driver. Adjust them as needed.

Prefix: pterodactyl_panel_aws_

Name	Description	Default
endpoint	S3 Endpoint	""
default_region	S3 region such as us-east-1	""
access_key_id	ID of your access key	""
secret_access_key	The secret belonging to your access key	""
backups_bucket	Name of the bucket to store the backups in	""
use_path_style_endpoint	Use domain.com/bucket-style endpoints instead of the default bucket.domain.com	false

Other

pterodactyl_panel_environment_only

• If set to false, allow admins to change .env file settings from the admin UI.
• Please note that changing settings this way is NOT supported by this role and may cause issues.
• It is recommended that you leave this setting on true unless you know what you are doing
• Default: true

pterodactyl_panel_extra_env

• Optionally pass additional options to the env file
• You can use this to set values not covered above, such as reCAPTCHA settings
• Expects a string dictionary with the key as the variable name
• Example:

  pterodactyl_panel_extra_env:
    APP_NAME: "Custom Panel"
    APP_2FA_REQUIRED: true
  

• Default: {}

Example Playbooks

See the main README for a more detailed example.

# Please make sure that your keys are provided by a secure mechanism,
# such as ansible-vault or via vars-prompt
- hosts: panel
  become: true
  tasks:
    - name: Install Pterodactyl Panel
      include_role:
        name: maxhoesel.pterodactyl.pterodactyl_panel
      # pterodactyl_panel supports additional options, see it's README for more details.
      vars:
        pterodactyl_panel_app_key: #your-app-key-here
        pterodactyl_panel_hashids_salt: #your-salt-here
        # The timezone in which the panel should operate
        pterodactyl_panel_timezone: Europe/Berlin
        # DB settings. Make sure that the database + user already exist and are accessible
        pterodactyl_panel_db_host: "127.0.0.1"
        pterodactyl_panel_db_name: panel
        pterodactyl_panel_db_user: pterodactyl
        pterodactyl_panel_db_password: users-db-password-here
        # Mail server settings.
        pterodactyl_panel_mail_host: smtp.gmail.com
        pterodactyl_panel_mail_user: your-address@gmail.com
        pterodactyl_panel_mail_password: your-mail-password
        pterodactyl_panel_mail_encryption: tls
        # By default, the role will create a user with the credentials admin/admin.
        # You can change these values below or in the UI once the panel is up and running
        pterodactyl_panel_admin_mail: "your-address@gmail.com"
        #pterodactyl_panel_admin_user: admin
        #pterodactyl_panel_admin_password: admin