Installer le panel Pterodactyl pour serveurs de jeu

Pterodactyl est l'interface libre la plus répandue pour les serveurs de jeu. Sa réputation de logiciel compliqué ne vient presque jamais de l'installation elle-même, mais d'un seul malentendu : Pterodactyl n'est pas un programme, mais deux. Ce guide sépare proprement les deux rôles, montre les différences entre Debian et Ubuntu, puis passe en revue les messages d'erreur que l'on finit par recopier mot pour mot dans un moteur de recherche.

Panel et Wings : deux programmes, deux rôles

Le Panel est une application PHP basée sur Laravel. Il fournit l'interface web, gère les utilisateurs, les droits, les bases de données et les tâches planifiées, et enregistre le tout dans sa propre base MySQL ou MariaDB. Le Panel ne démarre jamais lui-même un serveur de jeu. Il ne connaît même pas Docker.

Wings est un programme unique, écrit en Go. Il tourne sur chaque machine censée héberger réellement des serveurs de jeu, dialogue avec le démon Docker, démarre les conteneurs (containers), diffuse la console et fournit l'accès SFTP. Wings n'a ni interface web ni base de données. Il écoute sur un port HTTP et attend les instructions du Panel.

Les deux communiquent exclusivement en HTTP, dans les deux sens, avec des tokens signés. Trois conséquences qu'il vaut mieux accepter dès le départ :

• Le Panel doit joindre le nœud par un nom de domaine, pas par une IP. Le certificat est lié au nom.
• Le Panel et Wings doivent parler le même protocole. Un Panel en HTTPS avec un Wings en HTTP ne fonctionne pas : le navigateur bloque la connexion à la console.
• Les deux horloges doivent être justes. Les tokens n'ont qu'une durée de vie de quelques minutes.

Une fois ces trois phrases intégrées, la moitié des problèmes classiques de Pterodactyl sont déjà évités.

Prérequis et choix du système

Pterodactyl 1.11 et les versions plus récentes exigent PHP 8.2 ou 8.3. C'est le point sur lequel la plupart des guides restent flous, car les distributions livrent des versions très différentes. En juillet 2026, voici la situation dans les dépôts standard :

Ce guide s'en tient strictement à Debian et Ubuntu. Sur AlmaLinux, Rocky Linux et Oracle Linux, il n'y a pas d'apt : aucune des commandes de paquets qui suivent n'y est applicable.

Conséquence pratique : Debian 12 et Ubuntu 24.04 sont les deux systèmes sur lesquels le Panel tourne sans dépôt tiers. Sur Ubuntu 22.04, il vous faut le PPA d'Ondřej Surý, sur Debian 13 son équivalent Debian, parce que PHP 8.4 y fournit le métapaquet alors que le composer.json du Panel exige explicitement ^8.2 || ^8.3. Dans les faits, l'exécution de Composer passe bien sous PHP 8.4, mais c'est un terrain non validé et pas un état dans lequel on souhaite exploiter un serveur de production. Pour vous épargner le dépôt supplémentaire, prenez Debian 12 ou Ubuntu 24.04.

Les deux systèmes trop anciens n'échouent d'ailleurs pas sur la commande de paquets, mais seulement deux étapes plus loin, et c'est ce qui les rend traîtres. apt install php se termine avec le code de sortie 0 sur Ubuntu 22.04 (PHP 8.1.2) comme sur Debian 11 (PHP 7.4.33) : c'est l'exécution de Composer qui s'interrompt ensuite, sur Ubuntu 22.04 avec brick/math requires php (^8.2) failed, sur Debian 11 avec aws/aws-sdk-php requires php (>=8.1) failed. Si vous devez rester sur l'un de ces systèmes, installez depuis le dépôt tiers des paquets explicitement versionnés (php8.3, php8.3-cli, php8.3-fpm et ainsi de suite) plutôt que le métapaquet php, sinon c'est de nouveau la version de la distribution qui s'impose.

Deuxième différence qui surprend régulièrement : Debian ne fournit tout simplement aucun paquet mysql-server. MariaDB y est la référence, et cela ne pose aucun problème : Pterodactyl demande MariaDB 10.2 ou plus récent. Si vous tapez apt install mysql-server sous Debian, vous obtenez E: Unable to locate package mysql-server et vous cherchez ensuite au mauvais endroit.

Pour le nœud qui fait tourner Wings, ces règles PHP ne s'appliquent d'ailleurs pas du tout. Wings est un programme Go lié statiquement, il lui faut seulement Docker et un noyau à peu près récent. Le nœud peut sans problème tourner sous Debian 13 pendant que le Panel tourne sous Debian 12.

Installer le Panel

Toutes les commandes qui suivent s'exécutent en root. D'abord les paquets de base. Veillez à prendre les extensions PHP au complet : un php-bcmath manquant ne se remarque qu'au moment de l'exécution de Composer.

apt update
apt -y install curl ca-certificates gnupg lsb-release tar unzip git
apt -y install mariadb-server nginx redis-server
apt -y install php php-cli php-common php-gd php-mysql php-mbstring php-bcmath php-xml php-fpm php-curl php-zip

Vérifiez immédiatement que la version convient, avant d'aller plus loin :

php -v
php -m | grep -E "bcmath|mbstring|curl|zip|gd|xml"

Ensuite Composer et les fichiers du Panel :

curl -sS https://getcomposer.org/installer -o /tmp/composer-setup.php
php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer
mkdir -p /var/www/pterodactyl
curl -Lo /var/www/pterodactyl/panel.tar.gz https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz
tar -xzf /var/www/pterodactyl/panel.tar.gz -C /var/www/pterodactyl

La base de données. Créez l'utilisateur sur 127.0.0.1 et non sur localhost, sinon c'est l'accès par socket qui s'applique et Laravel se heurtera plus tard à un refus d'accès alors même que le mot de passe est correct. Notre article sur Access denied for user explique comment démêler ce cas.

mariadb -u root -e "CREATE DATABASE panel;"
mariadb -u root -e "CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'IciUnMotDePasseLong';"
mariadb -u root -e "GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1' WITH GRANT OPTION;"
mariadb -u root -e "FLUSH PRIVILEGES;"

La base de données doit ensuite être sécurisée : nous y consacrons un article dédié sur la sécurisation de MariaDB et MySQL.

Passons à la configuration proprement dite. Les commandes p:environment sont interactives et demandent l'URL du Panel, le fuseau horaire, le pilote de cache et l'accès à la base de données :

cd /var/www/pterodactyl
cp .env.example .env
COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader
php artisan key:generate --force
php artisan p:environment:setup
php artisan p:environment:database
php artisan migrate --seed --force
php artisan p:user:make
chown -R www-data:www-data /var/www/pterodactyl/*

Dans p:environment:setup, choisissez Redis comme pilote de session et de cache : la file d'attente décrite plus bas fonctionnera alors proprement. Et saisissez l'URL du Panel avec https://. Un http:// à cet endroit produit plus tard du contenu mixte et une console qui attend indéfiniment la connexion.

nginx et le piège des versions

Les grandes lignes de la configuration du serveur web figurent dans notre article sur l'installation de nginx. Pour Pterodactyl, deux détails comptent, et c'est justement là que les modèles tout faits trouvés sur le web échouent régulièrement.

Premièrement, le socket PHP-FPM. Le nom du fichier contient la version de PHP et diffère selon le système. Allez voir au lieu de deviner :

systemctl status php8.2-fpm
ls /run/php/

Sur Debian 12, le socket s'appelle php8.2-fpm.sock, sur Ubuntu 24.04 php8.3-fpm.sock. Un mauvais chemin ici produit exactement la page 502 Bad Gateway que tant de gens cherchent à comprendre. L'interrogation du statut vient délibérément avant : le fichier socket n'apparaît qu'une fois le service FPM démarré. S'il n'est pas lancé, /run/php/ est vide et vous croyez à tort que le chemin est faux. Si le service ne tourne pas encore, systemctl enable --now php8.2-fpm règle la question, avec le numéro de version qui correspond à votre installation.

Deuxièmement, l'écriture de HTTP/2. La nouvelle directive http2 on; n'existe qu'à partir de nginx 1.25.1. Sur Debian 12 (1.22), Ubuntu 22.04 (1.18) et aussi Ubuntu 24.04 (1.24), vous devez utiliser l'ancienne forme listen 443 ssl http2;, faute de quoi le démarrage s'interrompt avec nginx: [emerg] unknown directive "http2". Seul Debian 13, avec nginx 1.26, comprend les deux formes.

server {
    listen 443 ssl http2;
    server_name panel.example.com;
    root /var/www/pterodactyl/public;
    index index.php;
    client_max_body_size 100m;

    ssl_certificate /etc/letsencrypt/live/panel.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/panel.example.com/privkey.pem;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param HTTP_PROXY "";
    }
}

File d'attente et planification

Sans ces deux briques, le Panel a l'air fonctionnel, mais il n'envoie aucun e-mail et n'exécute aucune tâche planifiée. La construction du fichier d'unité est expliquée en détail dans notre article sur la création d'un service systemd, voici la version prête à l'emploi :

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

[Service]
User=www-data
Group=www-data
Restart=always
RestartSec=5s
ExecStart=/usr/bin/php /var/www/pterodactyl/artisan queue:work --queue=high,standard,low --sleep=3 --tries=3

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable --now redis-server
systemctl enable --now pteroq.service

Il faut y ajouter une entrée dans la crontab de root, les détails de la syntaxe se trouvent dans l'article Mettre en place un cronjob sous Linux :

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

Installer Wings sur le nœud

À partir d'ici, vous travaillez sur la machine qui doit exécuter les serveurs de jeu. Ce peut être le même serveur, mais rien ne l'impose. Docker en est le prérequis, sa mise en place est décrite dans notre article Installer Docker sous Debian et Ubuntu.

mkdir -p /etc/pterodactyl
curl -L -o /usr/local/bin/wings https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_amd64
chmod u+x /usr/local/bin/wings
wings version

Sur les serveurs ARM, le nom du fichier est wings_linux_arm64. Si vous récupérez le mauvais binaire, le shell répond simplement cannot execute binary file: Exec format error. Ne vous étonnez pas de la sortie de la dernière ligne : wings version répond avec un double v, par exemple wings vv1.13.1. Cela vient de l'éditeur et ne signale pas une installation cassée.

Le fichier /etc/pterodactyl/config.yml, vous ne l'écrivez pas vous-même. Il sera créé automatiquement dans un instant. Pour l'heure, créez seulement le service :

[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

Ne démarrez pas encore. Sans configuration, Wings s'arrête immédiatement, avec un message qui signale en substance l'absence du fichier de configuration sous /etc/pterodactyl/config.yml. À ce stade, c'est parfaitement normal et ce n'est pas une erreur.

Un mot sur le fichier d'échange : beaucoup de guides anciens réclament swapaccount=1 dans /etc/default/grub. Cela ne concerne que les systèmes en cgroup v1. Debian 12 et 13 ainsi qu'Ubuntu 22.04 et 24.04 utilisent cgroup v2 par défaut, l'entrée y est superflue. Cela se vérifie avec docker info. Si WARNING: No swap limit support y apparaît, la limitation mémoire ne s'applique pas au swap. Notre article Mettre en place le swap explique comment dimensionner cet espace d'échange de façon sensée.

Un certificat pour le nœud, pas seulement pour le Panel

L'erreur de raisonnement la plus fréquente : on se procure un certificat pour panel.example.com et on s'étonne que le nœud ne fonctionne pas. Wings a besoin d'un certificat à lui, pour son propre nom de domaine, par exemple node1.example.com. Les deux noms peuvent pointer vers la même IP, mais ce sont bien deux noms.

Sur un nœud dédié à cette seule tâche, aucun serveur web ne tourne : le mode autonome de Certbot est donc la voie la plus simple. Le port 80 doit pour cela être joignable depuis l'extérieur pendant un court instant :

apt -y install certbot
certbot certonly --standalone -d node1.example.com

Si vous exploitez de nombreux nœuds, un certificat wildcard est plus confortable, nous le décrivons dans l'article Certificat wildcard Let's Encrypt.

Deux pièges qui coûtent beaucoup de temps :

• Wings lit les fichiers du certificat au démarrage. Après un renouvellement, le service doit être rechargé. Déposez dans /etc/letsencrypt/renewal-hooks/deploy/ un petit script contenant systemctl restart wings. Sans cela, le nœud fonctionne impeccablement pendant 90 jours, puis tombe en panne sans raison apparente.
• Désactivez le proxy Cloudflare pour le nom du nœud. Le nuage orange ouvre la connexion TLS et remplace le certificat. Le Panel reçoit alors un certificat qui ne correspond pas à l'émetteur attendu, et la connexion à la console via WebSocket devient imprévisible. L'enregistrement A du nœud doit rester en gris.

Créer et connecter le nœud

Dans le Panel, sous Admin, Locations, créez d'abord un emplacement, puis le nœud sous Nodes. Les champs qui comptent vraiment :

• FQDN : node1.example.com, exactement le nom qui figure dans le certificat.
• Communicate over SSL : activé si le Panel tourne en HTTPS. Sinon, autant ne pas commencer.
• Behind Proxy : à activer uniquement si un reverse proxy se trouve réellement devant Wings et qu'il termine le TLS.
• Daemon Port : 8080. Daemon SFTP Port : 2022.
• Memory et Disk : les limites que le Panel respecte lorsqu'il répartit les serveurs.

Après l'enregistrement, ouvrez l'onglet Configuration du nœud. Le Panel y génère une commande contenant un token à usage unique. À exécuter sur le nœud :

cd /etc/pterodactyl
wings configure --panel-url https://panel.example.com --token TOKEN --node 1

Wings récupère ainsi sa configuration complète et écrit /etc/pterodactyl/config.yml. Vérifiez le contenu : si l'adresse du Panel y apparaît en http:// au lieu de https://, c'est que vous avez copié la commande depuis un environnement où l'URL du Panel est mal enregistrée. Corrigez le problème à la racine avec php artisan p:environment:setup, pas à la main dans le fichier YAML.

Ensuite, dans l'onglet Allocations, saisissez l'IP du nœud et les plages de ports souhaitées, par exemple 25565 à 25600 pour Minecraft. Sans au moins une allocation libre, aucun serveur ne peut être créé.

Ce n'est que maintenant qu'il faut démarrer :

systemctl enable --now wings
systemctl status wings

Les ports doivent être ouverts dans le pare-feu. Avec ufw, dont nous traitons les bases dans l'article Configurer le pare-feu ufw :

ufw allow 8080/tcp
ufw allow 2022/tcp
ufw allow 25565:25600/tcp
ufw allow 25565:25600/udp

Quand Wings ne se connecte pas

Le Panel affiche un symbole rouge sur le nœud, ou renvoie une erreur à la création d'un serveur. Traitez les messages dans l'ordre, ils sont étonnamment explicites.

cURL error 7: Failed to connect ... Connection refused

Le serveur du Panel n'atteint pas le port. Soit Wings ne tourne pas, soit le pare-feu bloque, soit le service écoute sur la mauvaise adresse. Vérifiez dans cet ordre :

systemctl status wings
ss -tlnp | grep 8080
journalctl -u wings -n 50 --no-pager

Et depuis le serveur du Panel, c'est le test décisif :

curl -v https://node1.example.com:8080

Une réponse HTTP, même un 404 avec du contenu JSON, est ici un succès. Elle prouve que le DNS, le pare-feu, le port et le TLS fonctionnent ensemble.

cURL error 60: SSL certificate problem

Le certificat du nœud n'est pas accepté. Avec self signed certificate, vous utilisez un certificat auto-signé : le Panel ne sait pas s'en accommoder, car la bibliothèque sous-jacente ne connaît aucune exception. Avec unable to get local issuer certificate, c'est le plus souvent la chaîne intermédiaire qui manque, votre configuration Wings pointe alors vers cert.pem au lieu de fullchain.pem. Avec certificate has expired, le renouvellement a bien eu lieu, mais Wings garde encore l'ancien fichier en mémoire, voyez le point sur le redémarrage plus haut.

cURL error 28: Operation timed out

Aucune réponse, aucun reset. Cela sent le pare-feu qui jette les paquets au lieu de les rejeter, ou le nœud placé derrière du NAT. Un cas particulier : le Panel et Wings sur le même serveur, et le Panel qui s'adresse à sa propre IP publique. Certains réseaux ne renvoient pas cette boucle. La solution consiste à ajouter, sur le serveur du Panel, une entrée dans /etc/hosts qui fait pointer le nom du nœud vers l'adresse interne.

Cannot connect to the Docker daemon at unix:///var/run/docker.sock

Wings tourne, Docker non. systemctl status docker le montre en une ligne. Le nœud apparaît souvent malgré tout comme joignable dans le Panel, parce que l'interrogation de l'état fonctionne, mais chaque démarrage de serveur échoue.

Le nœud répond, mais toute action est refusée

Un token n'est pas le bon. Cela arrive après un nouveau wings configure avec un ancien token, ou après avoir supprimé puis recréé le nœud dans le Panel. Solution : générer un token frais dans l'onglet Configuration du Panel, réexécuter la commande, redémarrer Wings. Ne tâtonnez pas dans le fichier YAML.

Dans tous les cas où le message reste obscur, arrêtez le service et démarrez Wings au premier plan. La sortie est nettement plus bavarde que le journal :

systemctl stop wings
wings --debug

Le mode rapport intégré rend lui aussi service, il rassemble la configuration, l'état de Docker et les données système :

wings diagnostics

Décalage d'horloge entre le Panel et le nœud

Cette erreur est traîtresse, parce qu'elle ressemble à un problème réseau. Symptômes : le nœud est affiché comme joignable dans le Panel, les serveurs peuvent être créés, mais la console reste bloquée à l'établissement de la connexion et l'accès SFTP refuse des identifiants pourtant corrects.

La raison tient à la conception. Le Panel signe des tokens à courte durée de vie, valables quelques minutes seulement. Wings contrôle la date d'émission et l'expiration par rapport à sa propre horloge. Si les deux systèmes s'écartent de plus de quelques minutes, Wings rejette chaque token comme expiré ou comme pas encore valable, alors qu'il vient tout juste d'être généré.

Important à comprendre : il ne s'agit pas du fuseau horaire. Le Panel et le nœud peuvent très bien être réglés sur des fuseaux différents, cela n'a aucune importance. Ce qui compte, c'est l'instant absolu. Vérifiez sur les deux machines :

date -u
timedatectl status

Dans la sortie de timedatectl, il faut lire System clock synchronized: yes et NTP service: active. Si ce n'est pas le cas :

timedatectl set-ntp true

Sur les systèmes dépourvus de systemd-timesyncd, par exemple après une installation minimale, installez chrony et vérifiez la synchronisation :

apt -y install chrony
chronyc tracking

La valeur affichée pour System time doit se situer dans l'ordre de la milliseconde. Les machines virtuelles clonées à partir d'une image ou restaurées depuis un snapshot sont la source la plus fréquente d'écarts importants.

Comment savoir que tout fonctionne vraiment

Un symbole vert dans le Panel n'est que la première de cinq preuves. Parcourez la liste, vous en aurez alors la certitude :

1. systemctl is-active wings renvoie active, et un journalctl -u wings -n 20 ne montre aucune erreur récurrente.
2. Dans la vue d'ensemble, le nœud annonce la capacité réelle en mémoire et en stockage du serveur cible, pas seulement les limites saisies dans le Panel. Ces chiffres viennent en direct du nœud et prouvent que la communication fonctionne.
3. Vous créez un serveur de test. Dans la vue d'ensemble, il passe par l'état Installing puis s'affiche normalement. Sur le nœud, docker ps -a montre le conteneur correspondant.
4. Vous démarrez le serveur et voyez dans le navigateur la console défiler en direct. C'est la preuve de la connexion WebSocket, donc du certificat et de l'horloge en même temps.
5. Vous vous connectez en SFTP sur le port 2022 avec vos identifiants du Panel et vous voyez les fichiers du serveur. Le second port de Wings est ainsi confirmé lui aussi.

L'installation n'est complète qu'une fois les cinq points validés. D'expérience, ce sont les points quatre et cinq qui échouent le plus souvent, alors que le Panel paraît jusque-là parfaitement normal.

Exploiter le Panel et Wings ensemble ou séparément

Les deux sont possibles. Sur un serveur unique, vous devez seulement veiller à deux choses : utilisez deux noms de domaine différents sur la même IP, un pour le Panel sur le port 443 et un pour le nœud sur le port 8080. Et attendez-vous à ce que l'appétit en mémoire des serveurs de jeu ralentisse aussi le Panel quand la situation devient serrée.

Séparer les deux rôles est de toute façon la norme dès le deuxième nœud, avec un effet secondaire agréable : un serveur de jeu surchargé ou attaqué n'entraîne pas l'interface d'administration dans sa chute. Pour la sécurisation de base des deux machines, un coup d'œil à notre checklist pour un nouveau serveur root ainsi qu'aux articles sur la sécurisation SSH et fail2ban en vaut la peine.

Pour finir, une remarque pratique pour l'exploitation : les images Docker des serveurs de jeu embarquent elles-mêmes leur environnement Java. Vous n'avez pas besoin d'installer Java sur le nœud. Si vous voulez tout de même faire un essai en dehors de Pterodactyl, vous trouverez la marche à suivre dans nos articles sur Java 21 sous Debian et sur le serveur Minecraft sous Debian. Et gardez un œil sur l'espace disque, les images et les sauvegardes grossissent vite, l'article Disque plein sous Linux tombe à propos.