Create pterodactyl-docs.md

This commit is contained in:
Muhammad Tamir
2025-11-20 13:30:44 +07:00
parent 07c2220f81
commit b54ca14a1e

View File

@@ -0,0 +1,776 @@
```markdown
# Pterodactyl Knowledge Base
## Table of Contents
- [Introduction](#introduction)
- [About Pterodactyl](#about-pterodactyl)
- [Key Features](#key-features)
- [Installation Guides](#installation-guides)
- [Panel Installation](#panel-installation)
- [Wings Installation](#wings-installation)
- [Webserver Configuration](#webserver-configuration)
- [Community Guides and Tutorials](#community-guides-and-tutorials)
- [Creating a New Node](#creating-a-new-node)
- [Creating a Custom Docker Image](#creating-a-custom-docker-image)
- [Creating a Custom Egg](#creating-a-custom-egg)
- [Operating System Specific Installations](#operating-system-specific-installations)
- [Enterprise Linux 8 and Fedora Server 40](#enterprise-linux-8-and-fedora-server-40)
- [Debian 11, 12 & 13](#debian-11-12-13)
- [CentOS 7](#centos-7)
- [Advanced Configurations](#advanced-configurations)
- [Using Mounts](#using-mounts)
- [Upgrading PHP](#upgrading-php)
- [Development and Customization](#development-and-customization)
- [Building Wings](#building-wings)
- [Building Panel Assets](#building-panel-assets)
- [Legacy Upgrades](#legacy-upgrades)
- [Kernel Modifications](#kernel-modifications)
## Introduction
Welcome to the Pterodactyl Knowledge Base. This document provides structured information on installing, configuring, and using Pterodactyl, a game server management panel.
## About Pterodactyl
**Pterodactyl®** is a free, open-source game server management panel built with PHP, React, and Go. It runs all game servers in isolated Docker containers for security, providing a user-friendly interface.
## Key Features
- **Security First**: Uses bcrypt hashing, AES-256-CBC encryption, and HTTPS support.
- **Modern Tooling**: Built on a modern stack with best design practices.
- **Docker to the Core**: Runs all servers in isolated Docker containers.
- **Free & Open Source**: Fully open source under a MIT license.
- **User Friendly**: Intuitive interface for easy management.
- **Scalable**: Suitable for hosting companies and personal use.
## Installation Guides
### Panel Installation
- **Current Version**: 1.11
- **Getting Started**: Includes webserver configuration, additional configuration, updating, and troubleshooting.
### Wings Installation
- **Current Version**: 1.11
- **Installation**: Instructions for installing, upgrading, and migrating to Wings.
### Webserver Configuration
- Prepare SSL certificates before configuring NGINX or Apache.
- Use Caddy for automatic SSL management if needed.
- Specific configurations provided for NGINX and Apache.
## Community Guides and Tutorials
### Creating a New Node
- **Location Information Required**: Name, description, location, FQDN, SSL communication, server directory, memory, and disk space allocations.
- **Installation**: Install the Daemon and configure the node.
### Creating a Custom Docker Image
- **Dockerfile Creation**: Use Alpine Linux, install dependencies, create a container user, and set the work directory and entrypoint.
- **Entrypoint Script**: Modify startup commands and run the server.
### Creating a Custom Egg
- **Service Creation**: Create new options, configure process management, stop commands, log storage, and configuration files.
- **Variables**: Define specific variables and permissions for users.
## Operating System Specific Installations
### Enterprise Linux 8 and Fedora Server 40
- **Dependencies**: Install Docker and configure firewall.
- **Wings Installation**: Follow official documentation.
### Debian 11, 12 & 13
- **Dependencies**: Install PHP, MariaDB, Redis, and other necessary packages.
- **Installation**: Follow official documentation for further steps.
### CentOS 7
- **Dependencies**: Install Docker, configure SELinux, and set up the firewall.
- **Panel Installation**: Follow official documentation for further steps.
## Advanced Configurations
### Using Mounts
- **Configuration**: Specify mountable directories in the Wings configuration.
- **Panel Setup**: Configure mounts in the admin panel for server use.
### Upgrading PHP
- **Version Requirements**: Reference table for PHP versions by panel version.
- **Installation**: Commands to add repositories and install PHP 8.3.
## Development and Customization
### Building Wings
- **Build Requirements**: Requires Go programming knowledge.
- **Process**: Compile Wings and install the binary.
### Building Panel Assets
- **Dependencies**: NodeJS and Yarn required.
- **Build Process**: Rebuild the Panel frontend using Yarn.
## Legacy Upgrades
- **Version Transition**: Guide for upgrading from 0.7.X to 1.3.x.
- **Maintenance Mode**: Enter maintenance mode before upgrading dependencies.
## Kernel Modifications
- **Update Process**: Install new kernels and update GRUB.
- **Verification**: Confirm kernel installation and set default boot.
For more detailed information and additional sections, please refer to the official Pterodactyl documentation and community guides.
```
```markdown
# Pterodactyl Knowledge Base
This structured knowledge base provides detailed instructions and information for installing, configuring, and troubleshooting Pterodactyl Panel and related components.
## Table of Contents
- [Installation](#installation)
- [Download Files](#download-files)
- [Installation Process](#installation-process)
- [Environment Configuration](#environment-configuration)
- [Queue Listeners](#queue-listeners)
- [Enterprise Linux 8 and Fedora Server 40](#enterprise-linux-8-and-fedora-server-40)
- [Install Dependencies](#install-dependencies)
- [PHP Configuration](#php-configuration)
- [Additional Configuration](#additional-configuration)
- [Backups](#backups)
- [Reverse Proxy Setup](#reverse-proxy-setup)
- [reCAPTCHA](#recaptcha)
- [Telemetry](#telemetry)
- [Updating the Panel](#updating-the-panel)
- [Panel Version Requirements](#panel-version-requirements)
- [Manual Upgrade](#manual-upgrade)
- [Standalone SFTP Server](#standalone-sftp-server)
- [Webserver Configuration](#webserver-configuration)
- [Community Standards](#community-standards)
- [Terminology](#terminology)
- [Migrating to Wings](#migrating-to-wings)
- [Troubleshooting](#troubleshooting)
- [About](#about)
- [Core Project Team](#core-project-team)
- [Sponsors](#sponsors)
- [License](#license)
- [Creating SSL Certificates](#creating-ssl-certificates)
## Installation
### Download Files
1. **Create Directory**: Create a directory for the panel and navigate to it.
```bash
mkdir -p /var/www/pterodactyl
cd /var/www/pterodactyl
```
2. **Download Panel Files**: Use `curl` to download the panel files and set permissions.
```bash
curl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz
tar -xzvf panel.tar.gz
chmod -R 755 storage/* bootstrap/cache/
```
### Installation Process
1. **Database Setup**: Create a database and user with the necessary permissions.
```sql
CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'yourPassword';
CREATE DATABASE panel;
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1' WITH GRANT OPTION;
```
2. **Install Core Dependencies**: Copy environment settings and install dependencies.
```bash
cp .env.example .env
COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader
```
3. **Generate Encryption Key**: Generate a new encryption key.
```bash
php artisan key:generate --force
```
4. **Environment Setup**: Configure sessions, caching, and email sending.
```bash
php artisan p:environment:setup
php artisan p:environment:database
php artisan p:environment:mail
```
5. **Database Migration**: Set up the database tables.
```bash
php artisan migrate --seed --force
```
6. **Create Admin User**: Create an administrative user.
```bash
php artisan p:user:make
```
7. **Set File Permissions**: Set the correct permissions for the webserver.
```bash
chown -R www-data:www-data /var/www/pterodactyl/*
```
### Queue Listeners
- **Crontab Configuration**: Add a cronjob for processing tasks.
```bash
* * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1
```
- **Queue Worker**: Create a systemd worker for the queue process.
## Enterprise Linux 8 and Fedora Server 40
### Install Dependencies
1. **Update System**:
```bash
sudo dnf update -y
```
2. **Install Repositories**:
```bash
sudo dnf install -y epel-release
sudo dnf install -y https://rpms.remirepo.net/enterprise/remi-release-8.rpm
```
3. **Enable PHP 8.3**:
```bash
sudo dnf module reset php
sudo dnf module enable php:remi-8.3 -y
```
4. **Install Dependencies**:
```bash
sudo dnf install -y php php-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb mariadb-server nginx redis zip unzip tar
```
5. **Enable Services**:
```bash
sudo systemctl enable --now mariadb nginx redis
```
6. **Firewall Configuration**:
```bash
sudo firewall-cmd --add-service=http --permanent
sudo firewall-cmd --add-service=https --permanent
sudo firewall-cmd --reload
```
### PHP Configuration
- **Create PHP-FPM Configuration**:
```ini
[pterodactyl]
user = nginx
group = nginx
listen = /var/run/php-fpm/pterodactyl.sock
listen.owner = nginx
listen.group = nginx
listen.mode = 0750
pm = ondemand
pm.max_children = 9
pm.process_idle_timeout = 10s
pm.max_requests = 200
```
- **Start PHP-FPM**:
```bash
sudo systemctl enable --now php-fpm
```
## Additional Configuration
### Backups
- **Local Backups**: Set the backup driver in `.env`.
```env
APP_BACKUP_DRIVER=wings
```
- **S3 Backups**: Configure S3 settings in `.env`.
```env
APP_BACKUP_DRIVER=s3
AWS_DEFAULT_REGION=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_BACKUPS_BUCKET=
AWS_ENDPOINT=
```
### Reverse Proxy Setup
- **Modify `.env` for Proxies**:
```env
TRUSTED_PROXIES=127.0.0.1
```
- **NGINX Configuration**:
```nginx
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
```
### reCAPTCHA
- **Configuring reCAPTCHA**: Generate and apply your own keys in the admin panel.
- **Disable reCAPTCHA**: Use the admin panel to disable reCAPTCHA if necessary.
### Telemetry
- **How It Works**: Telemetry collects anonymous usage data to help improve the software.
- **Enabling/Disabling Telemetry**:
```env
PTERODACTYL_TELEMETRY_ENABLED=true
```
## Updating the Panel
### Panel Version Requirements
- Ensure your Wings version matches the Panel version. Supported PHP versions vary by Panel version.
### Manual Upgrade
1. **Enter Maintenance Mode**:
```bash
php artisan down
```
2. **Download Update**:
```bash
curl -L https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz | tar -xzv
```
3. **Update Dependencies**:
```bash
composer install --no-dev --optimize-autoloader
```
4. **Clear Cache**:
```bash
php artisan view:clear
php artisan config:clear
```
5. **Database Updates**:
```bash
php artisan migrate --seed --force
```
6. **Set Permissions**:
```bash
chown -R www-data:www-data /var/www/pterodactyl/*
```
7. **Restart Queue Workers**:
```bash
php artisan queue:restart
```
8. **Exit Maintenance Mode**:
```bash
php artisan up
```
## Standalone SFTP Server
- **Disable Daemon's SFTP**: Modify your Daemon's `core.json`.
```json
"sftp": {
"enabled": false
}
```
- **Download and Start Standalone Server**:
```bash
curl -Lo sftp-server https://github.com/pterodactyl/sftp-server/releases/download/v1.0.5/sftp-server
chmod +x sftp-server
./sftp-server
```
## Webserver Configuration
- **Remove Default Configuration**: Remove default NGINX configuration.
```bash
rm /etc/nginx/sites-enabled/default
```
- **Create NGINX Configuration File**: Replace `<domain>` with your domain.
```nginx
server {
listen 80;
server_name <domain>;
return 301 https://$server_name$request_uri;
}
```
- **Enable Configuration**: Symlink and restart NGINX.
```bash
sudo ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/pterodactyl.conf
sudo systemctl restart nginx
```
## Community Standards
- **Be Mature**: Maintain maturity and respect in all interactions.
- **Limit Drama**: Avoid negative discussions about others.
- **Be Patient**: Understand that support is community-driven and voluntary.
- **Commercial Services**: Avoid discussing paid services unless noted.
## Terminology
- **Panel**: The Pterodactyl Panel itself.
- **Node**: A machine running an instance of Wings.
- **Wings**: Service interfacing with Docker and the Panel.
- **Server**: A running instance created by the panel.
- **Docker**: Platform for running containerized applications.
- **Nest/Egg**: Configuration for specific games or services.
## Migrating to Wings
1. **Install Wings**:
```bash
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
```
2. **Copy Configuration File**: Create `config.yml` in `/etc/pterodactyl`.
3. **Remove Old Daemon**:
```bash
systemctl stop wings
rm -rf /srv/daemon
apt -y remove nodejs
```
4. **Daemonize Wings**: Update `wings.service` and start Wings.
```systemd
[Unit]
Description=Pterodactyl Wings Daemon
After=docker.service
[Service]
User=root
WorkingDirectory=/etc/pterodactyl
ExecStart=/usr/local/bin/wings
[Install]
WantedBy=multi-user.target
```
## Troubleshooting
### Reading Error Logs
- **Retrieve Logs**:
```bash
tail -n 100 /var/www/pterodactyl/storage/logs/laravel-$(date +%F).log
```
- **Understand Errors**: Focus on the human-readable exception line.
### Cannot Connect to Server Errors
- **Check Wings Status**:
```bash
systemctl status wings
```
- **Browser Console Check**: Use developer tools to inspect errors.
### Invalid MAC Exception
- **Restore `APP_KEY`**: Ensure original `APP_KEY` is restored from `.env`.
### SELinux Issues
- **Allow Redis**:
```bash
audit2allow -a -M redis_t
semodule -i redis_t.pp
```
- **Allow HTTP Port**:
```bash
audit2allow -a -M http_port_t
semodule -i http_port_t.pp
```
## About
### Core Project Team
- **Dane Everitt**: Founder & Former Project Maintainer
- **Matthew Penner**: Project Maintainer
- **Stepan Fedotov**: WHMCS Module Maintainer
- **Michael Parker**: Egg Developer, Docker Integration
### Sponsors
- **Aussie Server Hosts**: High Performance Server Hosting
- **CodeNode LLC**: Affordable hosting with dedicated IPs
- **BisectHosting**: Reliable server hosting since 2012
- **MineStrator**: Highend French hosting company
- **HostEZ**: US & EU Hosting with DDoS Protection
### License
- **MIT License**: Code released under the MIT License.
## Creating SSL Certificates
1. **Install Certbot**:
```bash
sudo apt update
sudo apt install -y certbot python3-certbot-nginx
```
2. **Generate Certificate**:
```bash
certbot certonly --nginx -d example.com
```
3. **Auto Renewal**:
```bash
0 23 * * * certbot renew --quiet --deploy-hook "systemctl restart nginx"
```
4. **Troubleshooting**: Renew certificates and restart services if expired.
```bash
certbot renew
systemctl restart nginx
```
```
```markdown
# Knowledge Base
## Reconfiguring Caddy to Use Cloudflare DNS
### Steps to Create an API Token
1. Under **Zone Resources**, select your DNS zone.
2. Click "Continue to summary".
3. Review the API token summary and click "Create Token".
4. Copy the API token to the clipboard.
### Configuring Caddy
- Create an environment variable file (e.g., `.env`) at `/etc/caddy/.secrets.env`.
- Store the Cloudflare API token:
```env
CLOUDFLARE_API_TOKEN=<your cloudflare api token>
```
- Set permissions to 0600 for security:
```bash
chown caddy:caddy /etc/caddy/.secrets.env
chmod 0600 /etc/caddy/.secrets.env
```
- Modify the systemd unit file at `/etc/systemd/system/caddy.service`:
```ini
[Unit]
Description=Caddy
Documentation=https://caddyserver.com/docs/
After=network.target network-online.target
Requires=network-online.target
[Service]
Type=notify
User=caddy
Group=caddy
ExecStart=/usr/bin/caddy run --environ --envfile /etc/caddy/.secrets.env --config /etc/caddy/Caddyfile
ExecReload=/usr/bin/caddy reload --config /etc/caddy/Caddyfile
TimeoutStopSec=5s
LimitNOFILE=1048576
LimitNPROC=512
PrivateTmp=true
ProtectSystem=full
AmbientCapabilities=CAP_NET_BIND_SERVICE
[Install]
WantedBy=multi-user.target
```
- Add a TLS block to your Caddyfile at `/etc/caddy/Caddyfile`:
```caddyfile
<domain> {
# ...
tls {
dns cloudflare {env.CLOUDFLARE_API_TOKEN}
}
}
```
## Installing Wings | Pterodactyl
### Overview
- Wings is the next-generation server control plane from Pterodactyl.
### Supported Systems
- **Ubuntu**: 20.04, 22.04, 24.04
- **RHEL / Rocky Linux / AlmaLinux**: 8, 9
- **Debian**: 11, 12, 13
- **Windows**: Not supported
### System Requirements
- Requires Linux capable of running Docker containers.
- KVM is guaranteed to work.
- Check virtualization with `systemd-detect-virt`.
### Installing Docker
- Quick install:
```bash
curl -sSL https://get.docker.com/ | CHANNEL=stable bash
```
- Ensure Docker starts on boot:
```bash
sudo systemctl enable --now docker
```
### Setting Up Swap
- For kernels 6.1 or newer, swap is enabled by default.
- Enable swap:
```bash
GRUB_CMDLINE_LINUX_DEFAULT="swapaccount=1"
sudo update-grub
sudo reboot
```
### Installing Wings
- Create directory structure and download Wings:
```bash
sudo mkdir -p /etc/pterodactyl
curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
sudo chmod u+x /usr/local/bin/wings
```
### Configure and Start Wings
- Create a node on the Panel and configure with `config.yml`.
- Start Wings in debug mode:
```bash
sudo wings --debug
```
### Daemonizing Wings
- Create `wings.service` in `/etc/systemd/system`:
```ini
[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
```
- Enable and start Wings:
```bash
sudo systemctl enable --now wings
```
### Node Allocations
- Create allocations via Nodes > Allocation.
- Avoid using 127.0.0.1 for allocations.
## Introduction to Pterodactyl
### Overview
- Pterodactyl is an open-source game server management panel.
- Built with PHP, React, and Go.
- Uses Docker containers for game server isolation.
### Supported Games
- Minecraft, Rust, Terraria, Team Fortress 2, and more.
- Community-supported games include Factorio, FiveM, and others.
### Responsible Disclosure
- Open-source and open to security audits.
- Report concerns to [email protected].
## Upgrading Wings
### Overview
- Upgrading Wings is simple and quick.
### Version Requirements
- Panel and Wings versions must match.
### Steps to Upgrade
1. Stop Wings:
```bash
systemctl stop wings
```
2. Download the updated binary:
```bash
curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
chmod u+x /usr/local/bin/wings
```
3. Restart Wings:
```bash
systemctl restart wings
```
## Setting up MySQL for Pterodactyl
### Creating a Database for Pterodactyl
- Login to MySQL:
```bash
mysql -u root -p
```
- Create a user and database:
```sql
CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'somePassword';
CREATE DATABASE panel;
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1';
```
### Creating a Database Host for Nodes
- Create a MySQL user with permissions:
```sql
CREATE USER 'pterodactyluser'@'127.0.0.1' IDENTIFIED BY 'somepassword';
GRANT ALL PRIVILEGES ON *.* TO 'pterodactyluser'@'127.0.0.1' WITH GRANT OPTION;
```
- Allow external database access by modifying `my.cnf`:
```ini
[mysqld]
bind-address=0.0.0.0
```
## Additional Configuration for Pterodactyl
### Private Registries
- Authenticate against private Docker registries.
### Custom Network Interfaces
- Change network interface for containers.
### Enabling Cloudflare Proxy
- Adjust Wings port for Cloudflare proxy.
### Container PID Limit
- Set the limit for active processes in a container.
### Throttles and Limits
- Customize throttle settings for server output.
### Installer Limits
- Define resource limits for installer containers.
### Other Values
- Configure miscellaneous settings such as debug mode and timeout.
```