> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ateex.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Pterodactyl Installation Guide

> Step-by-step guide to install Pterodactyl Panel and Wings on Ubuntu 22.04+ with NGINX, MariaDB, PHP, Redis, Docker, and SSL.

# Pterodactyl Installation Guide

Pterodactyl is an open-source game server management panel built with PHP, React, and Go.\
This guide covers **Panel** + **Wings (Daemon)** installation on a fresh **Ubuntu 22.04 / 24.04** server.

***

## Prerequisites

Before you begin, ensure you have:

| Requirement | Description                           |
| ----------- | ------------------------------------- |
| OS          | Ubuntu 22.04+ (root or sudo access)   |
| Web Server  | NGINX (recommended)                   |
| Database    | MariaDB or MySQL                      |
| PHP         | 8.2 or newer with required extensions |
| Redis       | Installed and running                 |
| Docker      | Required for Wings                    |
| Domain      | Example: `panel.example.com`          |
| SSL         | Let’s Encrypt or manual               |

### Install System Dependencies

```bash theme={null}
sudo apt update && sudo apt upgrade -y
sudo apt install -y software-properties-common curl apt-transport-https ca-certificates gnupg lsb-release
```

Add PHP and Redis repositories:

```bash theme={null}
LC_ALL=C.UTF-8 sudo add-apt-repository ppa:ondrej/php -y
curl -fsSL https://packages.redis.io/gpg | sudo 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" | sudo tee /etc/apt/sources.list.d/redis.list
sudo apt update
```

Install required packages:

```bash theme={null}
sudo apt install -y nginx mariadb-server redis-server tar unzip git composer php8.2 php8.2-{cli,common,gd,mbstring,bcmath,xml,fpm,curl,zip,tokenizer}
```

***

## Step 1: Configure MariaDB

Log into MySQL and create a database + user:

```bash theme={null}
sudo mysql -u root
```

```sql theme={null}
CREATE DATABASE pterodactyl;
CREATE USER 'ptero'@'127.0.0.1' IDENTIFIED BY 'StrongPasswordHere';
GRANT ALL PRIVILEGES ON pterodactyl.* TO 'ptero'@'127.0.0.1';
FLUSH PRIVILEGES;
EXIT;
```

***

## Step 2: Install the Panel

```bash theme={null}
cd /var/www/
curl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz
tar -xzvf panel.tar.gz
mv panel pterodactyl
cd pterodactyl
```

Install dependencies:

```bash theme={null}
cp .env.example .env
composer install --no-dev --optimize-autoloader
php artisan key:generate --force
```

### Configure Environment

Open `.env` and edit database + app settings:

```bash theme={null}
nano .env
```

Example values:

```
APP_URL=https://panel.example.com
APP_TIMEZONE=UTC
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=pterodactyl
DB_USERNAME=ptero
DB_PASSWORD=StrongPasswordHere
```

Migrate and seed the database:

```bash theme={null}
php artisan migrate --seed --force
```

### Set Permissions

```bash theme={null}
chown -R www-data:www-data /var/www/pterodactyl
chmod -R 755 /var/www/pterodactyl
```

***

## Step 3: NGINX Configuration

Create new site config:

```bash theme={null}
sudo nano /etc/nginx/sites-available/pterodactyl.conf
```

Paste this:

```nginx theme={null}
server {
    listen 80;
    server_name panel.example.com;

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

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

    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
    }

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

Enable the site:

```bash theme={null}
sudo ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

***

## Step 4: Secure with SSL

Install Certbot and generate certificates:

```bash theme={null}
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d panel.example.com
```

Auto-renew setup:

```bash theme={null}
sudo crontab -e
# Add the line below:
0 23 * * * certbot renew --quiet --deploy-hook "systemctl reload nginx"
```

***

## Step 5: Setup Cron & Queue

Add to crontab:

```bash theme={null}
* * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1
```

(Optional) Start queue worker manually:

```bash theme={null}
php artisan queue:work --daemon
```

***

## Step 6: Install Wings (Daemon)

### Install Docker

```bash theme={null}
curl -fsSL https://get.docker.com | sh
systemctl enable --now docker
```

### Install Wings

```bash theme={null}
mkdir -p /etc/pterodactyl
cd /etc/pterodactyl
curl -Lo wings https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_amd64
chmod +x wings
```

### Configure Wings

In your **Panel → Nodes → Configuration**, copy the generated YAML config and paste it into:

```bash theme={null}
nano /etc/pterodactyl/config.yml
```

### Create Systemd Service

```bash theme={null}
sudo nano /etc/systemd/system/wings.service
```

Paste:

```ini theme={null}
[Unit]
Description=Pterodactyl Wings
After=docker.service

[Service]
User=root
WorkingDirectory=/etc/pterodactyl
ExecStart=/etc/pterodactyl/wings
Restart=always
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash theme={null}
systemctl enable wings
systemctl start wings
```

***

## Step 7: Access Panel

Open your browser and go to:

```
https://panel.example.com
```

You’ll be guided through initial setup.

***

## Troubleshooting

| Problem                    | Solution                                    |
| -------------------------- | ------------------------------------------- |
| 502 Bad Gateway            | Check `php8.2-fpm` service and NGINX config |
| Database connection failed | Verify `.env` credentials                   |
| Wings not connecting       | Check node token and domain SSL             |
| Permission errors          | Ensure correct file ownership (`www-data`)  |

***

## References

* [Official Pterodactyl Docs](https://pterodactyl.io)
* [Panel Installation Guide](https://pterodactyl.io/panel/1.0/getting_started.html)
* [Wings Installation Guide](https://pterodactyl.io/wings/1.0/installing.html)
* [Docker Installation Docs](https://docs.docker.com/engine/install/)

***

> **Tip:**
> For faster installs, check out [pterodactyl-installer](https://github.com/pterodactyl-installer/pterodactyl-installer) (unofficial).

***

**Your panel is now live!**
Login at your domain, connect nodes, and start deploying game servers.