Installare il Pterodactyl Panel per i game server

Pterodactyl è l'interfaccia libera più diffusa per i game server. La fama di essere complicato non nasce quasi mai dall'installazione in sé, ma da un singolo malinteso: Pterodactyl non è un programma, sono due. Questa guida separa i due componenti in modo pulito, mostra le differenze tra Debian e Ubuntu e poi passa in rassegna i messaggi di errore che ti spingono a incollarli alla lettera nel motore di ricerca.

Panel e Wings: due programmi, due ruoli

Il Panel è un'applicazione PHP basata su Laravel. Fornisce l'interfaccia web, gestisce utenti, permessi, database e pianificazioni e salva tutto in un proprio database MySQL o MariaDB. Il Panel non avvia mai da solo un game server. Non conosce nemmeno Docker.

Wings è un singolo programma scritto in Go. Gira su ogni macchina su cui devono girare davvero i game server, parla con il daemon Docker, avvia i container, trasmette la console in streaming e mette a disposizione l'accesso SFTP. Wings non ha interfaccia web e non ha database. Resta in ascolto su una porta HTTP e aspetta istruzioni dal Panel.

I due componenti comunicano esclusivamente via HTTP, in entrambe le direzioni, con token firmati. Da qui derivano tre cose che conviene accettare fin dall'inizio:

• Il Panel deve raggiungere il nodo tramite un nome di dominio, non tramite un indirizzo IP. Il certificato è legato al nome.
• Panel e Wings devono parlare lo stesso protocollo. Panel in HTTPS più Wings in HTTP non funziona, il browser blocca la connessione della console.
• Entrambi gli orologi devono essere corretti. I token hanno una durata di pochi minuti.

Chi ha interiorizzato queste tre frasi ha già evitato metà dei problemi tipici di Pterodactyl.

Requisiti e scelta del sistema

Pterodactyl 1.11 e successivi richiede PHP 8.2 oppure 8.3. È il punto in cui la maggior parte delle guide diventa imprecisa, perché le distribuzioni consegnano versioni molto diverse tra loro. Al momento (luglio 2026) la situazione nei repository standard è questa:

Questa guida è pura materia Debian e Ubuntu. Su AlmaLinux, Rocky Linux e Oracle Linux non esiste apt, quindi nessuno dei comandi di pacchetto che seguono è applicabile.

Conseguenza pratica: Debian 12 e Ubuntu 24.04 sono i due sistemi su cui il Panel gira senza repository esterni. Su Ubuntu 22.04 ti serve il PPA di Ondřej Surý, su Debian 13 il suo equivalente per Debian, perché lì è PHP 8.4 a fornire il metapacchetto e il composer.json del Panel richiede esplicitamente ^8.2 || ^8.3. Nella pratica l'esecuzione di Composer sotto PHP 8.4 arriva anche in fondo, ma è terreno non verificato e non è una condizione in cui vuoi far girare un server di produzione. Chi vuole risparmiarsi il repository aggiuntivo prende Debian 12 oppure Ubuntu 24.04.

I due sistemi troppo vecchi, tra l'altro, non falliscono al comando di installazione, ma solo due passi dopo, ed è questo che li rende insidiosi. apt install php arriva in fondo con exit code 0 sia su Ubuntu 22.04 (PHP 8.1.2) sia su Debian 11 (PHP 7.4.33), e solo l'esecuzione di Composer si interrompe, su Ubuntu 22.04 con brick/math requires php (^8.2) failed, su Debian 11 con aws/aws-sdk-php requires php (>=8.1) failed. Se devi restare su uno di questi sistemi, installa dal repository esterno i pacchetti con versione esplicita (php8.3, php8.3-cli, php8.3-fpm e così via) invece del metapacchetto php, altrimenti torna a valere la versione della distribuzione.

Seconda differenza che sorprende con regolarità: Debian non fornisce affatto un pacchetto mysql-server. Lì la scelta obbligata è MariaDB, e va benissimo così, Pterodactyl richiede MariaDB 10.2 o successivi. Chi su Debian digita apt install mysql-server ottiene E: Unable to locate package mysql-server e poi cerca nel posto sbagliato.

Per il nodo con Wings, tra l'altro, queste regole su PHP non valgono affatto. Wings è un programma Go collegato staticamente e ha bisogno solo di Docker e di un kernel ragionevolmente recente. Il nodo può tranquillamente essere Debian 13 mentre il Panel gira su Debian 12.

Installare il Panel

Tutti i comandi che seguono vanno eseguiti come root. Prima i pacchetti di base. Fai attenzione a prendere le estensioni PHP al completo, un php-bcmath mancante salta fuori solo durante l'esecuzione di 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

Verifica subito che la versione sia quella giusta, prima di andare avanti:

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

Poi Composer e i file del 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

Il database. Crea l'utente su 127.0.0.1 e non su localhost, altrimenti entra in gioco l'accesso via socket e più avanti Laravel si becca un rifiuto di accesso anche se la password è corretta. Come distinguere i due casi lo spieghiamo nel nostro articolo su Access denied for user.

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

Il database andrebbe poi messo in sicurezza, e su questo abbiamo un articolo dedicato su come mettere in sicurezza MariaDB e MySQL.

Ora la configurazione vera e propria. I comandi p:environment sono interattivi e chiedono URL del Panel, fuso orario, driver di cache e accesso al database:

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

In p:environment:setup scegli Redis come driver di sessione e di cache, così la coda descritta più avanti funziona in modo pulito. E inserisci l'URL del Panel con https://. Un http:// in questo punto genera poi contenuti misti e una console che aspetta all'infinito la connessione.

nginx e la trappola delle versioni

Le basi della configurazione del web server stanno nel nostro articolo su come installare nginx. Per Pterodactyl contano due dettagli, ed è proprio su questi che i template già pronti trovati in rete falliscono con regolarità.

Primo, il socket PHP-FPM. Il nome del file contiene la versione di PHP e cambia da sistema a sistema. Vai a controllare invece di tirare a indovinare:

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

Su Debian 12 il socket si chiama php8.2-fpm.sock, su Ubuntu 24.04 php8.3-fpm.sock. Un percorso sbagliato qui produce esattamente quella pagina 502 Bad Gateway che in tanti cercano. L'interrogazione dello stato viene prima di proposito: il file socket nasce solo quando il servizio FPM è in esecuzione. Se non è avviato, /run/php/ è vuoto e tu credi erroneamente che il percorso sia sbagliato. Se il servizio non gira ancora, aiuta systemctl enable --now php8.2-fpm con il numero di versione adatto alla tua installazione.

Secondo, la sintassi di HTTP/2. La nuova direttiva http2 on; esiste solo a partire da nginx 1.25.1. Su Debian 12 (1.22), Ubuntu 22.04 (1.18) e anche su Ubuntu 24.04 (1.24) devi usare la forma vecchia listen 443 ssl http2;, altrimenti l'avvio si interrompe con nginx: [emerg] unknown directive "http2". Solo Debian 13 con nginx 1.26 capisce entrambe le forme.

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

Coda e pianificazione

Senza questi due tasselli il Panel sembra funzionante, ma non spedisce email e non esegue nessuna attività pianificata. La struttura del file unit è spiegata in dettaglio nel nostro articolo su come creare un servizio systemd, qui trovi la versione già pronta:

[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

In più una riga nella crontab di root, i dettagli sulla sintassi li trovi nell'articolo Configurare un cronjob su Linux:

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

Installare Wings sul nodo

Da qui in poi lavori sulla macchina che deve eseguire i game server. Può essere lo stesso server, ma non è obbligatorio. Il prerequisito è Docker, la cui configurazione abbiamo descritto nell'articolo Installare Docker su Debian e 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

Sui server ARM il nome del file è wings_linux_arm64. Se scarichi il pacchetto sbagliato, la shell segnala semplicemente cannot execute binary file: Exec format error. Non stupirti dell'output dell'ultima riga: wings version risponde con una doppia v, quindi qualcosa come wings vv1.13.1. Arriva così dal produttore e non è il segno di un'installazione rotta.

Il file /etc/pterodactyl/config.yml non lo scrivi tu. Nasce automaticamente tra poco. Per ora crea soltanto il servizio:

[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

Non avviarlo ancora. Senza configurazione Wings si interrompe subito, con un messaggio che in sostanza segnala l'assenza del file di configurazione sotto /etc/pterodactyl/config.yml. A questo punto è del tutto normale e non è un errore.

Una parola sul file di swap: molte guide più vecchie pretendono swapaccount=1 in /etc/default/grub. Questo riguarda esclusivamente i sistemi con cgroup v1. Debian 12 e 13 così come Ubuntu 22.04 e 24.04 usano cgroup v2 per impostazione predefinita, e lì la voce è superflua. Puoi verificarlo con docker info. Se compare WARNING: No swap limit support, il limite di memoria sullo swap non ha effetto. Come dimensionare in modo sensato lo spazio di swap sta nell'articolo Configurare lo swap.

Certificato per il nodo, non solo per il Panel

L'errore di ragionamento più frequente: ci si procura un certificato per panel.example.com e poi ci si stupisce che il nodo non funzioni. Wings ha bisogno di un certificato proprio per il proprio nome di dominio, per esempio node1.example.com. I due nomi possono puntare allo stesso indirizzo IP, ma restano due nomi distinti.

Su un nodo puro non gira nessun web server, quindi la modalità standalone di Certbot è la strada più semplice. Per farlo la porta 80 deve essere raggiungibile dall'esterno per un breve momento:

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

Chi gestisce molti nodi se la cava meglio con un certificato wildcard, e lo descriviamo nell'articolo Certificato wildcard Let's Encrypt.

Due ostacoli che costano molto tempo:

• Wings legge i file del certificato all'avvio. Dopo un rinnovo il servizio va ricaricato. Metti in /etc/letsencrypt/renewal-hooks/deploy/ un piccolo script con systemctl restart wings. Senza questo il nodo funziona benissimo per 90 giorni e poi cade apparentemente senza motivo.
• Disattiva il proxy Cloudflare per il nome del nodo. La nuvola arancione apre la connessione TLS e sostituisce il certificato. Il Panel riceve così un certificato che non corrisponde all'emittente atteso, e la connessione della console via WebSocket si comporta in modo imprevedibile. Il record A del nodo va tenuto in grigio.

Creare e collegare il nodo

Nel Panel, sotto Admin e Locations, crea prima una località, poi sotto Nodes il nodo. I campi che contano davvero:

• FQDN: node1.example.com, esattamente il nome che sta nel certificato.
• Communicate over SSL: attivo, se il Panel gira in HTTPS. Altrimenti non vale nemmeno la pena di cominciare.
• Behind Proxy: da attivare solo se davanti a Wings c'è davvero un reverse proxy che termina il TLS.
• Daemon Port: 8080. Daemon SFTP Port: 2022.
• Memory e Disk: i limiti che il Panel rispetta quando distribuisce i server.

Dopo il salvataggio apri la scheda Configuration del nodo. Lì il Panel genera un comando con un token monouso. Eseguilo sul nodo:

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

Con questo Wings recupera la propria configurazione completa e scrive /etc/pterodactyl/config.yml. Controlla il contenuto: se nell'indirizzo del Panel trovi http:// invece di https://, hai copiato il comando da un ambiente in cui l'URL del Panel è memorizzato in modo sbagliato. Correggilo alla radice con php artisan p:environment:setup, non a mano nel file YAML.

Poi, nella scheda Allocations, inserisci l'indirizzo IP del nodo e gli intervalli di porte desiderati, per esempio da 25565 a 25600 per Minecraft. Senza almeno un'allocazione libera non si può creare nessun server.

Solo adesso avvia:

systemctl enable --now wings
systemctl status wings

Le porte devono essere aperte nel firewall. Con ufw, le cui basi trattiamo nell'articolo Configurare il firewall ufw:

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

Quando Wings non si collega

Il Panel mostra un simbolo rosso accanto al nodo oppure restituisce un errore quando crei un server. Lavora sui messaggi uno dopo l'altro, sono sorprendentemente chiari.

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

Il server del Panel non raggiunge la porta. O Wings non è in esecuzione, oppure il firewall blocca, oppure il servizio è in ascolto sull'indirizzo sbagliato. Verifica in quest'ordine:

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

E dal server del Panel, questo è il test decisivo:

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

Una risposta HTTP, anche un 404 con contenuto JSON, a questo punto è un successo. Dimostra che DNS, firewall, porta e TLS lavorano insieme.

cURL error 60: SSL certificate problem

Il certificato del nodo non viene accettato. Con self signed certificate stai usando un certificato autofirmato, e il Panel non lo gestisce, perché la libreria sottostante non prevede eccezioni. Con unable to get local issuer certificate manca quasi sempre la catena intermedia, e in quel caso la tua configurazione di Wings punta a cert.pem invece che a fullchain.pem. Con certificate has expired il rinnovo è andato a buon fine, ma Wings tiene ancora in memoria il file vecchio, vedi il punto sul riavvio più sopra.

cURL error 28: Operation timed out

Nessuna risposta, nessun reset. Questo sa di firewall che scarta i pacchetti invece di rifiutarli, oppure di nodo dietro NAT. Un caso particolare: Panel e Wings sullo stesso server, e il Panel contatta il proprio indirizzo IP pubblico. Alcune reti non riportano indietro questo giro. La soluzione è una voce in /etc/hosts sul server del Panel che fa puntare il nome del nodo all'indirizzo interno.

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

Wings gira, Docker no. systemctl status docker chiarisce la cosa in una riga. Il nodo spesso appare comunque raggiungibile nel Panel, perché la richiesta di stato funziona, ma ogni avvio di server fallisce.

Il nodo risponde, ma ogni azione viene rifiutata

Un token non è corretto. Succede dopo un nuovo wings configure con un token vecchio oppure dopo che il nodo è stato cancellato e ricreato nel Panel. Soluzione: nel Panel, nella scheda Configuration, genera un token nuovo, esegui di nuovo il comando e riavvia Wings. Non tirare a indovinare dentro il file YAML.

Per tutti i casi in cui il messaggio resta poco chiaro, ferma il servizio e avvia Wings in primo piano. L'output è molto più loquace del journal:

systemctl stop wings
wings --debug

È utile anche la modalità di report integrata, che raccoglie configurazione, stato di Docker e dati di sistema:

wings diagnostics

Sfasamento di orario tra Panel e nodo

Questo errore è insidioso, perché sembra un problema di rete. Sintomi: il nodo viene mostrato come raggiungibile nel Panel, i server si lasciano creare, ma la console resta bloccata durante l'apertura della connessione e l'accesso SFTP rifiuta credenziali corrette.

Il motivo sta nell'architettura. Il Panel firma token di breve durata, la cui validità si misura in minuti. Wings verifica momento di emissione e scadenza rispetto al proprio orologio. Se i due sistemi divergono di più di qualche minuto, Wings scarta ogni token come scaduto oppure come non ancora valido, anche se è stato appena generato.

Importante per capirsi: non si tratta del fuso orario. Panel e nodo possono avere fusi orari diversi, non ha alcuna importanza. Si tratta dell'istante assoluto. Verifica su entrambe le macchine:

date -u
timedatectl status

Nell'output di timedatectl devono comparire System clock synchronized: yes e NTP service: active. In caso contrario:

timedatectl set-ntp true

Sui sistemi senza systemd-timesyncd, per esempio dopo un'installazione minimale, installa chrony e controlla la sincronizzazione:

apt -y install chrony
chronyc tracking

Il valore accanto a System time dovrebbe stare nell'ordine dei millisecondi. Le macchine virtuali clonate da un'immagine o ripristinate da uno snapshot sono la fonte più frequente di scostamenti importanti.

Da cosa capisci che funziona davvero

Un simbolo verde nel Panel è solo la prima di cinque prove. Percorri la lista, poi lo sai con certezza:

1. systemctl is-active wings restituisce active, e un journalctl -u wings -n 20 non mostra errori ricorrenti.
2. Il nodo, nella panoramica, segnala la capacità reale di memoria e di disco del server di destinazione, non soltanto i limiti inseriti nel Panel. Questi numeri arrivano dal vivo dal nodo e sono la prova che la comunicazione funziona.
3. Crei un server di prova. Nella panoramica attraversa lo stato Installing e poi viene mostrato normalmente. Sul nodo docker ps -a mostra il container corrispondente.
4. Avvii il server e nel browser vedi l'output della console che scorre. Questa è la prova della connessione WebSocket e quindi, allo stesso tempo, del certificato e dell'orario.
5. Ti colleghi via SFTP sulla porta 2022 con le credenziali del Panel e vedi i file del server. Così è confermata anche la seconda porta di Wings.

L'installazione è completa solo quando tutti e cinque i punti tornano. Per esperienza il quarto e il quinto sono quelli che falliscono più spesso, anche se fino a quel momento il Panel sembra del tutto a posto.

Gestire Panel e Wings insieme oppure separati

Entrambe le cose sono possibili. Su un server singolo devi tenere presenti solo due punti: usa due nomi di dominio diversi sullo stesso indirizzo IP, uno per il Panel sulla porta 443 e uno per il nodo sulla porta 8080. E metti in conto che la fame di memoria dei game server rallenta anche il Panel quando lo spazio si fa stretto.

Tenerli separati è comunque la norma a partire dal secondo nodo e ha un effetto collaterale piacevole: un game server sovraccarico oppure sotto attacco non si trascina dietro anche l'interfaccia di amministrazione. Per la messa in sicurezza di base delle due macchine vale la pena dare un'occhiata alla nostra checklist per i nuovi server root e agli articoli su come mettere in sicurezza SSH e su fail2ban.

Per finire un'indicazione pratica per l'esercizio quotidiano: le immagini Docker dei game server portano con sé il proprio ambiente Java. Sul nodo non devi installare Java. Chi comunque vuole provare qualcosa fuori da Pterodactyl trova le strade giuste nei nostri articoli su Java 21 su Debian e sul server Minecraft su Debian. E tieni d'occhio lo spazio su disco, immagini e backup crescono in fretta, e a questo si abbina l'articolo Disco pieno su Linux.