Pterodactyl Panel Kurulumu: Sıfırdan Tam Rehber

Pterodactyl panel kurulumu, kendi sunucunuz üzerinde birden fazla oyun sunucusunu web arayüzünden yönetmenin en yaygın yoludur. Bu rehberde Ubuntu 24.04 LTS üzerinde sıfırdan başlayıp Panel 1.15.0 ve Wings daemon’unu kuracak, Nginx ile SSL sertifikasını yapılandıracak, ilk node’u tanımlayacak ve Minecraft 26.2 sunucusunu panelden ayağa kaldıracağız. Kurulum uçtan uca yaklaşık 40 dakika sürer ve tamamı komut satırından yapılır.

Pterodactyl MIT lisanslı, tamamen ücretsiz ve açık kaynak bir oyun sunucusu yönetim panelidir. Her oyun sunucusunu ayrı bir Docker konteynerinde izole çalıştırır; böylece bir sunucu çöktüğünde diğerleri etkilenmez, her sunucuya ayrı RAM, CPU ve disk sınırı verilebilir. Minecraft dışında Rust, ARK, CS2, FiveM, Terraria ve onlarca oyun için hazır “egg” tanımları vardır.

Pterodactyl nasıl çalışır: Panel, Wings ve Docker#

Kuruluma başlamadan mimariyi anlamak, ilerideki hataların yarısını baştan çözer. Sistem üç katmandan oluşur:

Panel

Laravel tabanlı web uygulaması. Kullanıcılar, sunucular, node’lar, yetkiler ve zamanlanmış görevler burada tutulur. Oyun sunucularını kendisi çalıştırmaz, yalnızca yönetir. MariaDB ve Redis ister.

Wings

Node makinelerinde çalışan Go ile yazılmış daemon. Panel’den gelen API isteklerini alır, Docker konteynerlerini oluşturur, konsol çıktısını websocket üzerinden panele akıtır, SFTP sunucusunu 2022 portunda yayınlar.

Docker

Her oyun sunucusu, seçilen egg’in tanımladığı imajda ayrı bir konteyner olarak çalışır. Java sürümü de bu imajla gelir; node makinesine Java kurmanıza gerek yoktur.

Panel ve Wings aynı makinede olabilir (tek sunucu kurulumu) ya da panel küçük bir VDS’te, oyun sunucuları güçlü makinelerde durabilir (çoklu node kurulumu). Yeni başlıyorsanız ikisini aynı makinede kurun; ileride node eklemek panelden birkaç tıklamalık iştir. Docker’ın nasıl çalıştığına dair temel bilgi için Docker ile Minecraft sunucusu kurma sayfasına göz atabilirsiniz.

Donanım ve yazılım gereksinimleri#

Panel’in kendisi hafiftir; ağır iş oyun sunucularındadır. Kaynak planlamasını oyun sunucularının toplam ihtiyacına göre yapın ve panel için üstüne 2 GB ekleyin.

İşlemci seçiminde çekirdek sayısı değil saat hızı belirleyicidir; Minecraft’ın ana tick döngüsü tek çekirdekte döner. Bu yüzden düşük frekanslı çok çekirdekli sunucu işlemcileri yerine yüksek saat hızlı AMD Ryzen 9 modellerini tercih edin. Disk mutlaka NVMe SSD olmalı; panel her sunucunun dosyalarını /var/lib/pterodactyl/volumes altında tutar ve eşzamanlı chunk yazımı SATA SSD’de bile darboğaz yapar. Panel birden fazla sunucuyu aynı diske yazacağı için burada yapılan tasarruf doğrudan TPS olarak geri döner.

Yazılım tarafında Panel 1.15.0’ın istedikleri şunlardır:

Kurulum öncesi hazırlık ve DNS#

Sunucunuza root veya sudo yetkili bir kullanıcıyla SSH ile bağlanın; adımları bilmiyorsanız SSH ile sunucuya bağlanma rehberi ve taze bir makine için Ubuntu Server kurulumu ve ilk yapılandırma sayfaları işinizi görür. Sunucuyu ilk kez alıyorsanız VDS aldıktan sonra yapılması gereken ilk ayarları mutlaka uygulayın.

DNS tarafında iki A kaydı oluşturun ve yayılmasını bekleyin:

İndirmeniz gerekenler#

Adım adım Panel kurulumu#

1. Depoları ekleyin ve bağımlılıkları kurun#

   PHP 8.3 için ondrej deposunu, güncel Redis için resmî depoyu ekleyin:

   sudo apt update && sudo apt -y upgrade
   sudo apt -y install software-properties-common curl apt-transport-https ca-certificates gnupg lsb-release
   sudo add-apt-repository -y ppa:ondrej/php
   sudo apt update
   sudo apt -y install php8.3 php8.3-cli php8.3-common 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 redis-server tar unzip git
   curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

2. MariaDB’yi güvenli hâle getirin ve veritabanını açın#

   Önce sudo mysql_secure_installation çalıştırıp root parolası belirleyin, anonim kullanıcıları ve test veritabanını kaldırın. Ardından panel için ayrı bir kullanıcı ve veritabanı oluşturun:

   sudo mysql -u root -p

   CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'buraya-uzun-rastgele-parola';
   CREATE DATABASE panel CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1' WITH GRANT OPTION;
   FLUSH PRIVILEGES;
   EXIT;

3. Panel dosyalarını indirin#

   Dosyalar /var/www/pterodactyl altına açılır:

   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/
   sudo rm panel.tar.gz

4. Bağımlılıkları yükleyin ve anahtarı üretin#

   Composer’ı üretim modunda çalıştırın, sonra uygulama anahtarını oluşturun:

   sudo cp .env.example .env
   sudo composer install --no-dev --optimize-autoloader
   sudo php artisan key:generate --force

   UyarıAPP_KEY üretildikten sonra bir daha değiştirmeyin. Bu anahtar veritabanındaki şifrelenmiş alanları (node token’ları, veritabanı parolaları) çözer; kaybederseniz tüm node bağlantılarını yeniden kurmanız gerekir. .env dosyasını yedeklerinize dahil edin.

5. Ortam yapılandırmasını yapın#

   Üç interaktif komut sırayla temel ayarları, veritabanı bilgilerini ve e-posta gönderimini sorar:

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

   İlk komutta uygulama adresini https://panel.alanadiniz.com, saat dilimini Europe/Istanbul, önbellek, oturum ve kuyruk sürücülerinin üçünü de redis olarak seçin. Redis ana makinesi 127.0.0.1, portu 6379, parolası boş kalabilir.

6. Veritabanı tablolarını oluşturun ve yönetici hesabı açın#

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

   p:user:make komutu yönetici olup olmadığını, e-posta adresini, kullanıcı adını ve parolayı sorar. İlk soruya yes deyin, aksi halde panele girdiğinizde yönetim menüsünü göremezsiniz.

7. Dosya sahipliğini web sunucusuna verin#

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

8. Cron görevini ve kuyruk işçisini kurun#

   Zamanlanmış görevler, otomatik yedekler ve sunucu yeniden başlatmaları bu ikisine bağlıdır. Önce sudo crontab -e ile şu satırı ekleyin:

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

   Sonra sudo nano /etc/systemd/system/pteroq.service dosyasını oluşturun:

   [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
   sudo systemctl status pteroq.service --no-pager

Nginx ve SSL sertifikası yapılandırması#

Panel’i HTTPS olmadan yayınlamayın. Önce sertifikayı alın, sonra Nginx site dosyasını yazın.

sudo apt -y install certbot python3-certbot-nginx
sudo rm -f /etc/nginx/sites-enabled/default
sudo certbot certonly --nginx -d panel.alanadiniz.com

sudo nano /etc/nginx/sites-available/pterodactyl.conf dosyasını oluşturup aşağıdaki yapılandırmayı yazın:

server {
    listen 80;
    server_name panel.alanadiniz.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name panel.alanadiniz.com;

    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.alanadiniz.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/panel.alanadiniz.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;

    add_header X-Content-Type-Options nosniff;
    add_header X-Frame-Options DENY;
    add_header Referrer-Policy same-origin;

    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 /etc/nginx/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_read_timeout 300;
    }

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

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

Tarayıcıdan https://panel.alanadiniz.com adresine gidin; giriş ekranını görüyorsanız Panel tarafı bitti. Sertifika yenilemesinin otomatik çalıştığını sudo certbot renew --dry-run ile doğrulayın. HTTPS geçişinin genel mantığı için SSL sertifikası kurulumu sayfasına bakabilirsiniz.

Wings daemon kurulumu#

Wings, oyun sunucularının fiilen çalıştığı makinede kurulur. Tek makineli kurulumda bu aynı sunucudur.

1. Docker’ı kurun#

   curl -fsSL https://get.docker.com | sudo sh
   sudo systemctl enable --now docker

2. Wings ikili dosyasını indirin#

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

3. Node için SSL sertifikası alın#

   Node FQDN’i için ayrı bir sertifika gerekir. 80 portu Nginx tarafından kullanılıyorsa webroot, kullanılmıyorsa standalone yöntemini seçin:

   sudo certbot certonly --standalone -d node.alanadiniz.com

4. Wings servisini tanımlayın#

   sudo nano /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

   Servisi henüz başlatmayın; önce panelden node oluşturup yapılandırma dosyasını almanız gerekiyor.

Node oluşturma ve yapılandırmayı taşıma#

Panele yönetici hesabınızla girin ve Admin → Locations → Create New yolundan bir konum ekleyin (örneğin tr-ist). Ardından Admin → Nodes → Create New ekranını doldurun:

Node kaydedildikten sonra node sayfasındaki Configuration sekmesine geçin. Burada hazır bir config.yml ve onu otomatik yazan bir komut bulunur. Komutu node makinesinde çalıştırın, sonra Wings’i deneme kipinde başlatın:

sudo wings --debug

Çıktıda hata yoksa Ctrl+C ile durdurup servisi kalıcı hâle getirin:

sudo systemctl enable --now wings
sudo systemctl status wings --no-pager
sudo journalctl -u wings -f

Panelde node’un yanındaki kalp simgesi yeşile döndüğünde bağlantı kurulmuştur. Son adım olarak node’un Allocation sekmesinden IP ve port aralığını tanımlayın: IP alanına sunucunun genel IP’sini, port alanına 25565-25580 gibi bir aralık yazın. Her oyun sunucusu bu havuzdan bir port alır.

Minecraft 26.2 sunucusu oluşturma ve Java 25 ayarı#

Admin → Servers → Create New ekranından ilk sunucuyu oluşturun. Nest olarak Minecraft, egg olarak Paper seçin. Kaynak alanlarında bellek ve disk sınırını girin: 2–10 oyunculu bir sunucu için 8192 MB bellek ve 51200 MB disk uygun bir başlangıçtır.

Bu noktada rehberlerin çoğunun atladığı kritik ayar geliyor. Minecraft 26.1 ve 26.2 Java 25 ister; egg’in Docker imaj listesinde Java 25 imajı yoksa sunucu açılışta UnsupportedClassVersionError verir. Admin → Nests → Minecraft → Paper → Docker Images alanına şu satırın eklendiğinden emin olun:

Java 25|ghcr.io/pterodactyl/yolks:java_25
Java 21|ghcr.io/pterodactyl/yolks:java_21
Java 17|ghcr.io/pterodactyl/yolks:java_17
Java 8|ghcr.io/pterodactyl/yolks:java_8

Sunucu düzenleme ekranındaki Startup sekmesinden doğru imajı seçin. Hangi Minecraft sürümünün hangi Java’yı istediğini Java sürümü gereksinim tablosunda bulabilirsiniz:

Startup komutunu da elle düzeltmenizi öneririz. Varsayılan egg komutu belleği yüzdeyle hesaplar; sabit değer vermek daha öngörülebilir sonuç verir:

java -Xms6G -Xmx6G -XX:+UseG1GC -XX:+ParallelRefProcEnabled \
  -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC \
  -XX:+AlwaysPreTouch -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 \
  -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:G1HeapWastePercent=5 \
  -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 \
  -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 \
  -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 \
  -Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true \
  -jar {{SERVER_JARFILE}} nogui

Yukarıdaki bayrak seti Aikar’s Flags olarak bilinir ve 26.x sunucularında hâlâ geçerlidir. 26.1 ile duyurulan G1GC’den ZGC’ye geçişin istemci tarafı bir değişiklik olduğunu, sunucu jar’ının çöp toplayıcısını tamamen sizin verdiğiniz bayrakların belirlediğini unutmayın. 16 GB ve üzeri heap veya ağır modpack çalıştırıyorsanız bu bayrakları kaldırıp yalnızca -XX:+UseZGC deneyebilirsiniz; -XX:+ZGenerational bayrağı Java 25’te obsolete olduğu için yazmayın.

Güvenlik duvarı ve port listesi#

Panel ve node üzerinde aşağıdaki portların açık olması gerekir. Fazlasını açmayın; MariaDB ve Redis dışarıya kapalı kalsın.

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 8080/tcp
sudo ufw allow 2022/tcp
sudo ufw allow 25565:25580/tcp
sudo ufw enable
sudo ufw status numbered

Kural yazımının ayrıntıları ve iptables tarafı için sunucu güvenlik duvarı yapılandırması sayfasına bakın. Panelin yönetim arayüzünü yalnızca kendi IP’nize açmak isterseniz 443 kuralını sudo ufw allow from IP_ADRESINIZ to any port 443 biçiminde daraltabilirsiniz; ancak oyuncularınız panele erişecekse bunu yapmayın.

Panel ve Wings güncelleme#

Güncelleme öncesi mutlaka veritabanı yedeği alın. Migration adımı geri alınabilir değildir.

mysqldump -u pterodactyl -p panel > ~/panel-$(date +%F).sql
cd /var/www/pterodactyl
sudo php artisan down
sudo curl -L https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz | sudo tar -xzv
sudo chmod -R 755 storage/* bootstrap/cache
sudo composer install --no-dev --optimize-autoloader
sudo php artisan view:clear && sudo php artisan config:clear
sudo php artisan migrate --seed --force
sudo chown -R www-data:www-data /var/www/pterodactyl/*
sudo systemctl restart pteroq
sudo php artisan up

Wings güncellemesi daha basittir: servisi durdurun, ikili dosyayı yeniden indirin, başlatın.

sudo systemctl stop wings
sudo curl -Lo /usr/local/bin/wings \
  "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_amd64"
sudo chmod u+x /usr/local/bin/wings
sudo systemctl start wings

Panel’in kendi yedekleme özelliği (node başına yerel arşiv veya S3) sunucu dosyalarını kapsar ama panel veritabanını kapsamaz. İkisini birlikte planlayın; yaklaşım ve saklama süreleri için Minecraft sunucu yedekleme rehberine bakın.

Sık karşılaşılan hatalar ve çözümleri#

Oyun tarafındaki hatalar için Minecraft sunucu hataları ve çözümleri sayfası daha kapsamlı bir kaynak. Panel arayüzünün günlük kullanımı, kullanıcı yetkileri, zamanlanmış görevler ve alt kullanıcı yönetimi ayrı bir rehberin konusu.

Pterodactyl mi, Pelican mı, Crafty mi, AMP mi?#

Panel seçimi kurulum kolaylığı ile esneklik arasında bir tercihtir. Dördü de aktif projelerdir:

Panel kurup bakımını üstlenmek istemiyorsanız hazır web panelli çözümler de var. Batihost’un 156 TL’den başlayan Minecraft sunucu paketleri panel dahil gelir; kendi panelinizi kurmak istiyorsanız Ryzen tabanlı yüksek frekanslı VDS ya da çok node’lu kurulumlar için dedicated sunucu seçenekleri uygundur.

Kurulum sonrası kontrol listesi#

• Panel HTTPS üzerinden açılıyor ve sertifika geçerli.
• sudo systemctl status pteroq wings nginx mariadb redis-server çıktısında beşi de active (running).
• sudo crontab -l çıktısında schedule:run satırı var.
• Node’un kalp simgesi yeşil, allocation aralığı tanımlı.
• Test sunucusu java_25 imajıyla açılıyor, konsolda “Done” satırı görünüyor.
• SFTP ile 2022 portundan dosya yükleyebiliyorsunuz.
• Veritabanı yedeği ve .env dosyası sunucu dışında bir yerde duruyor.

Özetle#

Pterodactyl panel kurulumu, sırayla gidildiğinde uzun ama karmaşık olmayan bir iştir: bağımlılıkları kurun, veritabanını açın, panel dosyalarını yerleştirin, ortam yapılandırmasını yapın, cron ve kuyruk işçisini tanımlayın, Nginx ile SSL’i bağlayın, ardından Wings’i kurup node’u panele tanıtın. En çok zaman kaybettiren nokta kurulumun kendisi değil, node sertifikası ve 8080 portudur; bu ikisini baştan doğru yaparsanız “Wings offline” sorunuyla hiç uğraşmazsınız.

Minecraft tarafında ise tek kritik ayar Java sürümüdür. 26.1 ve 26.2 Java 25 ister; egg’in Docker imaj listesine java_25 satırını ekleyip Startup sekmesinden seçmeyi unutmayın. Bellek tahsisinde de heap ile konteyner limiti arasında pay bırakın: 8 GB tahsiste 6G, 12 GB’ta 10G, 16 GB’ta 14G heap doğru orandır. Kurulum bittikten sonra panelin günlük kullanımı için kullanım rehberine, sunucu performansını yükseltmek için optimizasyon rehberine geçebilirsiniz.