Pterodactyl-Panel für Gameserver installieren

Pterodactyl ist die verbreitetste freie Oberfläche für Gameserver. Der Ruf, kompliziert zu sein, kommt fast nie von der Installation selbst, sondern von einem einzigen Missverständnis: Pterodactyl ist nicht ein Programm, sondern zwei. Diese Anleitung trennt beide sauber, zeigt die Unterschiede zwischen Debian und Ubuntu, und geht danach durch die Fehlermeldungen, die einen im Wortlaut in die Suchmaschine treiben.

Panel und Wings: zwei Programme, zwei Rollen

Das Panel ist eine PHP-Anwendung auf Laravel-Basis. Es liefert die Weboberfläche, verwaltet Benutzer, Rechte, Datenbanken und Zeitpläne und speichert alles in einer eigenen MySQL- oder MariaDB-Datenbank. Das Panel startet niemals selbst einen Gameserver. Es kennt nicht einmal Docker.

Wings ist ein einzelnes, in Go geschriebenes Programm. Es läuft auf jedem Rechner, auf dem tatsächlich Gameserver laufen sollen, spricht mit dem Docker-Daemon, startet Container, streamt die Konsole und stellt den SFTP-Zugang bereit. Wings hat keine Weboberfläche und keine Datenbank. Es hört auf einem HTTP-Port und wartet auf Anweisungen vom Panel.

Beide reden ausschließlich über HTTP miteinander, in beide Richtungen, mit signierten Tokens. Daraus folgen drei Dinge, die man von Anfang an akzeptieren sollte:

• Das Panel muss den Knoten über einen Domainnamen erreichen, nicht über eine IP. Das Zertifikat hängt am Namen.
• Panel und Wings müssen dasselbe Protokoll sprechen. HTTPS-Panel plus HTTP-Wings funktioniert nicht, der Browser blockiert die Konsolenverbindung.
• Beide Uhren müssen stimmen. Die Tokens haben eine Lebensdauer von wenigen Minuten.

Wer diese drei Sätze verinnerlicht hat, hat die Hälfte der typischen Pterodactyl-Probleme bereits vermieden.

Voraussetzungen und die Wahl des Systems

Pterodactyl 1.11 und neuer verlangt PHP 8.2 oder 8.3. Das ist der Punkt, an dem die meisten Anleitungen ungenau werden, denn die Distributionen liefern sehr unterschiedliche Versionen aus. Stand Juli 2026 sieht die Lage in den Standardquellen so aus:

Diese Anleitung ist reine Debian- und Ubuntu-Kost. Auf AlmaLinux, Rocky Linux und Oracle Linux gibt es kein apt, dort ist keiner der folgenden Paketbefehle anwendbar.

Praktische Konsequenz: Debian 12 und Ubuntu 24.04 sind die beiden Systeme, auf denen das Panel ohne Fremdquellen läuft. Auf Ubuntu 22.04 brauchen Sie das PPA von Ondřej Surý, auf Debian 13 dessen Debian-Gegenstück, weil PHP 8.4 dort das Metapaket stellt und die composer.json des Panels ausdrücklich ^8.2 || ^8.3 verlangt. In der Praxis läuft der Composer-Lauf unter PHP 8.4 zwar durch, das ist aber unbestätigtes Gelände und kein Zustand, in dem man einen Produktivserver betreiben will. Wer sich die Zusatzquelle sparen will, nimmt Debian 12 oder Ubuntu 24.04.

Die beiden zu alten Systeme scheitern übrigens nicht am Paketbefehl, sondern erst zwei Schritte später, und das macht sie so tückisch. apt install php läuft auf Ubuntu 22.04 (PHP 8.1.2) und Debian 11 (PHP 7.4.33) mit Exit-Code 0 durch, erst der Composer-Lauf bricht dann ab, auf Ubuntu 22.04 mit brick/math requires php (^8.2) failed, auf Debian 11 mit aws/aws-sdk-php requires php (>=8.1) failed. Wenn Sie auf einem dieser Systeme bleiben müssen, installieren Sie aus der Fremdquelle ausdrücklich versionierte Pakete (php8.3, php8.3-cli, php8.3-fpm und so weiter) statt des Metapakets php, sonst greift wieder die Distributionsversion.

Zweiter Unterschied, der regelmäßig überrascht: Debian liefert überhaupt kein Paket mysql-server. Dort ist MariaDB gesetzt, und das ist völlig in Ordnung, Pterodactyl verlangt MariaDB 10.2 oder neuer. Wer unter Debian apt install mysql-server tippt, bekommt E: Unable to locate package mysql-server und sucht anschließend an der falschen Stelle.

Für den Knoten mit Wings gelten diese PHP-Regeln übrigens gar nicht. Wings ist ein statisch gelinktes Go-Programm und braucht nur Docker und eine halbwegs aktuelle Kernel-Version. Der Knoten kann problemlos Debian 13 sein, während das Panel auf Debian 12 läuft.

Das Panel installieren

Alle folgenden Befehle als root. Zuerst die Grundpakete. Achten Sie darauf, dass Sie die PHP-Erweiterungen vollständig mitnehmen, ein fehlendes php-bcmath fällt erst beim Composer-Lauf auf.

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

Prüfen Sie sofort, ob die Version passt, bevor Sie weitermachen:

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

Danach Composer und die Panel-Dateien:

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

Die Datenbank. Legen Sie den Benutzer auf 127.0.0.1 an und nicht auf localhost, sonst greift der Socket-Zugriff und Laravel bekommt später eine Zugriffsverweigerung, obwohl das Passwort stimmt. Wie man den Fall auseinanderdividiert, steht in unserem Beitrag zu Access denied for user.

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

Die Datenbank sollte anschließend abgesichert werden, dazu haben wir einen eigenen Beitrag über das Absichern von MariaDB und MySQL.

Jetzt die eigentliche Einrichtung. Die p:environment-Befehle sind interaktiv und fragen Panel-URL, Zeitzone, Cache-Treiber und Datenbankzugang ab:

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/*

Wählen Sie bei p:environment:setup als Session- und Cache-Treiber Redis, dann greift die weiter unten beschriebene Warteschlange sauber. Und tragen Sie die Panel-URL mit https:// ein. Ein http:// an dieser Stelle erzeugt später gemischte Inhalte und eine Konsole, die ewig auf Verbindung wartet.

nginx und die Versionsfalle

Die Grundzüge der Webserver-Einrichtung stehen in unserem Beitrag zum Installieren von nginx. Für Pterodactyl sind zwei Details wichtig, an denen fertige Vorlagen aus dem Netz regelmäßig scheitern.

Erstens der PHP-FPM-Socket. Der Dateiname enthält die PHP-Version und unterscheidet sich je nach System. Schauen Sie nach, statt zu raten:

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

Auf Debian 12 heißt der Socket php8.2-fpm.sock, auf Ubuntu 24.04 php8.3-fpm.sock. Ein falscher Pfad hier erzeugt genau die 502-Bad-Gateway-Seite, nach der so viele suchen. Die Statusabfrage steht bewusst davor: Die Socket-Datei entsteht erst, wenn der FPM-Dienst läuft. Ist er nicht gestartet, ist /run/php/ leer, und Sie halten den Pfad fälschlich für falsch. Läuft der Dienst noch nicht, hilft systemctl enable --now php8.2-fpm mit der zu Ihrer Installation passenden Versionsnummer.

Zweitens die HTTP/2-Schreibweise. Die neue Direktive http2 on; gibt es erst ab nginx 1.25.1. Auf Debian 12 (1.22), Ubuntu 22.04 (1.18) und auch auf Ubuntu 24.04 (1.24) müssen Sie die alte Form listen 443 ssl http2; verwenden, sonst bricht der Start mit nginx: [emerg] unknown directive "http2" ab. Nur Debian 13 mit nginx 1.26 versteht beide Formen.

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 "";
    }
}

Warteschlange und Zeitplan

Ohne diese beiden Bausteine sieht das Panel funktionsfähig aus, verschickt aber keine Mails und führt keine geplanten Aufgaben aus. Der Aufbau der Unit-Datei ist in unserem Beitrag zum Erstellen eines systemd-Dienstes ausführlich erklärt, hier die fertige Fassung:

[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

Dazu ein Eintrag in der Crontab von root, Details zur Syntax finden Sie im Beitrag Cronjob einrichten unter Linux:

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

Wings auf dem Knoten installieren

Ab hier arbeiten Sie auf dem Rechner, der die Gameserver ausführen soll. Das kann derselbe Server sein, muss es aber nicht. Voraussetzung ist Docker, dessen Einrichtung wir im Beitrag Docker installieren unter Debian und Ubuntu beschrieben haben.

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

Auf ARM-Servern lautet der Dateiname wings_linux_arm64. Wenn Sie das falsche Paket ziehen, meldet die Shell schlicht cannot execute binary file: Exec format error. Wundern Sie sich nicht über die Ausgabe der letzten Zeile: wings version antwortet mit einem doppelten v, also etwa wings vv1.13.1. Das kommt so vom Hersteller und ist kein Zeichen einer kaputten Installation.

Die Datei /etc/pterodactyl/config.yml schreiben Sie nicht selbst. Sie entsteht gleich automatisch. Legen Sie zunächst nur den Dienst an:

[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

Noch nicht starten. Ohne Konfiguration bricht Wings sofort ab, mit einer Meldung, die sinngemäß auf eine fehlende Konfigurationsdatei unter /etc/pterodactyl/config.yml hinweist. Das ist an dieser Stelle völlig normal und kein Fehler.

Ein Wort zur Auslagerungsdatei: Viele ältere Anleitungen verlangen swapaccount=1 in /etc/default/grub. Das betrifft ausschließlich Systeme mit cgroup v1. Debian 12 und 13 sowie Ubuntu 22.04 und 24.04 nutzen standardmäßig cgroup v2, dort ist der Eintrag überflüssig. Prüfen lässt sich das mit docker info. Erscheint dort WARNING: No swap limit support, greift die Speicherbegrenzung für Auslagerung nicht. Wie man Auslagerungsspeicher überhaupt sinnvoll dimensioniert, steht im Beitrag Swap einrichten.

Zertifikat für den Knoten, nicht nur für das Panel

Der häufigste Denkfehler: Man besorgt ein Zertifikat für panel.example.com und wundert sich, dass der Knoten nicht funktioniert. Wings braucht ein eigenes Zertifikat für seinen eigenen Domainnamen, etwa node1.example.com. Beide Namen dürfen auf dieselbe IP zeigen, aber es sind zwei Namen.

Auf einem reinen Knoten läuft kein Webserver, deshalb ist der eigenständige Modus von Certbot der einfachste Weg. Port 80 muss dafür kurzzeitig von außen erreichbar sein:

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

Wer viele Knoten betreibt, fährt mit einem Platzhalterzertifikat besser, das beschreiben wir im Beitrag Let's Encrypt Wildcard-Zertifikat.

Zwei Stolpersteine, die viel Zeit kosten:

• Wings liest die Zertifikatsdateien beim Start. Nach einer Erneuerung muss der Dienst neu geladen werden. Hinterlegen Sie in /etc/letsencrypt/renewal-hooks/deploy/ ein kleines Skript mit systemctl restart wings. Ohne das läuft der Knoten 90 Tage tadellos und fällt dann scheinbar grundlos aus.
• Cloudflare-Proxy für den Knoten-Namen abschalten. Die orange Wolke bricht die TLS-Verbindung auf und ersetzt das Zertifikat. Das Panel bekommt dann ein Zertifikat, das nicht zum erwarteten Aussteller passt, und die Konsolenverbindung über WebSocket verhält sich unberechenbar. Der A-Eintrag für den Knoten gehört auf grau.

Knoten anlegen und verbinden

Im Panel unter Admin, Locations zuerst einen Standort anlegen, dann unter Nodes den Knoten. Die Felder, die tatsächlich zählen:

• FQDN: node1.example.com, exakt der Name aus dem Zertifikat.
• Communicate over SSL: eingeschaltet, wenn das Panel über HTTPS läuft. Sonst gar nicht erst anfangen.
• Behind Proxy: nur einschalten, wenn tatsächlich ein Reverse-Proxy vor Wings steht und dieser das TLS beendet.
• Daemon Port: 8080. Daemon SFTP Port: 2022.
• Memory und Disk: die Grenzen, die das Panel beim Verteilen von Servern beachtet.

Nach dem Speichern öffnen Sie den Reiter Configuration des Knotens. Dort erzeugt das Panel einen Befehl mit Einmal-Token. Auf dem Knoten ausführen:

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

Wings holt sich damit seine vollständige Konfiguration und schreibt /etc/pterodactyl/config.yml. Prüfen Sie den Inhalt: Steht dort http:// statt https:// bei der Panel-Adresse, haben Sie den Befehl aus einer Umgebung kopiert, in der die Panel-URL falsch hinterlegt ist. Korrigieren Sie es an der Wurzel mit php artisan p:environment:setup, nicht per Hand in der YAML-Datei.

Danach im Reiter Allocations die IP des Knotens und die gewünschten Portbereiche eintragen, etwa 25565 bis 25600 für Minecraft. Ohne mindestens eine freie Zuweisung lässt sich kein Server anlegen.

Jetzt erst starten:

systemctl enable --now wings
systemctl status wings

Die Ports müssen in der Firewall offen sein. Mit ufw, dessen Grundlagen wir im Beitrag ufw-Firewall einrichten behandeln:

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

Wenn Wings sich nicht verbindet

Das Panel zeigt beim Knoten ein rotes Symbol oder wirft beim Anlegen eines Servers einen Fehler. Arbeiten Sie die Meldungen der Reihe nach ab, sie sind erstaunlich eindeutig.

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

Der Panel-Server erreicht den Port nicht. Entweder läuft Wings nicht, oder die Firewall blockiert, oder der Dienst hört auf der falschen Adresse. Prüfen Sie in dieser Reihenfolge:

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

Und vom Panel-Server aus, das ist der entscheidende Test:

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

Eine HTTP-Antwort, auch ein 404 mit JSON-Inhalt, ist an dieser Stelle ein Erfolg. Sie beweist, dass DNS, Firewall, Port und TLS zusammenspielen.

cURL error 60: SSL certificate problem

Das Zertifikat des Knotens wird nicht akzeptiert. Bei self signed certificate haben Sie ein selbst erstelltes Zertifikat im Einsatz, damit kommt das Panel nicht zurecht, weil die zugrundeliegende Bibliothek keine Ausnahme kennt. Bei unable to get local issuer certificate fehlt meist die Zwischenkette, dann verweist Ihre Wings-Konfiguration auf cert.pem statt auf fullchain.pem. Bei certificate has expired ist die Erneuerung durchgelaufen, Wings hat aber die alte Datei noch im Speicher, siehe der Neustart-Haken weiter oben.

cURL error 28: Operation timed out

Keine Antwort, kein Reset. Das riecht nach einer Firewall, die Pakete verwirft statt abzulehnen, oder nach einem Knoten hinter NAT. Ein Sonderfall: Panel und Wings auf demselben Server, und das Panel spricht die eigene öffentliche IP an. Manche Netze führen diese Schleife nicht zurück. Abhilfe schafft ein Eintrag in /etc/hosts auf dem Panel-Server, der den Knotennamen auf die interne Adresse zeigt.

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

Wings läuft, Docker nicht. systemctl status docker klärt das in einer Zeile. Der Knoten erscheint im Panel dann oft trotzdem als erreichbar, weil der Zustandsabruf funktioniert, aber jeder Serverstart scheitert.

Der Knoten antwortet, aber jede Aktion wird abgelehnt

Ein Token stimmt nicht. Das passiert nach einem erneuten wings configure mit einem alten Token oder nachdem der Knoten im Panel gelöscht und neu angelegt wurde. Lösung: im Panel im Reiter Configuration einen frischen Token erzeugen, den Befehl erneut ausführen, Wings neu starten. Nicht in der YAML-Datei herumraten.

Für alle Fälle, in denen die Meldung unklar bleibt, stoppen Sie den Dienst und starten Wings im Vordergrund. Die Ausgabe ist deutlich gesprächiger als das Journal:

systemctl stop wings
wings --debug

Ebenfalls hilfreich ist der eingebaute Berichtsmodus, der Konfiguration, Docker-Zustand und Systemdaten sammelt:

wings diagnostics

Zeitversatz zwischen Panel und Knoten

Dieser Fehler ist tückisch, weil er aussieht wie ein Netzwerkproblem. Symptome: Der Knoten wird im Panel als erreichbar angezeigt, Server lassen sich anlegen, aber die Konsole bleibt beim Verbindungsaufbau hängen, und der SFTP-Zugang lehnt korrekte Zugangsdaten ab.

Der Grund liegt in der Bauweise. Das Panel signiert kurzlebige Tokens, deren Gültigkeit im Minutenbereich liegt. Wings prüft Ausstellungszeitpunkt und Ablauf gegen die eigene Uhr. Gehen die beiden Systeme mehr als ein paar Minuten auseinander, verwirft Wings jeden Token als abgelaufen oder als noch nicht gültig, obwohl er soeben erzeugt wurde.

Wichtig zum Verständnis: Es geht nicht um die Zeitzone. Panel und Knoten dürfen unterschiedliche Zeitzonen eingestellt haben, das ist unerheblich. Es geht um den absoluten Zeitpunkt. Prüfen Sie auf beiden Maschinen:

date -u
timedatectl status

In der Ausgabe von timedatectl muss System clock synchronized: yes und NTP service: active stehen. Falls nicht:

timedatectl set-ntp true

Auf Systemen ohne systemd-timesyncd, etwa nach einer minimalen Installation, installieren Sie chrony und prüfen den Abgleich:

apt -y install chrony
chronyc tracking

Der Wert bei System time sollte im Bereich von Millisekunden liegen. Virtuelle Maschinen, die aus einem Abbild geklont oder aus einem Schnappschuss wiederhergestellt wurden, sind die häufigste Quelle für größere Abweichungen.

Woran Sie erkennen, dass es wirklich läuft

Ein grünes Symbol im Panel ist nur der erste von fünf Belegen. Gehen Sie die Liste durch, dann wissen Sie es sicher:

1. systemctl is-active wings liefert active, und ein journalctl -u wings -n 20 zeigt keine wiederkehrenden Fehler.
2. Der Knoten in der Übersicht meldet die tatsächliche Speicher- und Festplattenkapazität des Zielservers, nicht nur die im Panel eingetragenen Grenzen. Diese Zahlen kommen live vom Knoten und sind ein Beweis für funktionierende Kommunikation.
3. Sie legen einen Testserver an. In der Übersicht durchläuft er den Zustand Installing und wird danach normal angezeigt. Auf dem Knoten zeigt docker ps -a den zugehörigen Container.
4. Sie starten den Server und sehen im Browser laufende Konsolenausgabe. Das ist der Beweis für die WebSocket-Verbindung und damit für Zertifikat und Uhrzeit gleichzeitig.
5. Sie verbinden sich per SFTP auf Port 2022 mit Ihren Panel-Zugangsdaten und sehen die Serverdateien. Damit ist auch der zweite Wings-Port bestätigt.

Erst wenn alle fünf Punkte stimmen, ist die Installation vollständig. Punkt vier und fünf schlagen erfahrungsgemäß am häufigsten fehl, obwohl das Panel bis dahin völlig unauffällig wirkt.

Panel und Wings gemeinsam oder getrennt betreiben

Beides ist möglich. Auf einem einzelnen Server müssen Sie lediglich zwei Dinge beachten: Verwenden Sie zwei verschiedene Domainnamen auf derselben IP, einen für das Panel auf Port 443 und einen für den Knoten auf Port 8080. Und rechnen Sie damit, dass der Speicherhunger der Gameserver das Panel mit ausbremst, wenn es eng wird.

Getrennt zu fahren ist ab dem zweiten Knoten ohnehin der Normalfall und hat einen angenehmen Nebeneffekt: Ein überlasteter oder angegriffener Gameserver reißt die Verwaltungsoberfläche nicht mit. Für die Grundabsicherung beider Maschinen lohnt sich ein Blick in unsere Checkliste für neue Rootserver sowie in die Beiträge zu SSH-Absicherung und fail2ban.

Zum Schluss ein praktischer Hinweis für den Betrieb: Die Docker-Abbilder für die Gameserver bringen ihre Java-Umgebung selbst mit. Sie müssen auf dem Knoten kein Java installieren. Wer trotzdem einmal außerhalb von Pterodactyl testen will, findet die passenden Wege in unseren Beiträgen zu Java 21 unter Debian und zum Minecraft-Server unter Debian. Und behalten Sie den Plattenplatz im Auge, Abbilder und Sicherungen wachsen schnell, dazu passt der Beitrag Festplatte voll unter Linux.