Comment installer Pterodactyl sur un VPS Linux

[BoxToPlay-helper]

Installer Pterodactyl sur un serveur VPS Linux

Pterodactyl (retrouvez également son dépôt GitHub officiel) est un panel de gestion open source de serveurs de jeux qui s’appuie sur deux composants distincts : le Panel, qui fournit l’interface web d’administration, et Wings, qui exécute les services sur le nœud grâce à Docker. Si vous souhaitez déployer cette solution sur un serveur VPS, il faut donc préparer correctement Linux, la base de données, le service web, puis relier le nœud au panel.

Ce guide a été testé sur un VPS Ubuntu 24.04.4 LTS, avec Pterodactyl Panel 1.12.4 et Wings 1.12.3. Les commandes ci-dessous restent proches de la documentation officielle, mais ajoutent les vérifications utiles que l’on découvre souvent seulement pendant l’installation.

Ce que vous allez obtenir à la fin

À la fin de l’installation, vous disposerez de :

• un Panel Pterodactyl accessible via le web.
• un premier compte administrateur.
• un service de file d’attente fonctionnel.
• un Node Wings connecté au panel.
• des allocations IP et ports prêtes à être utilisées.

Voici l’interface d’administration obtenue après installation du Panel :

Prérequis avant de commencer

Avant toute installation, vérifiez les points suivants :

• vous avez un accès root à votre VPS.
• vous utilisez une distribution Linux compatible, par exemple Ubuntu 22.04, Ubuntu 24.04, Debian 11, Debian 12 ou Debian 13.
• votre environnement supporte Docker.
• vous n’êtes pas sur un environnement OpenVZ ou LXC non compatible avec Docker.
• vous disposez d’un nom de domaine pour le panel, et idéalement d’un sous-domaine distinct pour le nœud Wings.

Pour Wings, le point critique est bien la compatibilité Docker. Si votre virtualisation ne prend pas correctement en charge les conteneurs, le nœud ne pourra pas fonctionner normalement.

Vous pouvez vérifier la virtualisation avec :

systemd-detect-virt

Sur un VPS KVM, la commande peut par exemple retourner :

kvm

Si vous devez installer Docker sur votre machine avant d’aller plus loin, nous vous conseillons de suivre notre guide dédié : Installer Docker sur Linux, guide pratique pour bien démarrer.

Étape 1 : installer les dépendances du Panel

Le Panel Pterodactyl nécessite notamment :

• PHP 8.2 ou 8.3.
• MariaDB ou MySQL.
• Redis.
• NGINX ou un autre serveur web.
• Composer v2.
• curl, tar, unzip, git et lsb-release.

L’exemple ci-dessous vise une base Ubuntu avec NGINX, MariaDB, Redis et PHP 8.3. Sur Debian, adaptez les dépôts PHP au lieu d’utiliser le PPA Ubuntu.

apt update
apt -y install software-properties-common curl apt-transport-https ca-certificates gnupg lsb-release
LC_ALL=C.UTF-8 add-apt-repository -y ppa:ondrej/php
curl -fsSL https://packages.redis.io/gpg | gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/redis.list
apt update
apt -y install php8.3 php8.3-common php8.3-cli php8.3-gd php8.3-mysql php8.3-mbstring php8.3-bcmath php8.3-xml php8.3-fpm php8.3-curl php8.3-zip mariadb-server nginx tar unzip git redis-server

Installez ensuite Composer :

curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

Si vous lancez Composer en root, certaines commandes peuvent afficher un avertissement interactif. Pour l’installation du Panel, utilisez bien COMPOSER_ALLOW_SUPERUSER=1 comme indiqué plus bas.

Étape 2 : télécharger les fichiers du Panel

Créez le dossier d’installation, placez-vous dedans, puis récupérez les fichiers du panel.

mkdir -p /var/www/pterodactyl
cd /var/www/pterodactyl
curl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz
tar -xzvf panel.tar.gz
chmod -R 755 storage/* bootstrap/cache/

Étape 3 : préparer la base de données

Le panel a besoin d’une base dédiée et d’un utilisateur avec les droits nécessaires. Choisissez un mot de passe fort et conservez-le, car il sera demandé pendant la configuration de l’environnement.

Connexion à MariaDB :

mariadb -u root -p

Puis, dans la console SQL :

CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'votreMotDePasseFort';
CREATE DATABASE panel;
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1' WITH GRANT OPTION;
exit

Utilisez 127.0.0.1 plutôt que localhost, afin d’éviter les problèmes de socket MySQL lors de la connexion du Panel.

Étape 4 : configurer le Panel Pterodactyl

Copiez le fichier d’environnement, installez les dépendances PHP du projet, puis générez la clé d’application.

cd /var/www/pterodactyl
cp .env.example .env
COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader
php artisan key:generate --force

Ensuite, lancez la configuration interactive :

php artisan p:environment:setup
php artisan p:environment:database
php artisan p:environment:mail

Points importants pendant ces assistants :

• l’URL du panel doit commencer par https:// ou http://.
• utilisez 127.0.0.1 comme hôte MariaDB si la base est locale.
• pour la queue, Redis est recommandé.
• si vous n’avez pas encore de SMTP, configurez temporairement le mailer en mode log ou revenez-y plus tard avec une vraie configuration mail.

Puis initialisez la base :

php artisan migrate --seed --force

Créez enfin le premier compte administrateur :

php artisan p:user:make

Sauvegarder la clé APP_KEY

La variable APP_KEY est essentielle. Elle sert au chiffrement des données sensibles du panel. Si vous la perdez, les données chiffrées ne pourront pas être restaurées correctement.

Pour l’afficher :

grep APP_KEY /var/www/pterodactyl/.env

Conservez cette valeur dans un emplacement sûr en dehors du serveur, avec une sauvegarde de votre fichier .env.

Étape 5 : appliquer les permissions correctes

Sur un système Linux avec NGINX, appliquez les droits au bon utilisateur web :

chown -R www-data:www-data /var/www/pterodactyl

Étape 6 : configurer le serveur web NGINX

Pour rendre le panel accessible, vous devez configurer NGINX et installer un certificat SSL avec Certbot. En production, prévoyez un nom de domaine qui pointe déjà vers l’IP du VPS avant de demander le certificat.

1. Installez Certbot et son plugin NGINX :

apt update
apt -y install certbot python3-certbot-nginx

2. Générez le certificat SSL pour votre nom de domaine, en remplaçant panel.mon-domaine.fr par votre sous-domaine réel :

certbot certonly --nginx -d panel.mon-domaine.fr

3. Créez ensuite le fichier de configuration NGINX /etc/nginx/sites-available/pterodactyl.conf :

server {
    listen 80;
    server_name panel.mon-domaine.fr;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name panel.mon-domaine.fr;

    root /var/www/pterodactyl/public;
    index index.php;

    access_log /var/log/nginx/pterodactyl.app-access.log;
    error_log /var/log/nginx/pterodactyl.app-error.log error;

    client_max_body_size 100m;
    client_body_timeout 120s;
    sendfile off;

    ssl_certificate /etc/letsencrypt/live/panel.mon-domaine.fr/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/panel.mon-domaine.fr/privkey.pem;

    ssl_session_cache shared:SSL:10m;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384";
    ssl_prefer_server_ciphers on;

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

    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param PHP_VALUE "upload_max_filesize = 100M \n post_max_size=100M";
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param HTTP_PROXY "";
        fastcgi_intercept_errors off;
        fastcgi_buffer_size 16k;
        fastcgi_buffers 4 16k;
        fastcgi_connect_timeout 300;
        fastcgi_send_timeout 300;
        fastcgi_read_timeout 300;
    }

    location ~ /\.ht {
        deny all;
    }
}

Si vous utilisez une version de PHP différente de 8.3, adaptez le chemin php8.3-fpm.sock.

4. Activez la configuration en créant le lien symbolique, retirez la configuration par défaut de NGINX si elle existe, puis validez et redémarrez NGINX :

ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/pterodactyl.conf
rm -f /etc/nginx/sites-enabled/default
nginx -t
systemctl restart nginx

Après cette étape, ouvrez votre domaine dans le navigateur et connectez-vous avec le compte administrateur créé plus haut.

Étape 7 : activer cron et la file d’attente

Pterodactyl s’appuie sur un ordonnanceur et une file d’attente pour les tâches en arrière-plan.

Ajoutez la tâche cron :

(crontab -l 2>/dev/null; echo "* * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1") | crontab -

Créez ensuite le service systemd de la queue dans /etc/systemd/system/pteroq.service avec ce contenu :

cat <<'EOF' > /etc/systemd/system/pteroq.service
[Unit]
Description=Pterodactyl Queue Worker
After=redis-server.service

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

[Install]
WantedBy=multi-user.target
EOF

Puis activez Redis et le worker :

systemctl enable --now redis-server
systemctl daemon-reload
systemctl enable --now pteroq.service
systemctl status pteroq.service --no-pager

Étape 8 : installer Docker pour Wings

Wings repose sur Docker. Commencez donc par l’installer, puis activez le service au démarrage.

Sur une machine neuve, utilisez cette séquence pour désinstaller les paquets obsolètes puis installer la dernière version stable de Docker Engine :

sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc | cut -f1)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
systemctl enable --now docker
docker version

Si Docker est déjà utilisé en production sur le VPS, ne supprimez pas les paquets existants sans fenêtre de maintenance. Dans ce cas, vérifiez d’abord la version installée et l’impact sur vos conteneurs existants.

Sur les noyaux Linux antérieurs à 6.1, l’activation de la gestion du swap peut aussi être utile pour éviter certains problèmes mémoire dans les conteneurs.

Étape 9 : installer Wings sur le nœud Linux

Créez le dossier de configuration puis téléchargez le binaire Wings.

mkdir -p /etc/pterodactyl
curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
chmod u+x /usr/local/bin/wings
wings version

Étape 10 : créer le Node dans le Panel

Une fois le panel opérationnel, allez dans Admin > Nodes > Create New. Renseignez le nom du nœud, sa location, son FQDN, les limites mémoire/disque et les ports Wings.

Quelques règles simples :

• utilisez un FQDN réel pour le nœud, par exemple node.mon-domaine.fr.
• choisissez Use SSL Connection si Wings dispose d’un certificat valide pour ce FQDN.
• choisissez Use HTTP Connection uniquement pour un test temporaire ou un environnement isolé.
• gardez 8080 pour l’API Wings et 2022 pour le SFTP, sauf besoin précis.
• ne mettez pas 127.0.0.1 dans les allocations de serveurs de jeux.

Après création du nœud, ouvrez l’onglet Configuration. Le panel génère le contenu complet du fichier config.yml à copier dans /etc/pterodactyl/config.yml.

Créez ensuite le fichier côté serveur :

nano /etc/pterodactyl/config.yml

Collez le contenu fourni par le panel, enregistrez, puis testez Wings en mode debug :

wings --debug

Si le démarrage est correct, vous devez voir Wings contacter l’API du Panel, traiter la liste des serveurs, puis écouter sur le port API et le port SFTP. Vous pouvez alors arrêter le mode debug avec Ctrl+C et passer au service systemd.

Étape 11 : lancer Wings comme service systemd

Créez le service /etc/systemd/system/wings.service :

cat <<'EOF' > /etc/systemd/system/wings.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
EOF

Activez ensuite le service :

systemctl daemon-reload
systemctl enable --now wings
systemctl status wings --no-pager

Vous pouvez aussi vérifier les ports écoutés :

ss -ltnp | grep -E ':(8080|2022) '

Étape 12 : ajouter les allocations IP et ports

Chaque service créé sur le nœud a besoin d’au moins une allocation, c’est-à-dire une combinaison IP + port. Dans l’administration du nœud, ajoutez les plages de ports nécessaires avec l’adresse IP correcte de votre interface réseau ou l’IP publique du VPS.

Pour récupérer l’IP principale du serveur :

hostname -I | awk '{print $1}'

Pour vérifier l’IP publique vue depuis Internet :

curl -fsS https://api.ipify.org

N’utilisez pas 127.0.0.1 pour les allocations. Voici un exemple d’allocations créées dans l’interface, avec une IP de documentation masquée :

Étape 13 : configurer le pare-feu

Pour que le Panel, Wings et vos serveurs de jeux puissent communiquer et être accessibles depuis l’extérieur, il est indispensable de configurer le pare-feu de votre VPS.

Pterodactyl utilise généralement les ports suivants :

• 80 et 443 en TCP pour l’accès web au Panel.
• 8080 en TCP pour l’API Wings utilisée par le Panel.
• 2022 en TCP pour le serveur SFTP intégré à Wings.
• les ports de vos serveurs de jeux, par exemple 25565 en TCP/UDP pour Minecraft.

Option A : configuration avec UFW

Avant d’activer UFW, vérifiez toujours son état actuel pour éviter de vous couper l’accès SSH :

ufw status

Autorisez impérativement SSH, puis ouvrez les ports nécessaires :

ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 8080/tcp
ufw allow 2022/tcp
ufw allow 25565:25600/tcp
ufw allow 25565:25600/udp
ufw enable

Notez que la règle pour le port 22/tcp (SSH) sert uniquement à maintenir votre accès d’administration à distance au VPS, et n’est pas requise pour le fonctionnement de Pterodactyl lui-même.

Si votre hébergeur applique aussi un pare-feu réseau externe, ouvrez les mêmes ports dans son interface client.

Option B : configuration équivalente avec iptables

Si votre distribution n’utilise pas UFW, vous pouvez appliquer ces règles directement avec iptables :

iptables -A INPUT -p tcp --dport 22 -j ACCEPT
iptables -A INPUT -p tcp --dport 80 -j ACCEPT
iptables -A INPUT -p tcp --dport 443 -j ACCEPT
iptables -A INPUT -p tcp --dport 8080 -j ACCEPT
iptables -A INPUT -p tcp --dport 2022 -j ACCEPT
iptables -A INPUT -p tcp --dport 25565:25600 -j ACCEPT
iptables -A INPUT -p udp --dport 25565:25600 -j ACCEPT

De même, la règle pour le port 22/tcp sert uniquement à conserver votre accès SSH d’administration (le port par défaut est 22, mais pensez à l’adapter si vous l’avez modifié).

Pensez à persister vos règles iptables selon votre distribution, sinon elles peuvent disparaître au redémarrage.

Vérifications finales

Avant de créer votre premier serveur de jeu, contrôlez l’état des services :

systemctl status nginx php8.3-fpm mariadb redis-server pteroq wings --no-pager

Vérifiez aussi que les ports attendus écoutent bien :

ss -ltnp | grep -E ':(80|443|8080|2022) '

Enfin, dans le panel, retournez sur votre nœud. Si Wings communique correctement avec le Panel, vous pourrez créer un serveur et lui assigner une allocation disponible.

Exemple : créer un serveur Minecraft dans Pterodactyl

Une fois le Panel, Wings et les allocations en place, le test le plus parlant consiste à créer un premier serveur Minecraft. Dans l’administration Pterodactyl, allez dans Admin > Servers > Create New.

Commencez par les informations générales : nom du serveur, propriétaire, nœud cible et allocation principale. Pour un test simple, utilisez une seule allocation, par exemple le port 25565, puis laissez Start Server when Installed activé si vous voulez lancer le serveur automatiquement après l’installation.

Renseignez ensuite les limites applicatives et les ressources du conteneur. Pour un petit serveur Paper de test, une base raisonnable peut être :

• Database Limit à 0 si vous ne prévoyez pas de base externe.
• Allocation Limit à 1 si le serveur n’a besoin que d’un port.
• Backup Limit à 2 pour permettre quelques sauvegardes.
• CPU Limit à 100 pour limiter le serveur à un cœur logique.
• Memory à 2048 MiB pour un test confortable.
• Swap à 0 pour désactiver le swap du conteneur.
• Disk Space à 8192 MiB pour donner 8 Go au serveur.

Dans Nest Configuration, choisissez le nest Minecraft, puis l’egg que vous souhaitez utiliser. Pour cet exemple, nous utilisons Paper, car c’est un choix courant pour un serveur Minecraft optimisé avec plugins.

Pour l’image Docker, faites attention à la version Java. Avec latest, les versions Minecraft récentes peuvent exiger Java 25. Par exemple, Paper pour Minecraft 26.1 demande Java 25 : l’image ghcr.io/pterodactyl/yolks:java_21 peut donc faire crasher le démarrage. Pour un serveur latest, choisissez Java 25 ou épinglez une version Minecraft compatible avec l’image Java choisie.

Dans Startup Configuration, laissez la commande de démarrage générée par l’egg, puis vérifiez les variables :

• Minecraft Version : latest pour la dernière version, ou une version précise si vous voulez éviter les surprises.
• Server Jar File : server.jar.
• Build Number : latest pour le premier build Paper.

Cliquez ensuite sur Create Server. Le serveur apparaît d’abord en installation, puis passe en état Active quand Wings a terminé le téléchargement et la préparation des fichiers.

Enfin, ouvrez la vue utilisateur du serveur. La console permet de démarrer, redémarrer ou arrêter le serveur, de suivre les logs Minecraft et de contrôler l’utilisation CPU/RAM/réseau. Après passage sur Java 25, le serveur Paper doit démarrer correctement si l’allocation et les ports sont cohérents.

Si le serveur reste bloqué ou repasse hors ligne immédiatement, ouvrez les logs de la console. Les causes classiques sont une image Java incompatible avec la version Minecraft choisie, un port déjà utilisé, une allocation incorrecte, ou une EULA Minecraft à accepter selon l’egg et la version utilisée.

Réglages avancés de Wings à connaître

Une fois votre nœud fonctionnel, vous pouvez ajuster certains paramètres avancés dans /etc/pterodactyl/config.yml :

• registries Docker privées pour s’authentifier à un registre privé.
• network name et network_mode pour personnaliser le réseau des conteneurs.
• container_pid_limit pour limiter le nombre de processus dans un conteneur.
• throttles pour contrôler la quantité de logs ou l’intensité de certaines opérations.
• installer_limits pour plafonner les ressources utilisées lors des installations.

Ces réglages sont puissants, mais une mauvaise configuration peut casser le fonctionnement du nœud. Modifiez-les uniquement si vous comprenez précisément leur effet.

Erreurs fréquentes à éviter

Voici les problèmes rencontrés le plus souvent pendant ce type d’installation :

• composer semble bloqué en root : relancez la commande avec COMPOSER_ALLOW_SUPERUSER=1.
• No application encryption key has been specified : vérifiez que .env existe et relancez php artisan key:generate --force.
• le Panel génère de mauvais liens : vérifiez que APP_URL contient bien https:// ou http://.
• Wings ne contacte pas le Panel : vérifiez remote dans config.yml, le port 8080, le pare-feu et le choix HTTP/HTTPS du nœud.
• le serveur Minecraft crashe dès le démarrage : vérifiez que l’image Docker Java correspond à la version Minecraft demandée, par exemple Java 25 pour les versions récentes avec latest.
• les serveurs ne sont pas accessibles : vérifiez les allocations, les ports ouverts et l’IP publique utilisée.

Mettre à jour Wings plus tard

La mise à jour de Wings est rapide. Il est recommandé de garder une version cohérente avec celle du Panel. Pour une installation en Pterodactyl 1.12.x, la branche Wings 1.12.x est celle attendue.

Commande de mise à jour :

systemctl stop wings
curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
chmod u+x /usr/local/bin/wings
systemctl restart wings
systemctl status wings --no-pager

Bonnes pratiques pour une installation propre

Pour terminer, voici les recommandations que nous appliquons chez BoxToPlay pour obtenir un déploiement stable sur hébergement VPS :

• séparer clairement le Panel et le nœud si votre charge augmente.
• utiliser des certificats SSL valides pour le Panel et Wings.
• sauvegarder la base de données et le fichier .env.
• conserver une copie externe de APP_KEY.
• configurer correctement le pare-feu en suivant l’étape 13.
• éviter les modifications avancées de réseau Docker sans besoin réel.
• tester Wings en mode debug avant d’activer le service définitif.

Si vous cherchez un environnement fiable pour déployer ce type de stack sur un serveur VPS, nous mettons chez BoxToPlay l’accent sur des performances solides et une prise en main propre. Vous pouvez lancer votre serveur gratuitement.