maxhoesel.pterodactyl.pterodactyl_wings

Install and initialize the pterodactyl wings daemon

This role follows the official installation instructions on the pterodactyl docs homepage.

Versioning Policy

This role officially supports the latest release of the Pterodactyl 1.x series. Older versions are supported on a best-effort basis.

Requirements

• The following distributions are currently supported:
  • Ubuntu: 22.04 LTS, 24.04 LTS
  • Debian: 11, 12, 13
• This role requires root access. Make sure to run this role with become: yes or equivalent
• Docker is required to run Wings. If docker is not present, this role will install it automatically
• You must have already created a new node in your panel.

Role Variables

General

pterodactyl_wings_version

• Version of wings to install
• Can be a specific tag (e.g. v1.3.2) or latest
• Default: latest

pterodactyl_wings_config_dir

• Directory in which the config file is stored
• Default: /etc/pterodactyl

pterodactyl_wings_start

• Start the wings service at the end of this role
• Default true

Docker

pterodactyl_wings_docker_install

• Whether to handle the docker installation.
• Set to false if you already have a docker install running and don't want this role to touch anything
• Default: true

pterodactyl_wings_docker_source

• Method used to install docker
• If set to distro, the Docker version provided by the distribution will be installed
• If set to stable, the most recent stable version form the official Docker repositories will be installed
• If this value is changed later, the role will automatically switch the installed Docker version. Note that this may cause downtime
• Default: stable

pterodactyl_wings_docker_ipv6

• Whether to enable IPv6 support in docker using docker-ipv6NAT. This allows you to connect to your containers using IPv6, as long as you have a correct allocation in pterodactyl (0.0.0.0 works for me). See this comment for more details.
• WARNING: Enabling IPv6 support using this approach requires a reboot - the role will perform this automatically. This may cause some downtime on the first run.
• Due to the "hacky" nature of this approach, it is disabled by default
• Default: false

pterodactyl_wings_docker_ipv6_cidr

• CIDR range to use for the internal IPv6 ULA addresses
• Has no effect if pterodactyl_wings_docker_ipv6 is disabled
• Default: "fd00::/80"

pterodactyl_wings_docker_ipv6nat_version

• Use the specified ipv6nat container tag
• Default: latest

Wings Configuration

This role can manage your wings config if pterodactyl_wings_config_install is enabled (default).

The pterodactyl_wings_config is a dictionary representing the configuration file of the wings daemon. This configuration will be merged with any existing configuration already present on the node.

To get started, you can adjust the configuration below. To get a more complete configuration file, use the panel to generate one or read it from an existing wings daemon.

NOTE: You must provide your own uuid, token_id and token values. These can be viewed in the node settings in the panel.

NOTE: The TLS certificate for the wings daemon must be present at the supplied path (defaults to Let's Encrypt).

Default configuration:

pterodactyl_wings_config:
  debug: false
  # Secrets generated by the panel for the wings client
  uuid: #your-uuid-here
  token_id: #your-token-id-here
  token: #your-token-here
  api:
    host: 0.0.0.0 # Address to bind the wings daemon to
    port: 8080 # Port to bind the wings daemon to
    # SSL Settings, including certificate path and key. Defaults to the path used by certbot/Let's Encrypt
    ssl:
      enabled: true
      cert: "/etc/letsencrypt/live/{{ ansible_fqdn }}/fullchain.pem"
      key: "/etc/letsencrypt/live/{{ ansible_fqdn }}/privkey.pem"
    upload_limit: 100 # File browser upload limit in MB
  remote: https://127.0.0.1:443 # The address of the Panel
  system:
    data: /var/lib/pterodactyl/volumes # Path under which to save server data
    sftp:
      bind_port: 2022 # Port on which sftp should listen on
  allowed_mounts: []
  # add additional configuration options here, if required

Example Playbooks

# Performs a basic wings installation
# such as ansible-vault or via vars-prompt
- hosts: all
  roles:
    - role: maxhoesel.pterodactyl.pterodactyl_wings
      become: yes
      vars:
        pterodactyl_wings_config:
          debug: false
          uuid: 12544f88-cfbf-40b6-9432-a2bc14312112
          token_id: m9TVwtaw6FQQZt8H
          token: dPigfaWa4I4xcY3o5sM3Hi3ST3duxHqCqu30fc3eO44lPj7msGY6R14YKCR6QZJ2
          api:
            host: 0.0.0.0
            port: 8080
            ssl:
              enabled: true
              cert: "/etc/letsencrypt/live/{{ ansible_fqdn }}/fullchain.pem"
              key: "/etc/letsencrypt/live/{{ ansible_fqdn }}/privkey.pem"
            upload_limit: 100
          remote: https://mypanel.example.com:443
          system:
            data: /var/lib/pterodactyl/volumes
            sftp:
              bind_port: 2022
          allowed_mounts: []