Instalace Pterodactyl Panelu krok za krokem na Ubuntu

Pterodactyl je open-source panel pro správu herních serverů. Skládá se ze dvou částí: Panelu (webové rozhraní v PHP/Laravelu) a Wings (démon na každém nodu, který spouští servery v Dockeru). Tento návod pokrývá jen Panel – Wings a propojení nodu řešíme v samostatném článku Instalace Wings a propojení nodu.

Postup vychází z oficiální dokumentace na pterodactyl.io pro Panel 1.x. Před instalací si vždy zkontrolujte aktuální verzi dokumentace – požadavky se mezi verzemi mění.

Co budete potřebovat

Komponenta	Požadavek
PHP	8.1–8.3 s rozšířeními cli, openssl, gd, mysql, PDO, mbstring, tokenizer, bcmath, xml/dom, curl, zip, fpm
Databáze	MySQL 5.7.22+ nebo MariaDB 10.2+
Cache a fronta	Redis
Webserver	nginx (nebo Apache/Caddy)
Nástroje	curl, tar, unzip, git, Composer v2

Doménu (např. panel.example.cz) nasměrujte A záznamem na IP serveru ještě před instalací – usnadní to pozdější SSL.

1. Instalace závislostí

Na Ubuntu 24.04 je PHP 8.3 přímo v repozitářích:

sudo apt update
sudo apt install -y php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} \
  mariadb-server nginx tar unzip git redis-server curl

Composer v2 nainstalujete oficiálním instalátorem:

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

2. Stažení Panelu

Panel patří do /var/www/pterodactyl:

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

3. Databáze

sudo mariadb -u root

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

Heslo si uložte, budete ho za chvíli zadávat.

4. Konfigurace prostředí

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

Důležité: hodnotu APP_KEY ze souboru .env si zálohujte mimo server. Bez ní nelze dešifrovat uložená data (např. API klíče nodů) a obnova ze zálohy databáze by nefungovala.

Následují interaktivní průvodci:

sudo php artisan p:environment:setup     # URL panelu, cache/session/queue = redis
sudo php artisan p:environment:database  # host 127.0.0.1, DB panel, uživatel pterodactyl
sudo php artisan p:environment:mail      # SMTP pro e-maily (lze přeskočit a doplnit později)

U p:environment:setup zadejte URL přesně tak, jak ji budete používat, včetně https://. Špatná URL je nejčastější příčinou pozdějších CORS chyb.

Migrace databáze a první administrátor:

sudo php artisan migrate --seed --force
sudo php artisan p:user:make

Nakonec nastavte vlastníka souborů pro webserver:

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

5. Cron a queue worker pteroq

Panel potřebuje plánovač úloh. Otevřete sudo crontab -e a přidejte:

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

Frontu (instalace serverů, e-maily, plánované úlohy) zpracovává worker. Vytvořte /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

sudo systemctl enable --now redis-server
sudo systemctl enable --now pteroq.service

6. nginx

Soubor /etc/nginx/sites-available/pterodactyl.conf (zjednodušená HTTP verze, SSL doplníte podle návodu na SSL):

server {
    listen 80;
    server_name panel.example.cz;
    root /var/www/pterodactyl/public;
    index index.php;

    client_max_body_size 100m;

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

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

Cestu k socketu upravte podle verze PHP (php8.1-fpm.sock, php8.2-fpm.sock…).

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

7. Ověření

systemctl status pteroq – musí být active (running).
redis-cli ping – odpověď PONG.
Otevřete doménu v prohlížeči a přihlaste se účtem z p:user:make.
Při chybě 500 se podívejte do /var/www/pterodactyl/storage/logs/ – nejnovější laravel-*.log obvykle řekne přesně, co chybí.

Časté chyby při instalaci

Bílá stránka nebo 502 – nesedí cesta k PHP-FPM socketu v nginx konfiguraci.
Permission denied v logu – zapomenutý chown na www-data.
Servery se „věčně instalují“ – neběží pteroq nebo Redis.

Až Panel běží, pokračujte instalací Wings na node. Pokud se v některém kroku zaseknete, můžete chybový výpis vložit do ColdHost AI v režimu Server a DevOps – po připojení VPS přes SSH vám navrhne diagnostické příkazy, které každý zvlášť schválíte.