YueMi-Development/OpenWebUI-RAG
3
0
Fork 0
Code Issues Pull Requests Releases Activity
Files
main
OpenWebUI-RAG/software/pterodactyl-panel/pterodactyl-docs.md
Muhammad Tamir b54ca14a1e Create pterodactyl-docs.md
2025-11-20 13:30:44 +07:00

21 KiB
Raw Permalink Blame History 

# 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.

# 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
  1. Download Panel Files: Use curl to download the panel files and set permissions. 
    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.

    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.

    cp .env.example .env
COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader

  3. Generate Encryption Key: Generate a new encryption key.

    php artisan key:generate --force

  4. Environment Setup: Configure sessions, caching, and email sending.

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

  5. Database Migration: Set up the database tables.

    php artisan migrate --seed --force

  6. Create Admin User: Create an administrative user.

    php artisan p:user:make

  7. Set File Permissions: Set the correct permissions for the webserver.

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

Queue Listeners

  • Crontab Configuration: Add a cronjob for processing tasks.

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

    sudo dnf update -y

  2. Install Repositories:

    sudo dnf install -y epel-release
sudo dnf install -y https://rpms.remirepo.net/enterprise/remi-release-8.rpm

  3. Enable PHP 8.3:

    sudo dnf module reset php
sudo dnf module enable php:remi-8.3 -y

  4. Install Dependencies:

    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:

    sudo systemctl enable --now mariadb nginx redis

  6. Firewall Configuration:

    sudo firewall-cmd --add-service=http --permanent
sudo firewall-cmd --add-service=https --permanent
sudo firewall-cmd --reload

PHP Configuration

  • Create PHP-FPM Configuration:

    [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:

    sudo systemctl enable --now php-fpm

Additional Configuration

Backups

  • Local Backups: Set the backup driver in .env.

    APP_BACKUP_DRIVER=wings

  • S3 Backups: Configure S3 settings in .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:

    TRUSTED_PROXIES=127.0.0.1

  • NGINX Configuration:

    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:

    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:

    php artisan down

  2. Download Update:

    curl -L https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz | tar -xzv

  3. Update Dependencies:

    composer install --no-dev --optimize-autoloader

  4. Clear Cache:

    php artisan view:clear
php artisan config:clear

  5. Database Updates:

    php artisan migrate --seed --force

  6. Set Permissions:

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

  7. Restart Queue Workers:

    php artisan queue:restart

  8. Exit Maintenance Mode:

    php artisan up

Standalone SFTP Server

  • Disable Daemon's SFTP: Modify your Daemon's core.json.

    "sftp": {
  "enabled": false
}

  • Download and Start Standalone Server:

    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.

    rm /etc/nginx/sites-enabled/default

  • Create NGINX Configuration File: Replace <domain> with your domain.

    server {
  listen 80;
  server_name <domain>;
  return 301 https://$server_name$request_uri;
}

  • Enable Configuration: Symlink and restart NGINX.

    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:

    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:

    systemctl stop wings
rm -rf /srv/daemon
apt -y remove nodejs

  4. Daemonize Wings: Update wings.service and start Wings.

    [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:

    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:

    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:

    audit2allow -a -M redis_t
semodule -i redis_t.pp

  • Allow HTTP Port:

    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:

    sudo apt update
sudo apt install -y certbot python3-certbot-nginx

  2. Generate Certificate:

    certbot certonly --nginx -d example.com

  3. Auto Renewal:

    0 23 * * * certbot renew --quiet --deploy-hook "systemctl restart nginx"

  4. Troubleshooting: Renew certificates and restart services if expired.

    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: 
    chown caddy:caddy /etc/caddy/.secrets.env
chmod 0600 /etc/caddy/.secrets.env
  • Modify the systemd unit file at /etc/systemd/system/caddy.service: 
    [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: 
    <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: 
    curl -sSL https://get.docker.com/ | CHANNEL=stable bash
  • Ensure Docker starts on boot: 
    sudo systemctl enable --now docker

Setting Up Swap

  • For kernels 6.1 or newer, swap is enabled by default.
  • Enable swap: 
    GRUB_CMDLINE_LINUX_DEFAULT="swapaccount=1"
sudo update-grub
sudo reboot

Installing Wings

  • Create directory structure and download Wings: 
    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: 
    sudo wings --debug

Daemonizing Wings

  • Create wings.service in /etc/systemd/system: 
    [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: 
    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: 
    systemctl stop wings
  2. Download the updated binary: 
    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: 
    systemctl restart wings

Setting up MySQL for Pterodactyl

Creating a Database for Pterodactyl

  • Login to MySQL: 
    mysql -u root -p
  • Create a user and database: 
    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: 
    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: 
    [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.